The SyncSubscriptionGroup resource allows you to apply multiple subscriptions to one or more databases. Subscriptions use Ditto Query Language (DQL) to specify exactly which documents to sync, helping optimize bandwidth and storage usage.

​
Basic Configuration

resources:
  my_subscription_group:
    resource_type: SyncSubscriptionGroup
    db_ids:
      - "YOUR_APP_ID"  # UUID format
    subscriptions:
      - "SELECT * FROM collection_name"

​
Required Fields

FieldTypeDescription
resource_typestringMust be "SyncSubscriptionGroup"
db_idsarray[string]List of database IDs (UUIDv4 format) this subscription group applies to (minimum 1)
subscriptionsarrayList of DQL subscriptions to apply (minimum 1)

​
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

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

​
Single Database Subscription Group

resources:
  # Database configuration
  my_database:
    resource_type: DittoDatabase
    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"
  
  # Subscription group for the database
  my_subscriptions:
    resource_type: SyncSubscriptionGroup
    db_ids:
      - "12345678-1234-4123-1234-123456789012"
    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"

​
Multiple Database Subscription Group

resources:
  # First database
  db_production:
    resource_type: DittoDatabase
    db_id: "11111111-1111-4111-1111-111111111111"
    device_name: "edge-prod"
    auth:
      small_peer_only:
        offline_license_token: "PROD_LICENSE"
  
  # Second database
  db_staging:
    resource_type: DittoDatabase
    db_id: "22222222-2222-4222-2222-222222222222"
    device_name: "edge-staging"
    auth:
      small_peer_only:
        offline_license_token: "STAGING_LICENSE"
  
  # Subscription group applied to both databases
  cross_db_subscriptions:
    resource_type: SyncSubscriptionGroup
    db_ids:
      - "11111111-1111-4111-1111-111111111111"
      - "22222222-2222-4222-2222-222222222222"
    subscriptions:
      - "SELECT * FROM events WHERE timestamp > '2024-01-01'"
      - "SELECT * FROM system_logs"

​
Complex Subscription Group

resources:
  device_db:
    resource_type: DittoDatabase
    db_id: "33333333-3333-4333-3333-333333333333"
    device_name: "edge-device"
    auth:
      server:
        access_token: "TOKEN"
        auth_url: "https://auth.dittolive.app"
        provider: "customProvider"
  
  comprehensive_subscriptions:
    resource_type: SyncSubscriptionGroup
    db_ids:
      - "33333333-3333-4333-3333-333333333333"
    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"

​
Subscriptions in DittoDatabase Resource

You can also define subscriptions directly within a DittoDatabase resource configuration: 
resources:
  my_database:
    resource_type: DittoDatabase
    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:  # Inline subscriptions
      - "SELECT * FROM tasks"
      - query: "SELECT * FROM users WHERE role = :role"
        args:
          role: "admin"

​
Best Practices

  1. Use DQL best practices.
  2. Use YAML anchors and aliases to stay DRY and ensure db_ids are correct: 
resources:
  # First database
  db_production:
    resource_type: DittoDatabase
    db_id: &prod_db "11111111-1111-4111-1111-111111111111"
    device_name: "edge-prod"
    auth:
      small_peer_only:
        offline_license_token: "PROD_LICENSE"
  
  # Second database
  db_staging:
    resource_type: DittoDatabase
    db_id: &staging_db "22222222-2222-4222-2222-222222222222"
    device_name: "edge-staging"
    auth:
      small_peer_only:
        offline_license_token: "STAGING_LICENSE"
  
  # Subscription group applied to both databases
  cross_db_subscriptions:
    resource_type: SyncSubscriptionGroup
    db_ids:
      - *prod_db
      - *staging_db
    subscriptions:
      - "SELECT * FROM events WHERE timestamp > '2024-01-01'"
  1. Group Related Subscriptions: Use SyncSubscriptionGroup to logically group related subscriptions that should be applied together.
  2. 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.
  • Multiple Groups: You can have multiple SyncSubscriptionGroup resources for the same database to organize different sync patterns.
  • 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.
  • Inline vs Group: You can define subscriptions either directly in a DittoDatabase resource or in separate SyncSubscriptionGroup resources. Use groups when you want to apply the same subscriptions to multiple databases.