Configuring Collection Sync

User Collection Sync Scopes let you control how data from each user collection is shared with other connected Peers. This is useful when you want to fine-tune which collections do not sync, which collections sync with only the cloud (Big Peer) and which collections sync only with connected Small Peer devices.

Sync scopes can be used to control how documents sync, reduce unnecessary data transfer, and improve performance.

​

Usage

Sync scopes work on a per-collection basis. A collection’s scope is checked when syncing data to other peers and can prevent data from being sent, even if it matches the other peer’s subscription.

​

Sync Scopes

A collection can use one of the following sync scopes:

​

Setting Sync Scopes

To configure sync scopes, use the DQL ALTER SYSTEM operation to set the USER_COLLECTION_SYNC_SCOPES system property. This property takes a map where each key is a collection name and the value is the desired sync scope.

ALTER SYSTEM SET USER_COLLECTION_SYNC_SCOPES = {
    [collection_name]: [sync_option],
    ...
}

ALTER SYSTEM SET USER_COLLECTION_SYNC_SCOPES = {
    collection_1: "BigPeerOnly",
    collection_2: "SmallPeersOnly",
    collection_3: "LocalPeerOnly"
}

Code Example

In the example below we’ll set the collection local_mesh_orders to only sync with other small peers in the mesh and not with the Big Peer using the SmallPeersOnly sync scope.

var syncScopes = [
  "local_mesh_orders": "SmallPeersOnly"
];
await ditto.store.execute(
    query: "ALTER SYSTEM SET USER_COLLECTION_SYNC_SCOPES = :syncScopes",
    arguments: ["syncScopes": syncScopes]);

try! ditto.startSync()

​

Reading Sync Scopes

To see the currently set sync scopes use the DQL SHOW command with the USER_COLLECTION_SYNC_SCOPES system property.

SHOW USER_COLLECTION_SYNC_SCOPES

​

Updating Sync Scopes

To change sync scopes after they are set, restart the ditto instance so that changes to be reflected in the mesh.

1. Call ditto.close() or ditto = nil
2. Create a new ditto instance ditto = Ditto(...)
3. Update the sync scopes using ALTER SYSTEM
4. Call ditto.startSync() to resume syncing with the new sync scopes.

​

Usage Considerations

• USER_COLLECTION_SYNC_SCOPES is reset when the Ditto instance is closed.
• Be sure to always set USER_COLLECTION_SYNC_SCOPES after creating a new Ditto instance.
• You must set USER_COLLECTION_SYNC_SCOPES before calling startSync().
• Sync scopes are defined on a per-device basis and not shared with other peers in the mesh.
• Sync scopes are designed to allow users to control how document on a device flow out on a per collection basis.
• Sync scopes will be enforced locally over sync subscriptions from other peers. Meaning if a collection has a sync scope that doesn’t allow for sharing with that peer documents will not be share even if that peer has permissions to that collection.
• To have a collection that is only synced with other Small Peers and never synced with the cloud (Big Peer) all peers need to individually set the collection to have the SmallPeersOnly sync scope. If any peer in the mesh does not set this that peer will send data to the cloud (Big Peer).

​

Limitations

• Sync scopes cannot be applied to system collections. These are collections prefixed with double underscore __. Updating USER_COLLECTION_SYNC_SCOPES with a system collection will fail.
• Sync scopes are not enforced for remote query requests.

​

Use Case Scenarios

​

Local-Device Only Collections

A Local-Device Only Collection keeps data stored only on the device where it was created. This is useful when the data is temporary, sensitive, or tied to the specific device. Common examples include caches of recently viewed items, unsaved drafts, or device-specific settings like user preferences.

In these cases, syncing the data to other peers — or to the Big Peer — is unnecessary and could introduce privacy or performance concerns. By setting the collection to LocalPeerOnly, you ensure the data never leaves the device.

​

Small Peers Only Collections

A Small Peers Only Collection allows data to sync only with nearby Small Peers, without ever syncing to the Big Peer. This is useful for temporary collaboration data or ephemeral sessions where nearby devices work together locally.

This approach helps reduce unnecessary cloud storage and limits data visibility to just the local mesh. To configure this, set the collection’s sync scope to SmallPeersOnly.

A common pattern is to use a Small Peers Only collection for active or in-progress data being shared between devices. Once the data reaches a final state — such as after a process is completed — you can copy or move the finalized data into a separate collection that syncs with the Big Peer for long-term storage or reporting.

​

Big Peer Only Collections

A Big Peer Only Collection syncs data exclusively with the Big Peer, ensuring it is not shared with connected Small Peers. This is particularly useful when data needs to be stored in the cloud without being distributed across other devices. Ideal use cases include audit logs, user preferences, or any information meant for centralized storage and retrieval rather than real-time peer-to-peer collaboration.