Credential:  
None
  • None
  • Manage Credentials
Launch IDE ↗

Stitch API

4.8. 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 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 (eq) current.

Combining Operators

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" 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:

Operators
NameDescription
eqEqual to
neqNot equal to
inAccepts a set of possible values and checks if the field value is a member of the set
ninNot 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:

Operators
NameDescription
gtGreater than
gteGreater than or equal to
ltLess than
lteLess than or equal to

Retrieving incoming transactions using the gt operator

This filter is designed to only show money coming into the specified bank account, by using the greater than or gt operator:

Regex and Glob

For string scalar types such as String and EmailAddress, there are two additional operators regex and glob. Both 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 is a literal telling the glob compiler to match on that exact sequence of characters.

Regex

A 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.

Stitch's regex filter is interpreted by the V8 JavaScript Engine and so a handy tool to test your expression out 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 also include a small set of operators:

Operators
NameDescription
lengthAn operator which allows you to filter on the list length
everyAn operator which passes if every element in the subfilter matches
anyAn operator which passes if any element in the subfilter 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 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.

Performance Considerations

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