---
id: understanding_filters
sidebar_position: 10
title: Understanding Filters
---

Understanding Filters

### Introduction

Filters are used to get a specific subset of objects (channels, users, messages, members, etc) which
fit the conditions specified. Earlier versions of the SDK contained String-based filters which are now replaced by type-safe
filters. This guide aims to explain the different types of filters and how to use them.

### Types Of Filters

#### Filter.equal

The 'equal' filter gets the objects where the given key has the specified value.

```dart
Filter.equal('type', 'messaging'),
```

#### Filter.notEqual

The 'notEqual' filter gets the objects where the given key does not have the specified value.

```dart
Filter.notEqual('type', 'messaging'),
```

#### Filter.greater

The 'greater' filter gets the objects where the given key has a higher value than the specified value.

```dart
Filter.greater('count', 5),
```

#### Filter.greaterOrEqual

The 'greaterOrEqual' filter gets the objects where the given key has an equal or higher value than the specified value.

```dart
Filter.greaterOrEqual('count', 5),
```

#### Filter.less

The 'less' filter gets the objects where the given key has a lesser value than the specified value.

```dart
Filter.less('count', 5),
```

#### Filter.lessOrEqual

The 'lessOrEqual' filter gets the objects where the given key has a lesser or equal value than the specified value.

```dart
Filter.lessOrEqual('count', 5),
```

#### Filter.in_

The 'in_' filter allows getting objects where the key matches any in a specified array.

```dart
Filter.in_('members', [user.id])
```

:::note
Since 'in' is a keyword in Dart, the filter has an underscore added. This does not apply to the 'notIn'
keyword.
:::

#### Filter.notIn

The 'notIn' filter allows getting objects where the key matches none in a specified array.

```dart
Filter.notIn('members', [user.id])
```

#### Filter.query

The 'query' filter matches values by performing text search with the specified value.

```dart
Filter.query('name', 'demo')
```

#### Filter.autoComplete

The 'autoComplete' filter matches values with the specified prefix.

```dart
Filter.autoComplete('name', 'demo')
```

#### Filter.exists

The 'exists' filter matches values that exist, or don't exist, based on the specified boolean value.

```dart
Filter.exists('name')
```

#### Filter.notExists

The 'notExists' filter checks if the specified key doesn't exist. This is a simplified call to `Filter.exists`
with the value set to false.

```dart
Filter.notExists('name')
```

#### Filter.contains

The 'contains' filter matches any list that contains the specified value.

```dart
Filter.contains('teams', 'red')
```

#### Filter.empty

The 'empty' filter constructor returns an empty filter. It's the equivalent of an empty map `{}`;

```dart
Filter.empty();
```

#### Filter.raw

The 'raw' filter constructor lets you specify a raw filter. We suggest using this only if you can't manage to build what you want using the other constructors.

```dart
Filter.raw(value: {
  'members': [
    ..._selectedUsers.map((e) => e.id),
    chatState.currentUser!.id,
  ],
  'distinct': true,
});
```

#### Filter.custom

The 'custom' filter is used to create a custom filter in case it does not exists or it's not been added to the SDK yet.
Note that the filter must be supported by the Stream backend in order to work.

```dart
Filter.custom(
  operator: '\$max',
  value: 10,
)
```

### Group Queries

#### Filter.and

The 'and' operator combines multiple queries.

```dart
final filter = Filter.and([
     Filter.equal('type', 'messaging'),
     Filter.in_('members', [user.id])
])
```

#### Filter.or

Combines the provided filters and matches the values matched by at least one of the filters.

```dart
final filter = Filter.or([
     Filter.in_('bannedUsers', [user.id]),
     Filter.in_('shadowBannedUsers', [user.id])
])
```

#### Filter.nor

Combines the provided filters and matches the values not matched by all the filters.

```dart
final filter = Filter.nor([
     Filter.in_('bannedUsers', [user.id]),
     Filter.in_('shadowBannedUsers', [user.id])
])
```
