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