Managing Subscriptions

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
}

Unsupported Query Syntax

A subscription query describes which documents sync to the peer, not the order they are displayed in. Some SELECT syntax is therefore rejected when you register a subscription, even though the same query runs fine through execute or registerObserver:

LIMIT and ORDER BY — registering a subscription whose query contains either clause fails with <dql> Unsupported feature: Limit or Order by. Remove the clauses from the subscription and sort or page the results at query time instead, in an execute or registerObserver query. See Stateful Subscription Performance Guidelines for background on why these clauses are restricted.
Joins — a subscription query that joins collections fails with an unsupported query error. Subscribe to each collection separately and perform the join in an execute or registerObserver query. See Joins — Restrictions.

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()

Overview & Setup

SDKs

Accessing Data

Syncing Data

Authentication and Authorization

Managing the Mesh

Deploying your App

Managing Subscriptions

Start Sync

Subscriptions

Creating Subscriptions

Unsupported Query Syntax

Retrieving Subscriptions

Canceling Subscriptions

Stopping Sync

​Start Sync

​Subscriptions

​Creating Subscriptions

​Unsupported Query Syntax

​Retrieving Subscriptions

​Canceling Subscriptions

​Stopping Sync

Start Sync

Subscriptions

Creating Subscriptions

Unsupported Query Syntax

Retrieving Subscriptions

Canceling Subscriptions

Stopping Sync