Skip to main content
Version: v5

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.

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

Filter.notEqual​

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

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

Filter.greater​

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

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.

Filter.greaterOrEqual('count', 5),

Filter.less​

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

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.

Filter.lessOrEqual('count', 5),

Filter.in_​

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

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.

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

Filter.query​

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

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

Filter.autoComplete​

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

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

Filter.exists​

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

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.

Filter.notExists('name')

Filter.contains​

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

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

Filter.empty​

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

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.

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.

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

Group Queries​

Filter.and​

The 'and' operator combines multiple queries.

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.

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.

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

Did you find this page helpful?