Filters
Understanding Filters
#
IntroductionFilters 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.equalThe 'equal' filter gets the objects where the given key has the specified value.
Filter.equal('type', 'messaging'),
#
Filter.notEqualThe 'notEqual' filter gets the objects where the given key does not have the specified value.
Filter.notEqual('type', 'messaging'),
#
Filter.greaterThe 'greater' filter gets the objects where the given key has a higher value than the specified value.
Filter.greater('count', 5),
#
Filter.greaterOrEqualThe 'greaterOrEqual' filter gets the objects where the given key has an equal or higher value than the specified value.
Filter.greaterOrEqual('count', 5),
#
Filter.lessThe 'less' filter gets the objects where the given key has a lesser value than the specified value.
Filter.less('count', 5),
#
Filter.lessOrEqualThe '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.notInThe 'notIn' filter allows getting objects where the key matches none in a specified array.
Filter.notIn('members', [user.id])
#
Filter.queryThe 'query' filter matches values by performing text search with the specified value.
Filter.query('name', 'demo')
#
Filter.autoCompleteThe 'autoComplete' filter matches values with the specified prefix.
Filter.autoComplete('name', 'demo')
#
Filter.existsThe 'exists' filter matches values that exist, or don't exist, based on the specified boolean value.
Filter.exists('name')
#
Filter.notExistsThe '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.containsThe 'contains' filter matches any list that contains the specified value.
Filter.contains('teams', 'red')
#
Filter.emptyThe 'empty' filter constructor returns an empty filter. It's the equivalent of an empty map {}
;
Filter.empty();
#
Filter.rawThe '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.customThe '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.andThe 'and' operator combines multiple queries.
final filter = Filter.and([
Filter.equal('type', 'messaging'),
Filter.in_('members', [user.id])
])
#
Filter.orCombines 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.norCombines 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])
])