---
title: Data Sync
slug: v4-5/data-sync
icon: {"faIcon":"fa-solid fa-route"}
docTags: 
createdAt: 2023-08-22T20:57:32.293Z
---

Here's a detailed guide with step-by-step instructions on integrating sync functionality within your app, allowing seamless communication with remote peers.

# Sync Start and Stop

Required only once, initiating the sync process automatically connects you with the mesh network. Once connected, you immediately begin receiving updates from publishing remote peers and sending updates to subscribing remote peers.

## Starting Sync

To start the sync process:

:::CodeblockTabs
```swift
try! ditto.startSync()
```

```kotlin
try {
    ditto.startSync()
} catch (e: DittoError) {
    // handle error
}
```

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

```java
try {
    ditto.startSync();
} catch(DittoError e) {
    // handle error
}
```

```csharp
try
{
    ditto.StartSync();
}
catch (DittoException ex)
{
    // handle exception
}
```

```cpp
try {
  ditto.start_sync();
} catch (const DittoError &err) {
  std::cerr << err.what();
}
```

```rust
ditto.try_start_sync()?;
```
:::

:::hint{type="info"}
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.&#x20;
:::

## Stopping Sync

To stop the sync process, call the `stopSync` function. Once called, all active sync subscriptions end and you disconnect from the mesh.&#x20;

:::CodeblockTabs
```swift
try! ditto.stopSync()
```

```kotlin
try {
    ditto.stopSync()
} catch (e: DittoError) {
    // handle error
}
```

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

```java
try {
    ditto.stopSync();
} catch(DittoError e) {
    // handle error
}
```

```csharp
try
{
    ditto.StopSync();
}
catch (DittoException ex)
{
    // handle exception
}
```

```cpp
try {
  ditto.stop_sync();
} catch (const DittoError &err) {
  std::cerr << err.what();
}
```

```rust
ditto.try_stop_sync()?;
```
:::

***

# Subscriptions Management

:::hint{type="warning"}
DQL sync subscriptions are supported for devices on version 4.5 or later.&#x20;

Devices on Ditto versions 4.4 or earlier are supported, however will *not* sync data by way of DQL subscriptions. For information on syncing with devices on version 4.4 and earlier, see *Platform Manual* > Legacy API & Language > [Data Sync (Legacy)](docId:4mF4vp9MK0WZc2COLhflH).
:::

Manage your sync subscriptions:

- To get your active subscriptions, call the `subscriptions` method on the `ditto.sync` namespace. ([Retrieving Subscriptions](./#retrieving-subscriptions))

- To cancel a subscription, call `cancel` on its subscription object you instantiated when setting up your subscription. ([Canceling Subscriptions](./#canceling-subscriptions))

- To confirm cancelation, call the `isCancelled` field on the subscription object. ([Canceling Subscriptions](./#canceling-subscriptions))

***

## Creating Subscriptions

To register a new sync subscription in your app. For example, 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`:

:::CodeblockTabs
```swift
ditto.sync.registerSubscription("SELECT * FROM cars")
```

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

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

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

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

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

```rust
let subscription = 
  ditto.sync().register_subscription("SELECT * FROM cars", None);
```
:::

Sync subscriptions also support argument injection using the `:argument` syntax in DQL:

:::CodeblockTabs
```swift
ditto.sync.registerSubscription("""
  SELECT *
  FROM cars
  WHERE color = :color
  """,
  [ "color": "blue" ])
```

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

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

```java
ditto.sync.registerSubscription(
  "SELECT * FROM cars WHERE color = :color",
  Collections.singletonMap("color", "blue"))
```

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

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

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

```rust
struct Args {
  color: String,
}

// ...

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

***

## Retrieving Subscriptions

Retrieve active sync subscriptions by calling the `subscriptions` method on the `ditto.sync` namespace:

:::CodeblockTabs
```swift
let activeSubscriptions = ditto.sync.subscriptions;
```

```kotlin
val activeSubscriptions = ditto.sync.subscriptions
```

```javascript
const activeSubscriptions = ditto.sync.subscriptions
```

```java
DittoSyncSubscription[] activeSubscriptions = ditto.sync.subscriptions;
```

```csharp
var activeSubscriptions = ditto.Sync.Subscriptions;
```

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

```rust
// Not Supported. Hold the reference to the SyncSubscription object.
```
:::

***

## Canceling Subscriptions

To cancel a subscription, call `cancel` on the subscription object you set up to establish your subscription:

:::CodeblockTabs
```swift
subscription.cancel()
```

```kotlin
subscription.close()
```

```javascript
subscription.cancel()
```

```java
subscription.close()
```

```csharp
subscription.Cancel();
```

```cpp
// ...
```

```rust
// ...
```
:::

You can check if a sync subscription is canceled by using the `isCancelled` field on the subscription object:

:::CodeblockTabs
```swift
subscription.isCancelled
```

```kotlin
subscription.isClosed
```

```javascript
subscription.isCancelled
```

```java
subscription.isCancelled
```

```csharp
subscription.IsCancelled
```

```cpp
// ...
```

```rust
// ...
```
:::

***

# Attachments Sync

Attachments are synced on demand using the Attachment API methods.

:::hint{type="warning"}
Syncing large documents can significantly impact sync performance:

Be cautious handling very large binary data, a deeply embedded or very large document. Carefully consider using `ATTACHMENTS` instead of storing the data directly within a document object. For more information, see [Attachment](docId\:VoFl0GukXq8AjsMMW7Sgz) and [Large Binary Files](docId\:ko44x97iM4nop3qIo9vYu).
:::