# Content comparison

> Compare content versions and inspect additions, deletions, and updates by product.

- Human documentation: [https://docs.univer.ai/overview/features/shared/compare](https://docs.univer.ai/overview/features/shared/compare)

- Agent Markdown: [https://docs.univer.ai/overview/features/shared/compare.md](https://docs.univer.ai/overview/features/shared/compare.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.6.0`

- Source: [features/shared/compare.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/compare.mdx)

---

Compare reports what changed between two versions. It accepts two fully reconstructed Unit snapshots and returns semantic differences in cells, paragraphs, pages, or records. It supports history review, verification of Agent output, and inspection of 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. |

Every change is an addition, a deletion, or an update. Temporary UI state such as zoom level and selection is not a content change. What Compare covers depends on the product adapter, and PDF is not included.

## How Snapshot and changesets contribute to Compare

A Snapshot stores the complete content state at a specific revision. A mutation describes a single content change, and a changeset groups mutations into an ordered commit. History stores versions and rebuilds them on demand. Compare describes the differences between two versions that have already been rebuilt.

```mermaid
flowchart LR
    S["Base Snapshot"]
    CA["Apply changesets A"]
    CB["Apply changesets B"]
    A["Version A"]
    B["Version B"]
    C["Product comparison"]
    D["Added · deleted · modified"]
    S --> CA --> A
    S --> CB --> B
    A --> C
    B --> C
    C --> D
```

To compare a history entry or a Worktree, load the base Snapshot and apply the subsequent changesets in order until the content reaches the target revision. Perform this reconstruction for each side, then pass both complete states to the product adapter. When the corresponding changesets are available, Compare aligns structural changes such as inserted or deleted rows and columns more accurately. When only the two complete states are provided, Compare still produces a Snapshot comparison.

Results follow the content model of each product: cells and rows or columns for Sheet, paragraphs for Doc, elements for Slide and Canvases, and fields and records for Relational Table. A temporary selection or zoom level is not a content change. Compare is read-only. Restoring a version and merging a Worktree are separate operations.

## Working with Server SDK and AI SDK

**Server SDK** supplies the Snapshots, the changesets, and the revision numbers, and it reconstructs the content to compare. An application passes both states and the history it has to Compare, receives structured differences, and presents a review interface on the web. See [history](https://docs.univer.ai/overview/features/shared/history.md) and [collaboration service extensions](https://docs.univer.ai/server/collaboration/extensions.md).

**AI SDK** loads and edits content in a Worktree and commits the Agent's result. An application can use the structured differences for Agent checks and further processing, while a person reviews the same changes visually and decides whether to merge them. See the [Agent Worktree workflow](https://docs.univer.ai/ai/worktree.md) and [content operations](https://docs.univer.ai/ai/content-operations.md).

## Comparison examples for five products

All five examples use the same Northstar launch plan. We created and submitted a complete baseline, edited it in a Worktree, and then opened Compare to inspect the changes.

In the change list, **blue** marks modifications, **green** additions, and **red** deletions. Read-only panes display the content before and after the change. Click an image to enlarge it.

### Sheet: budget and row structure

We updated the research and editor forecasts, removed Legacy tooling, added Accessibility QA, and recalculated the totals. Changed values and formula results appear alongside the row structure to which they belong.

![Sheet: budget and row structure](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/compare/sheets.jpg)

### Doc: release plan and paragraphs

We changed the launch date, the pilot-team count, and the completion target, removed the legacy approval text, and added a quality gate. The preserved context makes paragraph-level review easier.

![Doc: release plan and paragraphs](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/compare/docs.jpg)

### Slide: metrics and page elements

We updated three metric cards, removed the legacy approval block, and added a quality gate. The comparison covers text and elements on the same page rather than treating the page as a new image.

![Slide: metrics and page elements](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/compare/slides.jpg)

### Relational Table: fields and task records

We updated progress, status, and dates, renamed the date field, removed the legacy approval record, and added an accessibility task. Differences can be inspected by table, field, and record.

![Relational Table: fields and task records](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/compare/bases.jpg)

### Canvases: workflow and canvas elements

We updated the pilot size and launch date, moved the review node, and replaced the legacy approval card with a quality gate. Content and layout changes appear in their canvas context.

![Canvases: workflow and canvas elements](https://raw.githubusercontent.com/dream-num/documentation/dev/public/assets/features/compare/boards.jpg)

## Query and display results

Register the history comparison plugins and Facade extensions of the product, then call `compareUnitData()`. For repeated filtering and pagination, create a session with `prepareUnitComparison()` and call `query()`.

Display 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, so the first page is not necessarily the complete diff. Check the diagnostics and coverage status before presenting results.

See the [Unit Comparison API](https://docs.univer.ai/reference/facade/unit-comparison.md), [version history](https://docs.univer.ai/overview/features/shared/history.md), and [Worktree](https://docs.univer.ai/overview/features/shared/worktree.md).

[Back to all features](https://docs.univer.ai/overview/features.md)
