Stitch provides a comprehensive filtering API. Most collections of items may be filtered, such as bank accounts, transactions and debit orders.
The API was loosely inspired by MongoDB selectors but made changes to improve ergonomics and account for the recursive nature of GraphQL.
Here is an example of how to filter bank accounts so that only current accounts are shown:
Breaking this down, we can see that we're providing a filter that requires that the account type equals (
A filter can have more than one operator. If more than one operator is provided, all the conditions much mach for an element to pass through the filter.
Extending our previous example, let us add an additional condition, that we want the account name
to contain the string
"private" by using the glob operator:
Filters can also contain operators nested within a subfield. As before, all leaf operators have to match for a value to pass through the filter.
Here is a query that filters bank accounts by account holder type:
All leaf fields support the following equality and set operators:
|Not equal to|
|Accepts a set of possible values and checks if the field value is a member of the set|
|Not In. Accepts a set of possible values and checks if the field value is not a member of the set|
For types that have a natural ordering, such as
UInt, the filtering API provides the following
set of comparison operators:
|Greater than or equal to|
|Less than or equal to|
This filter is designed to only show money coming into the specified bank account, by using the greater than or
For string scalar types such as
EmailAddress, there are two additional operators
Both these operators can be used to match patterns in the strings.
A glob is a simple means of creating a filter that can match strings using wildcards.
If you've ever seen a string in an app that looks like this:
**/*.js, then you've seen a glob.
We'd generally recommend a choosing a
glob over a
regex if possible, as they are simpler to write
and read, though they are not quite as expressive.
Stitch uses the library micromatch to compile globs to regular expressions, which means that it supports all the features that micromatch does.
Looking at the example above, we used the glob
"*[Pr]rivate*", to match account names containing the string
* character at the beginning and end of the glob is known as a wildcard and matches zero or more instances of any character.
[Pp] means match on either the character
rivate is a literal telling the glob compiler to match on that exact sequence of characters.
regex is a widely used mechanism to specify patterns in strings. While the general form of regular expressions
is largely similar across programming languages, there are also a number of platform specific differences.
A query using a regex instead of the glob in the previous section would look as follows:
While not leaf fields, lists also include a small set of operators:
|An operator which allows you to filter on the list length|
|An operator which passes if every element in the subfilter matches|
|An operator which passes if any element in the subfilter matches|
Filtering on union types can be performed by adding a sub-filter under the name of the concrete type.
For example the query below has a sub-filter on the
accountHolder field, requiring that the return type is an
Within the subfilter, we are matching on the
identifyingDocument field, where we are encoding the requirement
that the identifying document is a South African ID.
If the accountHolder is a business, or the identifying document cannot be found, or is a passport or non South African ID, then the filter will not match.
Using filters may have a performance impact on your query. This is for two major reasons:
If a field appears in a filter, but is not requested in the query, the field data will need to be retrieved. For deeply nested or complicated filters, this may mean that a lot more work needs to done to resolve the query.
For paginated queries with filters, the Stitch API will attempt to honour the provided pagination parameters (such as the
This may mean that the backend may need to fetch several pages of results to resolve a single query.
In order to ensure bounded response times, the filter will limit the total number of pages seen per query. The page size is dynamically adjusted based on a filter leniency score.
Due to the tradeoff of favouring more predictable response times over number of results, a query may return zero results, even if there exist more pages in the collection
There are a few main limitation to consider when building a filter query.
The first is that you cannot use the list operators on paginated fields, since these fields don't have a known finite set of items and hence are difficult to reason about.
The second limitation is that Stitch does not currently provide
not operators. Rethinking your logic, making multiple queries or using a field alias
may be possible alternatives. This is not an inherent limitation, so if you have a use case that requires more complicated boolean logic, please let us know.
The final limitation is that filtering on fields that return interfaces can only be performed on fields explicitly declared in the interface type.