Navigation

Query Filters

Overview

A MongoDB query filter conditionally applies additional query predicates to incoming queries before Stitch runs them. Filters are useful for improving the performance of queries on collections that have many documents or roles that use complex Apply When expressions.

You can add filters to a collection to remove documents that you know are not relevant to incoming queries before Stitch evaluates any roles. This can help to reduce the amount of computation that Stitch needs to perform for a request. Filters can take advantage of indexes in a linked MongoDB cluster, so filtering out a document is generally faster than waiting for Stitch to evaluate a role for it.

Filter Application Process

When Stitch receives a query request, it determines if any filters associated with the collection apply to the request and adds those to the query. To assign filters to a query, Stitch evaluates the Apply When JSON expression that you defined for each filter. If a filter’s Apply When evaluates to true, Stitch merges the Filter Query into the incoming query document.

Example

A collection contains several million documents and has one role with the following Apply When expression:

{ "owner_id": "%%user.id" }

If no filter is applied, Stitch will evaluate a role for each document that the query matches. We know that Stitch will withhold any document that does not have the user’s id as the value of the owner_id field, so we can save time and compute resources by applying the following query filter to exclude those documents before Stitch evaluates any roles:

Apply When Filter Query
{ "%%true": true } { "owner_id": "%%user.id" }

Query Filter Configuration

{
  "name": "<Filter Name>",
  "apply_when": <JSON Expression>,
  "query": <Query Document>
}
Field Description
name Required. The name of the filter. Filter names are useful for identifying and distinguishing between filters. Limited to 100 characters or fewer.
apply_when

Required. A JSON expression that determines when this filter applies to a given query.

Important

Stitch evaluates and applies filters before it reads any documents, so you cannot use MongoDB document expansions in a filter’s Apply When expression. However, you can use other expression variables such as %%true, %%user, and %%values.

query

Required. A MongoDB query filter that contains additional query predicates to merge into incoming queries that the filter applies to.

Example

A filter that withholds documents that have a score below 20 could use the following filter query:

{ "score": { "$gt": 20 } }