Docs Menu

Filters

On this page

  • Overview
  • What is a Filter?
  • Why Define a Filter?
  • How Realm Applies Filters
  • Define a Filter

A filter modifies an incoming MongoDB query to return only a subset of the results matched by the query. Filters add additional query parameters and omit fields from query results before Realm runs the query.

Every filter has three components:

You can use filters to optimize queries, minimize compute overhead, and secure sensitive data. Filters are most useful for cross-cutting concerns that affect some or all of your queries.

Consider using filters if you want a centralized system to:

  • Restrict queries to a subset of all documents
  • Omit sensitive data or unused fields
Example

In a voting app where some users have agreed to anonymously share their vote, you could use the following filter to constrain all queries to an anonymous subset of the existing data:

Realm evaluates and applies filters for every MongoDB request where rules apply, e.g. an SDK or a function run as a specific user. Multiple filters may apply to a single request.

A filter applies to a given request if its Apply When expression evaluates to true given that request's context. If a filter applies to a request, Realm merges the filter's query or projection into the requested operation's existing query and projection.

Realm applies filters to the request before it sends the request to MongoDB.

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" }
{}

You define filters for specific collections in your linked cluster.

Note

To learn how to configure and deploy a filter in your app, see Filter Incoming Queries.

A filter configuration has the following form:

{
"name": "<Filter Name>",
"apply_when": { Expression },
"query": { MongoDB Query },
"projection": { MongoDB Projection }
}
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
Expression

An expression that determines when this filter applies to an incoming MongoDB operation.

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
Object
Default: {}

A MongoDB query that Realm merges into a filtered operation's existing query.

Example

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

{ "score": { "$gte": 20 } }
projection
Object
Default: {}

A MongoDB projection that Realm merges into a filtered operation's existing projection.

Important
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 withholds the _internal field from all documents using the following projection:

{ "_internal": 0 }
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.