> ## 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.

# Sync Subscriptions Configuration

> Configure sync subscriptions to control what data your Edge Server synchronizes from the mesh network

<Warning>
  **Configuration Change**: The `SyncSubscriptionGroup` resource type has been removed. Subscriptions are now defined directly in the database configuration.
</Warning>

Subscriptions use [Ditto Query Language (DQL)](/dql/dql) to specify exactly which
documents to sync, helping optimize bandwidth and storage usage.

## Basic Configuration

```yaml theme={null}
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  auth:
    # ... auth configuration
  subscriptions:
    - "SELECT * FROM collection_name"
    - "SELECT * FROM users WHERE active = true"
```

## Subscription Field

Subscriptions are configured as part of the database configuration:

| Field           | Type  | Description                                                            |
| --------------- | ----- | ---------------------------------------------------------------------- |
| `subscriptions` | array | List of DQL subscriptions to apply (optional, defaults to empty array) |

## Subscription Formats

Each subscription in the `subscriptions` array can be either:

### Simple String Query

```yaml theme={null}
subscriptions:
  - "SELECT * FROM tasks"
  - "SELECT * FROM users WHERE active = true"
```

### Query with Arguments

```yaml theme={null}
database:
  db_id: "YOUR_APP_ID"
  device_name: "edge-device-1"
  auth:
    # ... auth configuration
  subscriptions:
    - query: "SELECT * FROM tasks WHERE assignee = :user_id"
      args:
        user_id: "user123"
    - query: "SELECT * FROM events WHERE region = :region AND priority >= :min_priority"
      args:
        region: "us-west"
        min_priority: 3
```

### Mixed Format

```yaml theme={null}
subscriptions:
  # Simple string queries
  - "SELECT * FROM config"
  - "SELECT * FROM users"
  
  # Parameterized queries
  - query: "SELECT * FROM tasks WHERE status = :status"
    args:
      status: "active"
```

## Complete Examples

### Database with Subscriptions

```yaml theme={null}
database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"
  subscriptions:
    - "SELECT * FROM sensor_data WHERE location = 'warehouse_a'"
    - "SELECT * FROM alerts WHERE severity >= 3"
    - query: "SELECT * FROM inventory WHERE category = :category"
      args:
        category: "electronics"
```

### Complex Subscriptions Example

```yaml theme={null}
database:
  db_id: "33333333-3333-4333-3333-333333333333"
  device_name: "edge-device"
  auth:
    server:
      access_token: "TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "customProvider"
  subscriptions:
    # Simple queries
    - "SELECT * FROM config"
    - "SELECT * FROM users WHERE active = true"

    # Parameterized queries
    - query: "SELECT * FROM devices WHERE region = :region AND last_seen > :cutoff_date"
      args:
        region: "us-west"
        cutoff_date: "2024-12-01T00:00:00Z"

    - query: "SELECT * FROM metrics WHERE device_id IN :device_list AND metric_type = :type"
      args:
        device_list: ["device1", "device2", "device3"]
        type: "temperature"
```

## Configuration Location

Subscriptions are always defined directly in the database configuration:

```yaml theme={null}
database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "REPLACE_ME_WITH_YOUR_URL"
      provider: "__playgroundProvider"
  subscriptions:  # Subscriptions defined inline
    - "SELECT * FROM tasks"
    - query: "SELECT * FROM users WHERE role = :role"
      args:
        role: "admin"
```

## Best Practices

1. Use [DQL best practices](/best-practices/data-modeling).

2. **Group Related Subscriptions**: Logically organize related subscriptions together in the subscriptions array.

3. **Minimize Overlap**: Avoid overlapping subscriptions that would sync the same data multiple times.

## Important Notes

* **Subscription Scope**: Subscriptions only affect what data is synchronized to this Edge Server instance, not what data exists elsewhere in the mesh.
* **Query Validation**: Invalid DQL queries will cause the subscription to fail during Edge Server startup.
* **Configuration Updates**: Changes to subscription configuration require Edge Server restart to take effect.
* **Query Arguments**: The `args` object supports various data types including strings, numbers, booleans, arrays, and nested objects.

## Related Resources

* [Ditto Query Language (DQL) Documentation](/dql)
* [DittoDatabase Configuration](/edge-server/configuration/reference/ditto-database-resource)
* [Edge Server Overview](/edge-server/overview)