Filters
On this page
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.
Overview
What is 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 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 this expression. However, you cannot use MongoDB variables like%%rootbecause App Services applies filters before it reads any data. - An optional query document, which uses standard MongoDB query syntax and 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.
Why Define a Filter?
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:
How App Services Applies Filters
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": "%%user.id" }
If no filter is applied, Atlas App Services will evaluate a role for each
document that the query matches. We know that Atlas 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
Atlas App Services evaluates any roles:
Apply When | Query | Projection |
|---|---|---|
{ "%%true": true } | { "owner_id": "%%user.id" } | {} |
Define a Filter
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 } }
Field | Description | |
|---|---|---|
nameString | Required. The name of the filter. Filter names are
useful for identifying and distinguishing between filters.
Limited to 100 characters or fewer. | |
apply_whenExpression | An expression that determines when this filter applies to an incoming MongoDB operation. Important 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 | |
queryObject Default: {} | A MongoDB query that App Services merges into a filtered operation's existing query. Example A filter withholds documents that have a | |
projectionObject Default: {} | A MongoDB projection that App Services 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 |