Filter Incoming Queries¶

On this page

Overview
Procedure

Overview¶

You can define filters on incoming queries that Stitch evaluates and applies before its initial query to your MongoDB cluster. Adding a filter to a collection allows you to control the shape of queried documents using projection filters and can improve query performance by reducing the number of documents for which Stitch needs to evaluate a role.

Every filter consists of an Apply When JSON expression and a Filter Query document. When Stitch receives an incoming MongoDB query, it evaluates the Apply When expression of all filters on the collection and merges the Filter Query document into the incoming query.

This guide walks through creating one or more query filters for a collection.

Note

This guide requires a linked MongoDB Atlas cluster.

Procedure¶

Stitch UI
Import/Export

1

Navigate to the MongoDB Rules Screen¶

You can create and manage query filters from the MongoDB rules screen in the Stitch UI. To get to the rules screen, click Rules beneath MongoDB Clusters in the left-hand navigation.

2

Create a New Filter¶

Select the collection that you want to configure a filter for from the Rules menu then click the Filters tab. Click New Filter and enter a Name for the new filter.

3

Specify the Apply When Expression¶

In the Apply When input box, enter a JSON expression that defines when the filter applies to a query. If the expression evaluates to true for an incoming query, Stitch adds the Filter Query parameters to the incoming query.

Important

Stitch 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 %%true, %%user, and %%values.

4

Specify the Filter Query Predicates¶

In the Query input box, specify a document that contains additional query predicates to merge into the incoming query when the filter applies. For example, a filter that withholds documents that have a score below 20 could use the following filter query:

copy

{ "score": { "$gt": 20 } }

5

Specify the Filter Projection¶

In the Projection input box, specify a document that contains a projection document to merge into the incoming query when the filter applies.

For example, a filter that withholds the career_stats and personal fields from documents could use the following filter projection:

copy

{
  "career_stats": 0,
  "personal": 0
}

6

Save the Filter¶

After you have configured the Filter Query and the Apply When expression, click Save. After saving, Stitch immediately begins evaluating and applying filters to incoming queries on the collection.

1

Export Your Stitch Application¶

To define query filters with stitch-cli you need to export an application directory for your application.

You can export your application from the Export tab of the Settings page in the Stitch UI, or by running the following command from an authenticated instance of stitch-cli:

copy

stitch-cli export --app-id=<App ID>

2

Add a Rule Configuration File¶

The rules for a MongoDB collection are configured in the rules subdirectory of the linked cluster’s service directory. The rules configuration file is a JSON file with the same name as the collection namespace. For example, the rules for the collection app.users in the mongodb-atlas cluster are defined in the file /services/mongodb-atlas/rules/app.users.json.

If you have not configured rules for the collection, add a configuration file for it to the rules directory:

copy

touch services/<cluster name>/rules/<db>.<collection>.json

The configuration file should have the following general form:

copy

{
  "roles": [],
  "filters": [],
  "schema": {}
}

Note

This guide focuses on creating filters for the collection. Check out the other configuration guides to learn how to define roles and permissions and enforce document schemas.

3

Add One or More Filters¶

Add a document to the filters array for each filter that you want to configure. Filter documents have the following form:

copy

{
  "name": "<Filter Name>",
  "apply_when": <JSON Expression>,
  "query": <Query Document>,
  "projection": <Projection Document>
}

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`	Required. A JSON expression that determines when this filter applies to a given query. Important Stitch 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 `%%true`, `%%user`, and `%%values`.
`query` Document	Required. A MongoDB query filter that contains additional query predicates to merge into incoming queries that the filter applies to. Example A filter that withholds documents that have a `score` below `20` could use the following filter query: copy { "score": { "$gt": 20 } }
`projection` Document	Required. A MongoDB projection document that specifies additional field projections to merge into incoming queries that the filter applies to. 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 that withholds the `_internal` field from all documents could use the following filter projection: copy { "_internal": 0 }

4

Import Your Application Directory¶

Once you’ve added the filter configurations to the collection rule configuration file, all that’s left is to import the rule.

Ensure that the rule configuration file is saved then navigate to the root of the exported application directory. Log in to MongoDB Atlas with stitch-cli:

copy

stitch-cli login --username="<MongoDB Cloud Username>" --api-key="<MongoDB Cloud API Key>"

Once you’re logged in, import the directory:

copy

stitch-cli import

Once the import completes, Stitch will immediately begin evaluating and applying the filters to incoming queries on the collection.

← Define Roles And Permissions Enforce a Document Schema →