# 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
```