Skip to main content
Read more about how data synchronization works in Syncing Data.

​
Start Sync

Ensure the sync process remains active throughout your app’s lifecycle by starting the sync process (startSync) in the top-most scope of your code. To initiate the sync process: 
do {
    try ditto.sync.start()
} catch {
    print("Failed to start sync: \(error)")
    // handle error
}

try {
    ditto.sync.start()
} catch (e: DittoException) {
    // handle error
}

try {
  ditto.startSync()
} catch (err) {
  // handle error
}

try {
  ditto.startSync();
} catch (err: unknown) {
  // handle error
}

try {
    ditto.getSync().start();
} catch(DittoError e) {
    // handle error
}

try
{
    ditto.Sync.Start();
}
catch (DittoException ex)
{
    // handle exception
}

try {
  ditto.get_sync().start();
} catch (const DittoError &err) {
  std::cerr << err.what();
}

ditto.sync().start()?;

try {
  ditto.startSync();
} catch (e) {
  // handle exception
}

if err := dit.Sync().Start(); err != nil {
	log.Fatalf("failed to start sync: %v", err)
}

​
Subscriptions

With a subscription query, you can declaratively describe the data that you want a particular device to receive. When a query is subscribed, Ditto continuously syncs relevant documents that match the query to the local device. The subscription query represents “what you want other peers to send you.” It is not a query that you run against the local database, but rather a query that you run against the remote peers to receive updates about documents that match the query.
For operational best practices — scoping subscriptions, keeping them stable, and avoiding patterns that degrade sync performance — see Sync Handling.

​
Creating Subscriptions

The following snippet demonstrates how to establish a subscription to sync updates to documents in the cars collection with a field of color set to the value blue: 
ditto.sync.registerSubscription("SELECT * FROM cars")

ditto.sync.registerSubscription("SELECT * FROM cars")

ditto.sync.registerSubscription("SELECT * FROM cars")

import { SyncSubscription } from '@dittolive/ditto';

const subscription: SyncSubscription = ditto.sync.registerSubscription("SELECT * FROM cars");

ditto.getSync().registerSubscription("SELECT * FROM cars")

ditto.Sync.RegisterSubscription("SELECT * FROM cars");

auto subscription =
  ditto.sync().register_subscription("SELECT * FROM cars");

let subscription =
  ditto.sync().register_subscription("SELECT * FROM cars")?;

ditto.sync.registerSubscription("SELECT * FROM cars");

subscription, err := dit.Sync().RegisterSubscription("SELECT * FROM cars)
if err != nil {
    // handle error
}
Sync subscriptions also support argument injection using the :argument syntax in DQL: 
ditto.sync.registerSubscription("""
  SELECT *
  FROM cars
  WHERE color = :color
  """,
  [ "color": "blue" ])

ditto.sync.registerSubscription("""
  SELECT *
  FROM cars
  WHERE color = :color
  """,
  mapOf("color" to "blue"))

ditto.sync.registerSubscription(`
  SELECT *
  FROM cars
  WHERE color = :color`,
  { color: 'blue' })

import { SyncSubscription } from '@dittolive/ditto';

const subscription: SyncSubscription = ditto.sync.registerSubscription(`
  SELECT *
  FROM cars
  WHERE color = :color`,
  { color: 'blue' });

import static com.ditto.java.serialization.DittoCborSerializable.buildDictionary;

ditto.getSync().registerSubscription(
  "SELECT * FROM cars WHERE color = :color",
  buildDictionary().put("color", "blue").build());

var queryArguments = new Dictionary<string, object>(){{"color", "blue" }};

ditto.Sync.RegisterSubscription(
  "SELECT * FROM cars WHERE color = :color",
  queryArguments);

ditto.sync().register_subscription(
  "SELECT * FROM cars WHERE color = :color",
  {{"color", "blue"}});

#[derive(serde::Serialize)]
struct Args {
  color: String,
}

// ...

let args = Args {
  color: "blue".to_string(),
};
ditto.sync().register_subscription((
  "SELECT * FROM cars WHERE color = :color",
  args,
))?;

ditto.sync.registerSubscription("""
  SELECT *
  FROM cars
  WHERE color = :color""",
  arguments: {"color": "blue"},
);

subscription, err := dit.Sync().RegisterSubscription(
	"SELECT * FROM cars WHERE color = :color",
	map[string]any{"color": "blue"},
)
if err != nil {
    // handle error
}

​
Retrieving Subscriptions

Retrieve active sync subscriptions by calling the subscriptions method on the ditto.sync namespace: 
let activeSubscriptions = ditto.sync.subscriptions;

val activeSubscriptions = ditto.sync.subscriptions

const activeSubscriptions = ditto.sync.subscriptions

import { SyncSubscription } from '@dittolive/ditto';

const activeSubscriptions: SyncSubscription[] = ditto.sync.subscriptions;

DittoSyncSubscription[] activeSubscriptions = ditto.getSync().subscriptions;

var activeSubscriptions = ditto.Sync.Subscriptions;

// Not Supported. Hold the reference to the SyncSubscription object.

// Not Supported. Hold the reference to the SyncSubscription object.

final activeSubscriptions = ditto.sync.subscriptions;

activeSubscriptions := dit.Sync().Subscriptions()

​
Canceling Subscriptions

To cancel a subscription, call cancel on its subscription object you instantiated when setting up your subscription. 
subscription.cancel()

subscription.close()

subscription.cancel()

subscription.cancel();

subscription.close()

subscription.Cancel();

// ...

// ...

subscription.cancel()

subscription.Cancel()
Check if a sync subscription is canceled by using the isCancelled field on the subscription object: 
subscription.isCancelled

subscription.isClosed

subscription.isCancelled

const isCancelled: boolean = subscription.isCancelled;

subscription.isCancelled

subscription.IsCancelled

// ...

// ...

subscription.isCancelled

subscription.IsCanceled()

​
Stopping Sync

To stop the sync process, call the stopSync function. Once called, you will be disconnect from any peers and all active sync subscriptions will be paused. 
ditto.sync.stop()

try {
    ditto.sync.stop()
} catch (e: DittoException) {
    // handle error
}

try {
  ditto.stopSync()
} catch (err) {
  // handle error
}

try {
  ditto.stopSync();
} catch (err: unknown) {
  // handle error
}

try {
    ditto.getSync().stop();
} catch(DittoError e) {
    // handle error
}

try
{
    ditto.Sync.Stop();
}
catch (DittoException ex)
{
    // handle exception
}

try {
  ditto.get_sync().stop();
} catch (const DittoError &err) {
  std::cerr << err.what();
}

ditto.sync().stop();

ditto.stopSync();

dit.Sync().Stop()