Merge pull request #615 from GetStream/understanding_filters

docs(doc): Understanding filters
2021-08-13 12:04:07 +05:30
parent 14c73a3c55 a928bea125
commit d963bafef2
1 changed files with 143 additions and 0 deletions
@@ -0,0 +1,143 @@
+---
+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', true)
+```
+
+### 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])
+])
+```