Skip to main content
With Ditto SDK 4.11+, the new diffing APIs can be used with store observers to produce diffs between query results in consecutive invocations. This guide explains how to use the new diffing APIs to replace usage of the legacy live query APIs.

​
Overview

Live queries provide their callback with an event parameter that contains a diff of the current live query event against the previous one—a summary of which documents in the result have been:
  • Inserted: Indexes of new items
  • Updated: Indexes of items that existed previously, but have changed
  • Deleted: Indexes of items that were removed
  • Moved: Pairs of indexes showing items that changed position
Store observers don’t have a built-in feature that provides a diff, as generating it is computationally expensive. However, you can use the new Differ class to compute one when needed.

​
Key Differences

​
Legacy Live Query API

  • Provides automatic diffing through the event parameter
  • Maintains event.oldDocuments for deleted items (uses memory)
  • Includes event.isInitial flag for the first callback
  • Considers metadata changes as updates

​
Store Observer with Differ

  • Requires manual diffing using the Differ class
  • You must maintain previous results yourself
  • No built-in initial event detection
  • Ignores metadata-only changes when determining updates

​
Migration Example

​
Before: Using Legacy Live Query API

const appStateLegacy = {
  inserted: null,
  updated: null,
  deleted: null
};

ditto.store
  .collection('cars')
  .findAll()
  .observeLocal((documents, event) => {
    if (event.isInitial) {
      // Store all initial document IDs in app state
      appStateLegacy.inserted = documents.map(doc => doc.value._id);
      console.log("Initial live query event", appStateLegacy.inserted);
    } else {
      appStateLegacy.inserted = event.insertions?.map(
        (index) => documents[index].value._id
      );
      appStateLegacy.updated = event.updates?.map(
        (index) => documents[index].value._id
      );
      appStateLegacy.deleted = event.deletions?.map(
        // accessing `event.oldDocuments`
        (index) => event.oldDocuments[index].value._id
      );
      console.log("Live query event: ", JSON.stringify(appStateLegacy, null, 2));
    }
  });

​
After: Using Store Observer with Differ

Important Memory Management: QueryResults and QueryResultItems should be treated like database cursors. Always extract the data you need and then close/dematerialize them immediately. Never store QueryResultItems directly between observer emissions.
let differ = DittoDiffer()
var previousDocumentIds: [String] = [] // Store only extracted IDs

let observer = ditto.store.registerObserver(
  query: "SELECT * FROM cars") { queryResult in
    let diff = differ.diff(queryResult.items)

    // Extract current document IDs and dematerialize items
    let currentDocumentIds = queryResult.items.map { item in
        let id = item.value["_id"] as? String ?? "unknown"
        item.dematerialize() // Release memory after extracting data
        return id
    }

    // Handle deletions using stored IDs from previous emission
    for index in diff.deletions {
        let deletedId = previousDocumentIds[index]
        print("Deleted car with ID: \(deletedId)")
    }

    // Handle insertions using current IDs
    for index in diff.insertions {
        let insertedId = currentDocumentIds[index]
        print("Inserted car with ID: \(insertedId)")
    }

    // Handle updates using current IDs
    for index in diff.updates {
        let updatedId = currentDocumentIds[index]
        print("Updated car with ID: \(updatedId)")
    }

    // Store only the document IDs for next callback - no live references!
    previousDocumentIds = currentDocumentIds
}

​
Implementation Details

​
Handling Deleted and Moved Documents

With store observers, results from the previous event are no longer provided directly. You need to:
  1. Store the current results at the end of each callback: 
    previousItems = result.items;
  2. Use the indexes provided in diff.deletions or diff.moves to access deleted and moved documents from your stored previousItems.

​
Detecting the Initial Event

The legacy API’s event.isInitial flag isn’t available with the Differ. To detect the first callback: 
if (!previousItems) {
  // This is the initial callback
  // All items will appear as insertions in the diff
}
In the first callback, all items passed to differ.diff show up as insertions because the differ is initially empty.

​
Metadata Changes

The Differ ignores metadata changes when determining updates. For example:
  • Changing a document field and then setting it back to its original value will not be considered an update
  • This differs from the legacy API which would count any change as an update

​
Performance Considerations

Generating diffs may take significant time for very large result sets. Consider whether you truly need diff information for your use case.

​
Interactive Example

Try the interactive example on CodePen to see both approaches in action. Open your browser console to observe the results.
⌘I