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])
])