> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ditto.live/llms.txt
> Use this file to discover all available pages before exploring further.
# Managing Subscriptions
> Subscriptions allow you to declaratively describe the data that you want a particular device to receive. Once subscribed, Ditto continuously syncs relevant documents that match the query to the local device.
Read more about how data synchronization works in [Syncing Data](/key-concepts/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:
```swift Swift theme={null}
do {
try ditto.sync.start()
} catch {
print("Failed to start sync: \(error)")
// handle error
}
```
```kotlin Kotlin theme={null}
try {
ditto.sync.start()
} catch (e: DittoError) {
// handle error
}
```
```javascript JS theme={null}
try {
ditto.startSync()
} catch (err) {
// handle error
}
```
```typescript TypeScript theme={null}
try {
ditto.startSync();
} catch (err: unknown) {
// handle error
}
```
```java Java theme={null}
try {
ditto.getSync().start();
} catch(DittoError e) {
// handle error
}
```
```csharp C# theme={null}
try
{
ditto.Sync.Start();
}
catch (DittoException ex)
{
// handle exception
}
```
```cpp C++ theme={null}
try {
ditto.get_sync().start();
} catch (const DittoError &err) {
std::cerr << err.what();
}
```
```rust Rust theme={null}
ditto.sync().start()?;
```
```dart Dart theme={null}
try {
ditto.startSync();
} catch (e) {
// handle exception
}
```
```go Go theme={null}
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.
### 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`:
```swift Swift theme={null}
ditto.sync.registerSubscription("SELECT * FROM cars")
```
```kotlin Kotlin theme={null}
ditto.sync.registerSubscription("SELECT * FROM cars")
```
```javascript JS theme={null}
ditto.sync.registerSubscription("SELECT * FROM cars")
```
```typescript TypeScript theme={null}
import { SyncSubscription } from '@dittolive/ditto';
const subscription: SyncSubscription = ditto.sync.registerSubscription("SELECT * FROM cars");
```
```java Java theme={null}
ditto.getSync().registerSubscription("SELECT * FROM cars")
```
```csharp C# theme={null}
ditto.Sync.RegisterSubscription("SELECT * FROM cars");
```
```cpp C++ theme={null}
auto subscription =
ditto.sync().register_subscription("SELECT * FROM cars");
```
```rust Rust theme={null}
let subscription =
ditto.sync().register_subscription("SELECT * FROM cars")?;
```
```dart Dart theme={null}
ditto.sync.registerSubscription("SELECT * FROM cars");
```
```go Go theme={null}
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:
```swift Swift theme={null}
ditto.sync.registerSubscription("""
SELECT *
FROM cars
WHERE color = :color
""",
[ "color": "blue" ])
```
```kotlin Kotlin theme={null}
ditto.sync.registerSubscription("""
SELECT *
FROM cars
WHERE color = :color
""",
mapOf("color" to "blue"))
```
```javascript JS theme={null}
ditto.sync.registerSubscription(`
SELECT *
FROM cars
WHERE color = :color`,
{ color: 'blue' })
```
```typescript TypeScript theme={null}
import { SyncSubscription } from '@dittolive/ditto';
const subscription: SyncSubscription = ditto.sync.registerSubscription(`
SELECT *
FROM cars
WHERE color = :color`,
{ color: 'blue' });
```
```java Java theme={null}
import static com.ditto.java.serialization.DittoCborSerializable.buildDictionary;
ditto.getSync().registerSubscription(
"SELECT * FROM cars WHERE color = :color",
buildDictionary().put("color", "blue").build());
```
```csharp C# theme={null}
var queryArguments = new Dictionary(){{"color", "blue" }};
ditto.Sync.RegisterSubscription(
"SELECT * FROM cars WHERE color = :color",
queryArguments);
```
```cpp C++ theme={null}
ditto.sync().register_subscription(
"SELECT * FROM cars WHERE color = :color",
{{"color", "blue"}});
```
```rust Rust theme={null}
#[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,
))?;
```
```dart Dart theme={null}
ditto.sync.registerSubscription("""
SELECT *
FROM cars
WHERE color = :color""",
arguments: {"color": "blue"},
);
```
```go Go theme={null}
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:
```swift Swift theme={null}
let activeSubscriptions = ditto.sync.subscriptions;
```
```kotlin Kotlin theme={null}
val activeSubscriptions = ditto.sync.subscriptions
```
```javascript JS theme={null}
const activeSubscriptions = ditto.sync.subscriptions
```
```typescript TypeScript theme={null}
import { SyncSubscription } from '@dittolive/ditto';
const activeSubscriptions: SyncSubscription[] = ditto.sync.subscriptions;
```
```java Java theme={null}
DittoSyncSubscription[] activeSubscriptions = ditto.getSync().subscriptions;
```
```csharp C# theme={null}
var activeSubscriptions = ditto.Sync.Subscriptions;
```
```cpp C++ theme={null}
// Not Supported. Hold the reference to the SyncSubscription object.
```
```rust Rust theme={null}
// Not Supported. Hold the reference to the SyncSubscription object.
```
```dart Dart theme={null}
final activeSubscriptions = ditto.sync.subscriptions;
```
```go Go theme={null}
activeSubscriptions := dit.Sync().Subscriptions()
```
### Canceling Subscriptions
To cancel a subscription, call `cancel` on its subscription object you
instantiated when setting up your subscription.
```swift Swift theme={null}
subscription.cancel()
```
```kotlin Kotlin theme={null}
subscription.close()
```
```javascript JS theme={null}
subscription.cancel()
```
```typescript TypeScript theme={null}
subscription.cancel();
```
```java Java theme={null}
subscription.close()
```
```csharp C# theme={null}
subscription.Cancel();
```
```cpp C++ theme={null}
// ...
```
```rust Rust theme={null}
// ...
```
```dart Dart theme={null}
subscription.cancel()
```
```go Go theme={null}
subscription.Cancel()
```
Check if a sync subscription is canceled by using the `isCancelled` field on the
subscription object:
```swift Swift theme={null}
subscription.isCancelled
```
```kotlin Kotlin theme={null}
subscription.isClosed
```
```javascript JS theme={null}
subscription.isCancelled
```
```typescript TypeScript theme={null}
const isCancelled: boolean = subscription.isCancelled;
```
```java Java theme={null}
subscription.isCancelled
```
```csharp C# theme={null}
subscription.IsCancelled
```
```cpp C++ theme={null}
// ...
```
```rust Rust theme={null}
// ...
```
```dart Dart theme={null}
subscription.isCancelled
```
```go Go theme={null}
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.
```swift Swift theme={null}
ditto.sync.stop()
```
```kotlin Kotlin theme={null}
try {
ditto.sync.stop()
} catch (e: DittoError) {
// handle error
}
```
```javascript JS theme={null}
try {
ditto.stopSync()
} catch (err) {
// handle error
}
```
```typescript TypeScript theme={null}
try {
ditto.stopSync();
} catch (err: unknown) {
// handle error
}
```
```java Java theme={null}
try {
ditto.getSync().stop();
} catch(DittoError e) {
// handle error
}
```
```csharp C# theme={null}
try
{
ditto.Sync.Stop();
}
catch (DittoException ex)
{
// handle exception
}
```
```cpp C++ theme={null}
try {
ditto.get_sync().stop();
} catch (const DittoError &err) {
std::cerr << err.what();
}
```
```rust Rust theme={null}
ditto.sync().stop();
```
```dart Dart theme={null}
ditto.stopSync();
```
```go Go theme={null}
dit.Sync().Stop()
```