Navigation

Query Filters

Overview

A MongoDB query filter conditionally applies additional query predicates and projections to an incoming query before MongoDB Realm runs the query. 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 MongoDB Realm evaluates any roles. This can help to reduce the amount of computation that MongoDB Realm needs to perform for a request. Filters can take advantage of indexes in a linked MongoDB Atlas cluster, so filtering out a document is generally faster than waiting for MongoDB Realm to evaluate a role for it.

Filter Application Process

When MongoDB Realm 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, MongoDB Realm evaluates the Apply When JSON expression that you defined for each filter. If a filter’s Apply When evaluates to true, MongoDB Realm 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, MongoDB Realm will evaluate a role for each document that the query matches. We know that MongoDB Realm will withhold any document that does not have the user’s id as the value of the owner_id field, so we save time and compute resources by applying an additional query predicate that excludes those documents before MongoDB Realm evaluates any roles:

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

Query Filter Configuration

{
  "name": "<Filter Name>",
  "apply_when": <JSON Expression>,
  "query": <Query Document>,
  "projection": <Projection Document>
}
Field Description
name
String
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

MongoDB Realm 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 %%user, %%values, and %function.

query
Document

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 } }
projection
Document

Required. A MongoDB projection document that specifies additional field projections to merge into incoming queries that the filter applies to.

Projection Conflicts

MongoDB projections can be either inclusive or exclusive, i.e. they can either return only specified fields or withhold fields that are not specified. If multiple filters apply to a query, the filters must all specify the same type of projection, or the query will fail.

Example

A filter that withholds the _internal field from all documents could use the following filter projection:

{ "_internal": 0 }