On this page
Flexible Sync uses subscriptions and permissions to determine which data to sync with your App.
To use Flexible Sync in the SDK:
Authenticate a user in your client project.
You can add, update, and remove query subscriptions to determine which data syncs to the client device.
This page details how to manage subscriptions for Flexible Sync.
For general information about using Atlas Device Sync with the SDK, such as how to sync changes in the background or pause a sync session, check out Sync Changes Between Devices.
For information about setting up permissions for Flexible Sync, check out Flexible Sync Rules & Permissions.
When you configure Flexible Sync on the backend, you specify which fields
your client application can query. In the client application, use the
subscriptions API to manage a set of subscriptions to specific queries on
queryable fields. You can construct queries with the Java SDK's fluent interface or Realm Query Language.
Flexible Sync does not support all the operators available in Realm Query Language. See Flexible Sync RQL Limitations for details.
React to subscription state
Update subscriptions with new queries
Remove individual subscriptions or all subscriptions for an object type
Data matching the subscription, where the user has the appropriate permissions, syncs between clients and the backend application.
You can specify an optional string name for your subscription.
Always Specify a Subscription Name
Always specify a subscription name if your application uses multiple subscriptions. This makes your subscriptions easier to look up, update, and delete elsewhere in your app.
When you create a subscription, Realm looks for data matching a query on a specific object type. You can have multiple subscription sets on different object types. You can also have multiple queries on the same object type.
You can create a subscription with an explicit name. Then, you can search for that subscription by name to update or remove it.
You can also search subscriptions by query. If you omit the name when creating a subscription, this is the only way to look up your subscription.
Subscription names must be unique. Adding a subscription with the same name as an existing subscription throws an error.
If you do not explicitly name a subscription, and instead subscribe to the same unnamed query more than once, Realm does not persist duplicate queries to the subscription set.
If you subscribe to the same query more than once under different names, Realm persists both subscriptions to the subscription set.
Add a subscription in a subscriptions write block. You append each new subscription to the client's Realm subscriptions.
You must add both an object and its linked object to the subscription set to see a linked object.
If your subscription results contain an object with a property that links to an object not contained in the results, the link appears to be null. There is no way to distinguish whether that property's value is legitimately null, or whether the object it links to exists but is out of view of the query subscription.
Writing an update to the subscription set locally is only one component of changing a subscription. After the local subscription change, the client synchronizes with the server to resolve any updates to the data due to the subscription change. This could mean adding or removing data from the synced realm. Use the waitForInitialRemoteData() builder method to force your application to block until client subscription data synchronizes to the backend before opening the realm:
Additionally, you can watch the state of the subscription set with the SubscriptionSet.State enum. You can use subscription state to:
Show a progress indicator while data is downloading
Find out when a subscription set becomes superseded
You can access the state of your application's subscription set using SubscriptionSet.getState().
SUPERSEDED is a
SubscriptionSet.State that can occur when another
thread writes a subscription on a different instance of the
subscription set. If the state becomes
SUPERSEDED, you must obtain
a new instance of the subscription set before you can write to it.
You cannot update subscriptions created without a name. However, you can look up unnamed subscriptions by their query, remove them from the subscription set, then add a new subscription with an updated query:
To remove subscriptions, you can:
Remove a single subscription query
Remove all subscriptions to a specific object type
Remove all subscriptions
When you remove a subscription query, Realm asynchronously removes the synced data that matched the query from the client device.
You can remove a specific subscription query
You can either look up the subscription by name, then pass the returned
remove(), or pass the subscription name directly to
If you want to remove all subscriptions to a specific object type, pass a class to the removeAll() method:
To remove all subscriptions from the subscription set, use removeAll() with no arguments:
If you remove all subscriptions and do not add a new one, you'll get an error. A realm opened with a flexible sync configuration needs at least one subscription to sync with the server.
Flexible Sync has some limitations when using RQL operators. When you write the query subscription that determines which data to sync, the server does not support these query operators. However, you can still use the full range of RQL features to query the synced data set in the client application.
Case insensitive queries (
[c]) cannot use indexes effectively.
As a result, case insensitive queries are not recommended, since they could lead to
Flexible Sync only supports
@count for array fields.
Flexible Sync does not support querying on lists of data using the
Flexible Sync does not support querying on properties in Embedded Objects
or links. For example,
obj1.field = "foo".