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

MongoDB Realm 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.

When a client makes a query, Realm 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. Realm 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.

Important

Flexible Sync is currently in preview. We encourage you to try out the feature and give feedback, but please be aware that:

  • Configuration details may change.
  • SDK API implementation details may change.

We do not recommend using Flexible Sync in production applications while it is still in preview.

Note
Flexible Sync Prerequisites

Enabling Flexible Sync in Your Realm Application requires the following:

  • A non-sharded MongoDB Atlas cluster running MongoDB 5.0 or greater
  • A Realm app without Partition-Based Sync enabled. While Flexible Sync is in preview, you cannot use Flexible Sync & Partition-Based Sync in the same Realm app.

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

Example

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 a Realm 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.

Tip
See also: Realm Query Language - Flexible Sync Limitations

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

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

Realm 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
Example

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

Realm also reserves the following keywords with the given exact capitalization:

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

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 Realm 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.

Tip
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.

Tip

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

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

When a user submits a query to the Realm 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 MongoDB Realm 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 Realm app and can watch for and react to changes.

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

About

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