Docs Menu

Flexible Sync

On this page

  • Overview
  • Queryable Fields
  • Eligible Field Types
  • Reserved Field Names
  • Performance and Storage
  • Get Started with Flexible Sync
  • Define a Schema
  • Enable Sync
  • Create Queries in Your Client Application
  • Optimize Sync with Asymmetric Sync (Optional)

Atlas App Services Flexible Sync lets you define a query in the client, and sync only the objects that match the query. With client-side subscriptions, client applications can:

  • Maintain queries
  • React to changes
  • Add, change, or delete queries

Together with rules and permissions, Flexible Sync provides a powerful way to configure Sync around your business logic.

See also:

For a guide to setting up flexible sync with common permissions models, see Flexible Sync Permissions Guide.

When a client makes a query, App Services searches the server-side data set for documents matching the query. Then, the sync engine applies a set of rules to determine which documents in the results set the user should be able to access. App Services returns only the matching documents where the user has read or read/write access, and assigns the user the appropriate permissions.

Client applications can add, update, or remove queries dynamically at run-time from the device.

Flexible Sync Prerequisites

Enabling Flexible Sync in Your App Services Application requires a non-sharded MongoDB Atlas cluster running MongoDB 5.0 or greater

When you configure Flexible Sync, you specify one or more fields from your Sync Schema that your client application can query.


In a task tracker app, you might set assignee or owner as queryable fields. On the client side, you can then query for tasks whose assignee or owner matches the logged-in user.

Queryable fields apply across all collections in an App's Sync Schema. You can use rules and permissions to configure more granular access control on individual collections.

Flexible Sync only supports top-level primitive fields with a scalar type as queryable fields. You can also include arrays of these primitives as queryable fields. Flexible Sync does not support embedded objects or arrays of objects as queryable fields.

See also: Realm Query Language - Flexible Sync Limitations

For information on the queries you can perform on these fields, see: Flexible Sync RQL Limitations

App Services reserves some keywords for the Realm Query Language and other purposes. You cannot use reserved keywords as field names.

App Services reserves the following keywords with any capitalization:

  • and
  • asc
  • ascending
  • beginswith
  • between
  • contains
  • desc
  • descending
  • distinct
  • endswith
  • falsepredicate
  • inf
  • infinity
  • like
  • limit
  • nan
  • nil
  • null
  • or
  • sort
  • subquery
  • truepredicate

You cannot use descending, Descending, DESCENDING, or DeScEnDiNG as a field name.

App Services also reserves the following keywords with the given exact capitalization:

  • ALL
  • ANY
  • B64
  • IN
  • NONE
  • NOT
  • SOME
  • TRUE
  • all
  • any
  • false
  • in
  • none
  • not
  • oid
  • some
  • true
  • uuid

You cannot use true or TRUE, since both capitalizations are specifically reserved, but you can use True or tRUE as a field name.

Queryable fields use storage on the backing Atlas cluster. The more queryable fields you configure, the more storage you use on the backing cluster. You can configure up to 10 queryable fields per application for Flexible Sync.

To use Flexible Sync, create a schema for your App. The eligible fields in your schema become queryable fields you can select when you enable Flexible Sync.

If you're not yet ready to create a schema, you can manually define queryable fields with Development Mode.

See also:

After you have defined a schema, or decided to create your data model on the client side and use Development Mode to define a schema, you can enable Flexible Sync.

During the process of enabling Sync, you select queryable fields and define roles that control how users can access your data.

When you enable Flexible Sync, you can select queryable fields in two ways:

You can configure up to 10 queryable fields per App. These fields apply across all of the collections in your application.

When a user submits a query to the App, Sync determines which role applies for the user.

Roles consist of:

  • A role name
  • A rule for when to apply the role
  • Read and write permissions for users with the role

You can define multiple roles to tailor your access permissions for each collection. Collections can have more than one role, or none at all.

You can also create default roles, which do not apply to a specific collection. Instead, default roles apply to any collection where you do not define custom roles.

With Flexible Sync enabled, you can start creating queries from your client application.

The Atlas App Services SDKs provide methods to create, update, and remove queries from the client application. The SDKs use subscriptions to maintain those queries on the client side. Through these subscriptions, your applications sync objects with the backend App and can watch for and react to changes.

Asymmetric Sync is a sync strategy that is optimized for applications with heavy client-side insert-only workloads. You enable it for one or more collections. It supports writing to any collection type, including an Atlas time-series collection.


Asymmetric Sync is a feature of Flexible Sync and cannot be enabled on apps that use Partition-Based Sync.

For example, an IoT app that frequently logs sensor data has a significant write workload and no read workload. The device may also be offline for extended periods of time. Asymmetric Sync bypasses some of the processing required for bi-directional sync, significantly improving write speed to an Atlas collection.

Other use cases include writing immutable data, such as invoices from a retail app, or logging application events, neither of which requires conflict resolution.

You can apply Asymmetric Sync to individual collections. This means your app can use Asymmetric Sync to write some data, but bi-directional Flexible Sync on other collections.


Asymmetric Sync collections are only for writing data. You cannot use Flexible Sync queries against these collections. Instead, use MongoDB Data Sources.

You configure and enable Asymmetric Sync in the Advanced Options section of the Sync set up page. For more information on setting up Flexible Sync with Asymmetric Sync, see Enable Flexible Sync.

After you have enabled Asymmetric Sync, you implement it in the client app via the client SDKs.

SDK Support

The JavaScript SDK supports Asymmetric Sync. Support in the other SDKs is forthcoming.

←  Choose Your Sync ModePartitions →
Give Feedback
© 2022 MongoDB, Inc.


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