Filtering
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 it includes changes to improve the 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 (eq) current.
Combining Operators
A filter can have more than one operator. If more than one operator is provided, all the conditions must match for an element to pass through the filter.
Extending our previous example, let us add a condition: we want to ensure the account name contains the string "Private"
or "private" by using the glob operator:
Nesting
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:
Equality and Set Operators
All leaf fields support the following equality and set operators:
| Name | Description |
|---|---|
eq | Equal to |
neq | Not equal to |
in | Accepts a set of possible values and checks if the field value is a member of the set |
nin | Not In. Accepts a set of possible values and checks if the field value is not a member of the set |
Using the in operator to list current and savings accounts
Comparison Operators
For types that have a natural ordering, such as Int, Date, Decimal, and UInt,
the filtering API provides the following set of comparison operators:
| Name | Description |
|---|---|
gt | Greater than |
gte | Greater than or equal to |
lt | Less than |
lte | Less than or equal to |
Retrieving incoming transactions using the gt operator
With this filter, you can show only money coming into the specified bank account.
Regex and Glob
For string scalar types such as String and EmailAddress, there are two additional
operators: regex and glob. Both of these operators can be used to match patterns in the strings.
Glob
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
private or Private.
The * 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 P or p.
Finally rivate tells the glob compiler to match on that exact sequence of characters.
Regex
A regex is a widely used mechanism that specifies patterns in strings. While the general form of regular expressions is
largely similar across programming languages, there can be a number of platform-specific differences.
Stitch's regex filter is interpreted by the V8 JavaScript Engine. A handy tool to test your expression is regexr.com.
A query using a regex instead of the glob in the previous section would look as follows:
Filtering on Lists
While not leaf fields, lists include a small set of operators:
| Name | Description |
|---|---|
length | An operator which allows you to filter on the list length |
every | An operator which passes if every element in the sub-filter matches |
any | An operator which passes if any element in the sub-filter matches |
Filtering on Union Types
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 Individual.
Within the sub-filter, 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.
Performance Considerations
Using filters may have a performance impact on your query
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 be done to resolve the query.
For paginated queries with filters, the Stitch API will attempt to honour the provided pagination parameters (such as the first argument).
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.
Limitations
There are a few main limitations to consider when building a filter query.
The first limitation is that you cannot use the list operators on paginated fields, as these fields don't have a known, finite set of items. And hence they are difficult to reason about.
The second limitation is that Stitch does not currently provide or or 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.