Docs Menu

Docs HomeAtlas App Services

Filter Incoming Queries

On this page

  • Overview
  • How App Services Applies Filters
  • Define Filters
  • Procedure

A filter modifies an incoming MongoDB query to return only a subset of the results matched by the query. Adding a filter to a collection allows you to control the shape of queried documents and can improve query performance.

Filters add additional query parameters and omit fields from query results before Atlas App Services runs the query. Every filter has three components:

App Services evaluates and applies filters for all MongoDB requests where rules apply except Device Sync requests. Examples of filterable MongoDB requests include:

  • A query on a collection.

  • A write to a document.

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, App Services merges the filter's query or projection into the requested operation's existing query and projection.

Multiple filters may apply to a single request.

App Services applies filters to the request before it sends the request to MongoDB.


A collection contains several million documents and has one role with the following "apply when" expression:

{ "owner_id": "" }

If no filter is applied, App Services will evaluate a role for each document that the query matches. We know that App Services 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 App Services evaluates any roles:

Apply When
{ "%%true": true }
{ "owner_id": "" }

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


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:

You can define filters for specific collections in your linked cluster from the App Services UI or by deploying configuration files with Realm CLI:


This guide requires a linked MongoDB Atlas data source.


Security Consideration for App Services Filters

While Role-based Permissions and Filters can hide specific documents and fields within a collection there is a potential that data can be exposed if the system allows arbitrary queries to access the collection.

For example, queries or functions that raise errors depending on the values stored in a collection (such as division-by-zero errors) may reveal information about documents, even if a role or filter prevents the querying user from viewing documents directly. Users may also make inferences about the underlying data in other ways (such as by measuring query execution time, which can be affected by the data's distribution).

Be aware that this is possible and audit your data access patterns where neccessary.

←  Rule ExpressionsDevice Sync-Compatible Permissions →