Manage Sync Subscriptions

Subscribe to Object Types

Subscription sets are based on your data model object types. You might have multiple subscriptions if you have many types of SDK objects. You can also have multiple subscriptions on the same object type.

However, note the following if you use relationships or asymmetric objects in your app:

Permissions

Subscriptions work hand-in-hand with permissions to determine what data to Sync to your client application. The client application only sees the subset of data that matches your subscriptions which also matches the permissions of the logged-in user. For more information about the intersection of subscriptions and user permissions, refer to Write Data to a Synced Database.

This page details how to manage client subscriptions for Device Sync. For information about setting up permissions for Device Sync, see: Device Sync Rules & Permissions.

Initial Subscriptions

Before you can read from or write to a synced database, you must provide at least one subscription. Some of the SDK languages provide a dedicated API to make it more convenient to set initial subscriptions. For details, refer to Set Initial Subscriptions.

Subscribe to a Query

With an authenticated user and a Sync configuration, you can open a synced database and query for the objects you want to read and write. You can subscribe to the query to create a subscription for objects matching the query.

This creates an unnamed subscription and adds it to the subscription set, similar to manually creating a subscription.

Subscriptions persist across user sessions unless you unsubscribe from them.

Subscribe to a Query with a Subscription Name

If your app works with multiple subscriptions, or if you want to update a subscription, you should add a name when you subscribe to a query.

You can later use this name to:

• Change a subscription's query

• Remove the query by name

Wait for a Query Subscription to Sync

When you subscribe to a query, that query's results do not contain objects until the subscription syncs with Atlas.

If your app creates objects, you may not need to download synced data before the user works with it. However, if your app requires data from Atlas before the user can work with your app, you can specify that the SDK should wait for the subscription query data to sync before proceeding.

Unsubscribe from a Query

You can unsubscribe from a query that you have previously subscribed to. Unsubscribing removes the suscription from the subscription set, similar to manually removing a subscription.

A query results set may still contain objects after calling the unsubscribe method if the subscription set contains another overlapping subscription.

The unsubscribe method returns before objects matching the removed subscription are deleted from the database. Sync continues in the background based on the new set of subscriptions. There is no API to wait for the unsubscribe method to sync with the server.

Access the Subscription Set

You can access the subscription set through the database subscriptions property. You perform all operations to add, find, update, remove, or watch subscriptions through this property.

Find a Subscription

You can find a specific subscription in a subscription set. You might want to find a specific subscription:

• To avoid adding the same subscription again, which in some languages throws an error.

• To update the subscription.

• To remove the subscription.

Add a Subscription

Add a subscription in a subscriptions update block. You append each new subscription to the client's SDK subscriptions.

Subscriptions persist across user sessions unless you remove them from the subscription set.

If your app is adding subscriptions for the first time, some SDK languages provide a special parameter to set initial subscriptions or recalculate initial subscriptions on app launch. For details, skip to the set initial subscriptions on this page.

Wait for Subscription Changes to Sync

Updating the subscription set on the device is only one component of changing a subscription. After the client app subscription change, the SDK 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 database.

Adding New Subscriptions

If your app creates objects, you may not need to download synced data before the user works with it. However, if your app requires data from Atlas before the user can work with your app, you can specify that the SDK should wait for the subscription changes to sync before proceeding.

Updating Existing Subscriptions

When you update an existing subscription, this could mean adding new data or removing data from the synced database. If this involves things like changing user permissions to add or remove data, or if your app otherwise makes these changes visible to users in the UI, you may want to wait for subscription changes to update before proceeding with app execution. Otherwise, the changes may appear to the user as unexpected changes to the data set later during "normal" app execution.

Check Subscription Set State

You can check the state of the subscription set through to find out the current status of the subscription set. This provides information about whether Atlas has registered the subscription that is on the device. It does not make any guarantees about the state of the documents matching the subscription.

Change Subscription Queries

You can change the queries in a subscription set. You might want to do this when business logic dictates syncing a different subset of objects, such as when a user unlocks new features in an app.

• Change a named query

• Change an unnamed query

When you change a query, consider how it interacts with any other queries that may be in the subscription set. You may need to add or remove other subscriptions, such as:

• Adding a new subscription when a change to a query introduces new linked objects

• Removing a subscription when an overlapping query inadvertently exposes objects you don't want to sync

Remove Subscriptions

To remove subscriptions, you can:

• Remove a specific subscription

  • Remove a named subscription

  • Remove an unnamed subscription

  • Remove a subscription by reference

• Remove all subscriptions for a specific object type

• Remove all unnamed subscriptions

• Remove all subscriptions

When you remove a subscription query, the SDK asynchronously removes the synced data that matched the query from the client device.

API Efficiency

Adding several subscriptions with the .subscribe() and .unsubscribe() APIs described in the Subscribe to Queries section is less efficient than performing batch updates when you manually manage subscriptions. On every call to .subscribe(), the SDK opens a new update block. For better performance adding multiple subscriptions, use the subscriptions.update API described in the Manually Manage Subscriptions section.

Group Updates for Improved Performance

Every write transaction for a subscription set has a performance cost. If you need to make multiple updates to a database object during a session, consider keeping edited objects in memory until all changes are complete. This improves sync performance by only writing the complete and updated object to your database instead of every change.

Indexed Queryable Fields Subscription Requirements

Adding an indexed queryable field to your App can improve performance for simple queries on data that is strongly partitioned. For example, an app where queries strongly map data to a device, store, or user, such as user_id == $0, “641374b03725038381d2e1fb”, is a good candidate for an indexed queryable field. However, an indexed queryable field has specific requirements for use in a query subscription:

• The indexed queryable field must be used in every subscription query. It cannot be missing from the query.

• The indexed queryable field must use an == or IN comparison against a constant at least once in the subscription query. For example, user_id == $0, "641374b03725038381d2e1fb" or store_id IN $0, {1,2,3}.

You can optionally include an AND comparison as long as the indexed queryable field is directly compared against a constant using == or IN at least once. For example, store_id IN {1,2,3} AND region=="Northeast" or store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

Invalid Device Sync queries on an indexed queryable field include queries where:

• The indexed queryable field does not use AND with the rest of the query. For example store_id IN {1,2,3} OR region=="Northeast" is invalid because it uses OR instead of AND. Similarly, store_id == 1 AND active_promotions < 5 OR num_employees < 10 is invalid because the AND only applies to the term next to it, not the entire query.

• The indexed queryable field is not used in an equality operator. For example store_id > 2 AND region=="Northeast" is invalid because it uses only the > operator with the indexed queryable field and does not have an equality comparison.

• The query is missing the indexed queryable field entirely. For example, region=="Northeast or truepredicate are invalid because they do not contain the indexed queryable field.

Unsupported Sync Subscription Query Operators

Device Sync does not support all RQL operators when creating your subscription queries. When you write the query subscription that determines which data to sync to the device, the server does not support these query operators. However, you can use all RQL operators to query the data set once it has synced to 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 performance problems.

Device Sync only supports @count for array fields.

List Queries

Device Sync supports querying lists using the IN operator.

You can query a list of constants to see if it contains the value of a queryable field:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

If a queryable field has an array value, you can query to see if it contains a constant value:

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"

Embedded or Linked Objects

Device Sync does not support querying on properties in Embedded Objects or links. For example, obj1.field == "foo".