This feature requires SDK version 4.12.0+ and an active Ditto Cloud subscription.
This guide provides detailed patterns and examples for tracking synchronization between your Edge SDK device and Ditto Cloud servers. Use these patterns to ensure critical data reaches the cloud and provide sync feedback in your application.

​
Understanding Ditto Cloud Sync

Ditto Cloud servers act as the source of truth in most deployments. Tracking sync status with the cloud is crucial for:
  • Critical Operations - Verify important data reached the cloud before proceeding
  • User UI/UX Feedback - Show sync indicators when local commits haven’t uploaded
  • Offline Handling - Know when devices reconnect and sync resumes
  • Data Integrity - Ensure passenger manifests, orders, or transactions are safely stored

​
Quick Start

​
Check Cloud Connection

The system:data_sync_info collection can be used to find and track cloud server connections. To query for the Ditto Server (e.g. Cloud) connections only use the following DQL Query.
DQL
SELECT * FROM system:data_sync_info
WHERE is_ditto_server = true
Check if you’re connected to the cloud: 
let result = try await ditto.store.execute(
  query: "SELECT * FROM system:data_sync_info WHERE is_ditto_server = true AND documents.sync_session_status = 'Connected' ORDER BY documents.synced_up_to_local_commit_id DESC LIMIT 1"
)
print("Connected to cloud: \(!result.items.isEmpty)")

​
Verify Data Reached Cloud

Track when specific local commits reach the cloud: 
// Step 1: Insert data and get commit ID
let result = try await ditto.store.execute(
  query: "INSERT INTO orders DOCUMENTS (:order)",
  arguments: ["order": ["_id": "order-123", "total": 299.99]]
)
let commitId = result.commitID!

// Step 2: Check if it synced to cloud
let syncStatus = try await ditto.store.execute(
  query: "SELECT * FROM system:data_sync_info WHERE is_ditto_server = true ORDER BY documents.synced_up_to_local_commit_id DESC LIMIT 1"
)

if let item = syncStatus.items.first,
   let documents = item.value["documents"] as? [String: Any],
   let syncedUpTo = documents["synced_up_to_local_commit_id"] as? Int64 {

  if syncedUpTo >= commitId {
    print("✅ Commit synced to cloud")
  } else {
    print("⏳ Commit pending sync")
  }
}

​
Real-Time Sync Monitoring

​
Connection Status Observer

Monitor cloud connection Commits in real-time:
Observers on system:data_sync_info result in the callback triggering every 500ms even when the result remains the same. This frequency can be configured using the live_query_system_collection_refresh_interval system parameter.
let observer = ditto.store.registerObserver(
  query: "SELECT * FROM system:data_sync_info WHERE is_ditto_server = true ORDER BY documents.synced_up_to_local_commit_id DESC LIMIT 1"
) { result in
  if let item = result.items.first,
     let documents = item.value["documents"] as? [String: Any] {

    let isConnected = documents["sync_session_status"] as? String == "Connected"
    print("Cloud status: \(isConnected ? "Connected" : "Disconnected")")
  } else {
    print("Cloud status: No servers found")
  }
}

​
Track Pending Cloud Syncs

Track multiple local commits and monitor when they sync to the cloud: 
// Collect the local commit IDs we still need to confirm
var localCommitIds: [Int64] = []

// Watch the cloud sync progress
let observer = ditto.store.registerObserver(
  query: """
    SELECT *
    FROM system:data_sync_info
    WHERE is_ditto_server = true
    ORDER BY documents.synced_up_to_local_commit_id DESC
    LIMIT 1
  """
) { result in
  guard let item = result.items.first,
        let documents = item.value["documents"] as? [String: Any],
        let latestCommitId = documents["synced_up_to_local_commit_id"] as? Int64 else { return }

  // Find the first commitId that hasn't synced yet
  var confirmedCount = 0
  for commitId in localCommitIds {
    if latestCommitId >= commitId {
      print("Successfully synced commit \(commitId) to the cloud")
      confirmedCount += 1
    } else {
      break  // Stop at first non-synced commit
    }
  }

  // Remove synced commitIds
  if confirmedCount > 0 {
    localCommitIds.removeFirst(confirmedCount)
  }
}

// Perform updates and track commit IDs
let result1 = try await ditto.store.execute(query: "UPDATE customers SET verified = true WHERE _id = 'customer-123'")
if let commitId = result1.commitID {
  localCommitIds.append(commitId)
}

let result2 = try await ditto.store.execute(query: "INSERT INTO orders DOCUMENTS ({ _id: 'order-456', total: 599.99 })")
if let commitId = result2.commitID {
  localCommitIds.append(commitId)
}

​
Monitor Incoming Cloud Data

Register an observer to track when new data arrives from the cloud by monitoring commits to last_update_received_time:
Observers on system:data_sync_info result in the callback triggering every 500ms even when the result remains the same. This frequency can be configured using the live_query_system_collection_refresh_interval system parameter.
// Watch for incoming data from cloud
let observer = ditto.store.registerObserver(
  query: "SELECT * FROM system:data_sync_info WHERE is_ditto_server = true ORDER BY documents.synced_up_to_local_commit_id DESC LIMIT 1"
) { result in
  guard let item = result.items.first,
        let documents = item.value["documents"] as? [String: Any],
        let lastUpdate = documents["last_update_received_time"] as? Int64 else { return }

  if lastUpdate > 0 {
    print("📥 New data received from cloud at: \(Date(timeIntervalSince1970: TimeInterval(lastUpdate)))")
  }
}

​
Troubleshooting

  • Verify cloud connection status - Use the connection check examples above
  • Check subscription configuration - Ensure your sync subscriptions are properly configured
  • Ensure device has network connectivity - Test basic internet connectivity
  • Verify Ditto Cloud permissions - Check authentication and access permissions
  • Check network connectivity - Verify internet connection is stable
  • Verify cloud credentials - Ensure authentication tokens are valid
  • Review transport configurations - Check WebSocket and network settings
  • Check firewall/proxy settings - Ensure Ditto Cloud endpoints are accessible
  • Large backlog of commits to sync - Consider reducing data volume or batch size
  • Poor network conditions - Wait for better connectivity or optimize for low bandwidth
  • Subscription recently changed - New subscriptions need time to sync historical data

​
See Also