# Filters

### Overview

When querying logs, traces, and events in groundcover, you can filter data to narrow the scope of results returned. Filters use a simple `field:value` syntax and support wildcards, numeric comparisons, and logical operators.

{% hint style="info" %}
Filtering syntax applies across all native groundcover pages - Logs, Traces, and Events as well as in the Data Explorer, Dashboards, and Monitors.
{% endhint %}

### Basic Filtering

#### Exact Match

Match a specific value in a field.

```
level:error
```

```
workload:auth-service
```

```
status_code:500
```

When the value contains spaces, use quotes:

```
error:"failed to authenticate user"
```

#### Numeric Comparisons

Compare numeric fields using `>`, `<`, `>=`, `<=`, `=`.

```
duration_seconds:>1000
```

```
status_code:>=500
```

Combine operators to create ranges:

```
status_code:>=200 status_code:<300
```

#### Free Text Search

Search across all fields without specifying a field name.

```
error
```

Search for a phrase:

```
"connection refused"
```

### Wildcard Filtering

Wildcard filters allow pattern matching within string fields.

#### Prefix Match

Match values starting with a string using `*` at the end.

```
workload:auth*
```

*Matches: auth-service, auth-api, authentication*

#### Suffix Match

Match values ending with a string using `*` at the start.

```
workload:*-service
```

*Matches: auth-service, payment-service, user-service*

#### Substring Match

Match values containing a string using `*` on both sides or the `~` operator.

```
workload:*auth*
```

*Matches: oauth-service, authentication, authorize-api*

### Field Existence

#### Field Has Any Value

Match records where a field exists with any non-empty value.

```
trace_id:"*"
```

*All records with a trace\_id*

```
error:"*"
```

*All records with an error field*

#### Field Is Empty

Match records where a field is empty.

```
error:""
```

*Records with no error*

#### Field Does Not Exist

Use negation with the any value filter to match records where a field doesn't exist.

```
-trace_id:"*"
```

*Records without a trace\_id field*

### Negation

Exclude results by prefixing with `-`.

```
-level:debug
```

*Exclude debug logs*

```
-"expected error"
```

*Exclude this phrase from results*

### Boolean Filtered Queries

Combine multiple filters using logical operators.

#### Implicit AND

Multiple filters on different fields are automatically combined with AND.

```
level:error namespace:production
```

Returns logs where level = error and namespace = production.

#### Implicit OR (Same Field)

**Important:** Multiple filters on the same field without an explicit operator are automatically combined with OR. This is different from LogsQL's behavior.

```
level:error level:warn level:fatal
```

*Equivalent to: level:error OR level:warn OR level:fatal*

#### Explicit AND

Use `AND` to explicitly combine conditions.

```
level:error AND namespace:production
```

#### Explicit OR

Use `OR` to match records satisfying any condition.

```
level:error OR level:fatal
```

#### NOT

Use `NOT` to explicitly negate a condition (equivalent to `-` prefix).

```
NOT level:debug
```

*Same as: -level:debug*

```
workload:api NOT (level:debug OR level:trace)
```

*API logs excluding debug and trace*

#### Parentheses

Use parentheses to control operator precedence.

```
(level:error OR level:fatal) AND namespace:production
```

*Critical issues in production*

Complex nested logic:

```
(namespace:prod-east OR namespace:prod-west) AND 
(level:error OR level:fatal) AND 
NOT (workload:*test* OR workload:*health*)
```

### Differences from LogsQL

groundcover Query Language is influenced by LogsQL but has important differences:

#### Case Sensitivity

**groundcover:** Case-insensitive by default

```
level:error
level:ERROR
level:Error
```

*All three match the same records*

For case-sensitive matching, use `:=`:

```
level:="ERROR"
```

**LogsQL:** Case-sensitive by default

#### Implicit OR on Same Field

**groundcover:** Multiple filters on the same field are automatically combined with OR

```
level:error level:warn
```

*Automatically becomes: level:error OR level:warn*

**LogsQL:** Requires explicit OR operator

```
level:error OR level:warn
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/querying-your-groundcover-data/groundcover-query-language/filters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.