Content comparison
Compare content versions and inspect additions, deletions, and updates by product.
Compare explains what changed between two versions. It reads two fully reconstructed Unit snapshots and returns semantic differences in cells, paragraphs, pages, or records. Use it to review history, agent output, or a Worktree.
Differences by product
| Product | Example comparison objects |
|---|---|
| Sheet | Worksheets, cell values and formulas, rows, columns, styles, and registered resources such as charts. |
| Doc | Paragraphs, text, styles, tables, blocks, and drawings. |
| Slide | Pages, elements, geometry, styles, layouts, and themes. |
| Relational Table | Tables, fields, records, and views. |
| Canvases | Pages, elements, and associated resources. |
Changes are additions, deletions, or updates. Temporary UI state such as zoom and selection is excluded. Coverage depends on the product adapter; PDF is not included.
How Snapshot and changesets contribute to Compare
A Snapshot stores the complete content state at a revision. A mutation describes a specific content change; a changeset groups mutations into an ordered commit. History stores and reconstructs versions; Compare explains the differences between two reconstructed versions.
For history or Worktree comparisons, load a base Snapshot and apply subsequent changesets in order to reconstruct each target revision. Pass the complete states to the product adapter. Available changesets can also improve alignment for structural changes such as inserted or deleted rows and columns. Snapshot comparison is available when only the two complete states are provided.
Results follow each product's content model: Sheet cells and rows or columns, Doc paragraphs, Slide and Canvases elements, and Relational Table fields and records. Temporary selections and zoom are not content changes. Compare is read-only; restoring a version and merging a Worktree are separate operations.
Working with Server SDK and AI SDK
Server SDK supplies Snapshots, changesets and revision numbers and reconstructs the content to compare. The application passes both states and available history to Compare, obtains structured differences, and displays a review interface on the web. See history and collaboration service extensions.
AI SDK loads and edits content in a Worktree and commits the Agent's result. Applications can use structured differences for Agent checks and further processing, while humans review the same changes visually before deciding whether to merge. See the Agent Worktree workflow and content operations.
Comparison examples for five products
These examples share a Northstar launch plan. We created and submitted a complete baseline, edited it in a Worktree, then opened Compare to inspect the changes.
In the change list, blue marks modifications, green additions, and red deletions. Read-only panes show the before and after content. Click an image to enlarge it.
Sheet: budget and row structure
Update research and editor forecasts, remove Legacy tooling, add Accessibility QA, and recalculate totals. Inspect changed values and formula results alongside the corresponding row structure.
Doc: release plan and paragraphs
Update the launch date, pilot-team count and completion target. Remove the legacy approval text and add a quality gate. Preserved context makes paragraph-level review easier.
Slide: metrics and page elements
Update three metric cards, remove the legacy approval block and add a quality gate. Compare text and elements on the same page rather than treating the page as a new image.
Relational Table: fields and task records
Update progress, status and dates, rename the date field, remove the legacy approval record and add an accessibility task. Inspect differences by table, field and record.
Canvases: workflow and canvas elements
Update pilot size and launch date, move the review node, and replace the legacy approval card with a quality gate. Inspect content and layout changes in their canvas context.
Query and display results
Register the product’s history comparison plugins and Facade extensions, then call compareUnitData(). For repeated filtering and pagination, create a session with prepareUnitComparison() and call query().
Show a summary first, then drill into worksheets, pages, or tables. Request change lists or full before/after values as needed. Default detail results are bounded: the first page is not necessarily the complete diff. Check diagnostics and coverage status before presenting results.
See the Unit Comparison API, version history, and Worktree.
How is this guide?