Platform Manual
Data Sync

13min
This article provides step-by-step instructions for setting up, maintaining, and ending data subscriptions for peer-to-peer asynchronous replication:
﻿Creating Subscriptions﻿﻿
﻿Managing Lifetime Subscriptions﻿﻿
﻿Canceling Subscriptions﻿﻿
Expand to learn the basics of subscriptions
Data synchronization, or "sync" for short, refers broadly to the practice of ensuring that peers always have the most up-to-date and accurate information. 
However, data sync goes beyond basic updates and involves a replication process, along with other sophisticated techniques for ensuring data up-to-date and consistent across the mesh network. Replication, in the most basic terms, refers to the process of copying and syncing data across multiple Small Peers; as in, the multiple storage locations that run locally within an end-user physical environment, such as a mobile device. 
To replicate data in Ditto, you establish a subscription. A subscription acts as a listener that, in conjunction with a replication query, specifies the specific remote events a Small Peer is interested in receiving data updates for. A replication query is essentially a request made by a peer to fetch data matching the query's criteria from other peers in order to sync. These replication queries define the criteria and conditions for the associated subscription.
For more information, see Sync and Replication Concepts﻿ in "Advanced Concepts." 
﻿
Creating Subscriptions
To set up a replication subscription in your app:
Syncing large documents can significantly impact sync performance:
Caution is advised when handling very large binary data, a deeply-embedded document, or a very large document. Carefully consider using attachments instead of storing the data directly within a document object. For more information, see Attachment﻿ and Large Binary Files﻿.
1
Start data replication within your app's development lifecycle. (Initiating Replication﻿)
2
Instantiate a top-level subscription object. (Creating Subscriptions﻿)
3
If applicable, end the subscription. (Canceling Subscriptions﻿)
Initiating Replication
Before you can set up your subscription listener, initiate the replication process in your app. Initiating replication indicates that you're ready receive updates from remote peers, as well as send updates to subscribing remote peers.
﻿
To initiate replication, early in your app lifecycle, such as within the following methods, call the startSync method
You must start replication (startSync) in the top-most scope to ensure that as soon as your app starts, it automatically connects with the mesh network and remains active throughout your app's lifecycle.
Otherwise, peer-to-peer connection may fail, resulting in remote peers becoming unable to send you updates in real-time.
Swift
Kotlin
JS
Java
C#
C++
Rust
|
try {
    ditto.startSync()
} catch (e: DittoError) {
    // handle error
}
try {
    ditto.startSync()
} catch (e: DittoError) {
    // handle error
}
﻿
Creating Subscriptions
In the top-most scope of your app, following the startSync method called in the previous step, set up a subscription object:
You must declare your subscription object from the top-most scope of your app to ensure access throughout your app. 
Otherwise, you cannot modify or cancel your subscription from any part of your code, resulting in difficulty and potential errors when managing the subscription's lifecycle.
Pass your replication query as an argument to find. 

Call thesubscribe method, and then pass the subsequent actions and processes you want to execute when your criteria is met as an argument.  
Once you've set up your subscription, your subscription query is automatically sent to all peers connected in the mesh network. If there are any data changes that match your criteria, Ditto automatically triggers your subscribe callback function that performs followup actions and processes in your app.
﻿
Swift
Kotlin
JS
C#
C++
Rust
|
let collection = ditto.store()
  .collection("your_collection_name").unwrap();

const subscription = collection
  .find([query])
  .subscribe();
let collection = ditto.store()
  .collection("your_collection_name").unwrap();

const subscription = collection
  .find([query])
  .subscribe();
﻿
For example, the following snippet demonstrates how to establish a carsSubscription to listen for all updates to documents in the "cars" collection with a field of color set to the value "blue":
Swift
Kotlin
JS
Java
C#
C++
Rust
|
const subscription = ditto.store
  .collection("cars")
  .find("color == 'blue'")
  .subscribe();
const subscription = ditto.store
  .collection("cars")
  .find("color == 'blue'")
  .subscribe();
﻿
Managing Lifetime Subscriptions
In order to prevent memory leaks, Ditto's built-in memory management mechanisms automatically cancels active subscriptions that are no longer needed or relevant.
Therefore, if you store the subscription object at a local scope within your code, once Ditto executes your subscribe callback function, the subscription object may be removed from memory leading to unexpected behaviors. 
﻿
Canceling Subscriptions
To cancel a subscription, callcancel on the subscription object you set up to establish your subscription.
﻿
Swift
Kotlin
JS
Java
C#
C++
Rust
|
subscription.cancel();
subscription.cancel();
﻿
For example, continuing with the previous example, the following snippet illustrates canceling the carsSubscription:
Swift
Kotlin
JS
Java
C#
C++
Rust
|
carsSubscription.cancel();
carsSubscription.cancel();
﻿
﻿
Updated 27 Sep 2023
Did this page help you?
Best Practices for CRUD
Document Model
Docs powered by
Archbee
TABLE OF CONTENTS
Expand to learn the basics of subscriptions
Creating Subscriptions
Initiating Replication
Creating Subscriptions
Managing Lifetime Subscriptions
Canceling Subscriptions