Docs Home → Atlas App Services
Filter Incoming Queries
Overview
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:
An "apply when" expression that determines if the filter applies to an incoming request. You can use variables like
%%userand%%requestin the "apply when" expression. However, you cannot use expansions that refer to a document like%%rootbecause App Services evaluates the "apply when" expression before reading any documents.An optional query expression, which merges with the existing query of any request the filter applies to.
An optional projection document, which uses standard MongoDB projection syntax and merges with the existing projection of any request the filter applies to.
How App Services Applies Filters
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.
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, 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 | Query | Projection |
|---|---|---|
{ "%%true": true } | { "owner_id": "%%user.id" } | {} |
Define Filters
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:
Procedure
You can define filters for specific collections in your linked cluster from the App Services UI or by deploying configuration files with Realm CLI:
Note
This guide requires a linked MongoDB Atlas data source.