Skip to main content
Configuration Change: The SyncSubscriptionGroup resource type has been removed. Subscriptions are now defined directly in the database configuration.
Subscriptions use Ditto Query Language (DQL) to specify exactly which documents to sync, helping optimize bandwidth and storage usage.

​
Basic Configuration

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:
FieldTypeDescription
subscriptionsarrayList of DQL subscriptions to apply (optional, defaults to empty array)

​
Subscription Formats

Each subscription in the subscriptions array can be either:

​
Simple String Query

subscriptions:
  - "SELECT * FROM tasks"
  - "SELECT * FROM users WHERE active = true"

​
Query with Arguments

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

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

database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      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

database:
  db_id: "33333333-3333-4333-3333-333333333333"
  device_name: "edge-device"
  auth:
    server:
      access_token: "TOKEN"
      auth_url: "https://auth.dittolive.app"
      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: 
database:
  db_id: "12345678-1234-4123-1234-123456789012"
  device_name: "edge-device-1"
  auth:
    server:
      access_token: "YOUR_TOKEN"
      auth_url: "https://your-app.cloud.dittolive.app"
      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.
  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.