MongoDB Atlas Overview


Stitch provides a first-class service interface for MongoDB Atlas that lets you securely query one or more Atlas clusters. You can use standard MongoDB query language syntax to access your data directly in your client application code or from a Stitch Function.

The MongoDB service secures your data with a dynamic, role-based Rules engine that proxies and modifies incoming queries based on rules that you define. There are three types of MongoDB collection rules: roles, filters, and document schemas.

Advanced MongoDB Queries

Stitch does not support all MongoDB CRUD and Aggregation operations when you query MongoDB as a specific user. You can bypass this limitation by querying MongoDB from a Function that runs as a system user, which has access to the full MongoDB CRUD and Aggregation APIs.

For more information on which features are unsupported, see MongoDB Service Limitations.

Get Started

To get started with the MongoDB service, link a cluster to your application and define roles and permissions for a collection. After you’ve created at least one role, you can start to work with data in the collection.

The following guides demonstrate how to work with data:



Whenever Stitch receives a MongoDB query, it handles the request by applying rules that you define in the following 4-step process:


Find All Relevant Documents

Stitch evaluates filters that you define and adds relevant query filters to the incoming query document. It then finds all documents that match the filtered query.


Evaluate A Role For Each Document

Stitch evaluates a role with specific read and write permissions for each document that matches the filtered query. You define the roles for each collection, including what permissions they have and when they apply.


Run The Query With The Assigned Roles

Once Stitch has evaluated a role for each document, it runs the filtered query and prevents reads and writes on each document unless the document’s role allows them. If no role applies to a specific document, Stitch withholds that document entirely and prevents the query from reading or writing any fields.


Validate The Document Schema

If the query was a write operation, Stitch checks each affected document to ensure that they conform to the collection’s document schema. If any documents do not match the schema, Stitch rolls back the operation and rejects the query.

Roles and Permissions

A role is a group of document-level and field-level permissions that apply to documents in a specific collection. Roles define what the user who issued a query is allowed to do with a particular document, including which fields they can read and write to. Each collection can have multiple role definitions that might apply to a user.

When Stitch receives a query request, it determines which documents in the collection the query applies to and evaluates a separate role for each document. To assign a role to a document, Stitch steps through each role definition in order and evaluates the Apply When JSON expression that you defined for the role. If a role’s Apply When expression evaluates to true, Stitch assigns the role to the current document and moves on to the next document. If the expression evaluates to false, Stitch evaluates the next role definition. If no roles apply to a document, Stitch withholds the entire document and prevents any modifications.

Query Filters

A query filter conditionally applies additional query predicates to incoming queries before Stitch sends them to a MongoDB cluster. Filters are useful for improving the performance of queries on collections that have many documents or roles that use complex Apply When expressions. Each filter consists of its own Apply When expression and a query document that is combined with incoming queries that the filter applies to.

You can add filters to a collection to remove documents that you know ahead of time are not relevant to incoming queries. This can help to reduce the number of roles that Stitch needs to evaluate for each request. Filters can take advantage of indexes in a linked MongoDB cluster, so filtering out a document is generally faster than waiting for Stitch to evaluate a role for it.


A collection contains several million documents and has one role with the following Apply When expression:

{ "owner_id": "" }

If no filter is applied, Stitch will evaluate a role for each document that the query matches. We know that Stitch will withhold any document that does not have the user’s id as the value of the owner_id field, so we can save time and compute resources by applying the following query filter to exclude those documents before Stitch evaluates any roles:

When Filter Query
{ "%%true": true } { "owner_id": "" }

Document Schemas

A document schema is a JSON object that allows you to define the shape and content of documents and embedded documents in a collection. You can use a schema to require a specific set of fields, configure the content of a field, or to validate changes to a document based on its beginning and ending states.

Stitch evaluates the result of all document writes (inserts and updates) and compares them against the schema before committing the writes to your cluster. If the result of a write operation does not match the schema, Stitch will roll back the write operation and return an error to the user.


Document schemas use the same JSON schema as the document validation built in to the MongoDB server.


A collection has the following document schema:

  "properties": {
    "_id": { "bsonType": "objectId" },
    "name": { "bsonType": "string" }

A user with permission to read and write all fields wants to update the name field of a particular document. They issue the following query:

  { "_id": "5ae782e48f25b9dc5c51c4d0" },
  { "$set": { "name": 42 } }

The query attempts to set the value of name to the number 42, but the schema requires the value to be a string. Stitch will reject this write operation even though the user had permission to update the document because the write result does not conform to the schema.


System-Generated Cluster Users

Stitch automatically creates a MongoDB user for each app linked to a cluster. These users are for internal use only and cannot be edited or manually deleted. If you delete a Stitch app, the associated user will also be deleted.

Users generated by Stitch have names of the form: mongodb-stitch-<your app id>

Accessing Application Data with Another Tool

Stitch connects to standard MongoDB Atlas clusters, which means that you can connect directly to a linked cluster using another tool such as the mongo shell or MongoDB Compass. There are no special considerations when reading data from a linked cluster with another tool.

While running update operations, Stitch temporarily adds a reserved field, _id_stitch_transaction, to documents. Once a document is successfully updated, Stitch removes this field. If you want to use another tool to modify data in a collection, ensure that you $unset this field prior to making changes.

For example, if you are using the mongo shell to update documents in the products collection, your command might resemble the following code:

   { sku: "unknown" },
   { $unset: { _id_stitch_transaction: "" } }