Docs Menu

Docs HomeAtlas App Services


On this page

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


The content in this section only applies when Atlas Device Sync is not enabled. For information about configuring permissions when using Sync, see Sync Rules and Permissions.

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 Atlas App Services 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


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:

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

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 define filters for specific collections in your linked cluster.


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 }
Required. The name of the filter. Filter names are useful for identifying and distinguishing between filters. Limited to 100 characters or fewer.

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


Atlas App Services 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 expansions like %%user, %%values, and %function

Default: {}

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


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

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

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


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.


A filter withholds the _internal field from all documents using the following projection:

{ "_internal": 0 }
←  Role-based PermissionsRule Expressions →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.