---
{
  "id": "platform.sheet.mutations-and-versioning",
  "topic": "sheet",
  "title": "Sheet mutations and optimistic versioning",
  "locale": "en",
  "version": "2026-07-25",
  "summary": "Every Sheet mutation chains the latest workbook version, preserves unrelated cells, checkpoints history, and reports validation violations as successful-write warnings.",
  "content": "`update_cells` and `append_rows` require optimistic locking. Read `version` from `get_workbook_summary` or `read_range`, pass it as `baseVersion`, then use the new `version` returned by a successful mutation as the next mutation’s base. Never reuse an old version or guess by adding one. A stale base returns `resource_conflict: version mismatch` with `details.baseVersion` and `details.currentVersion`; reread, inspect any changed cells, reconcile, and retry. Even a matching base can lose a database race and return `resource_conflict: workbook was modified concurrently`; handle it with the same reread-and-retry flow.\n\n`update_cells` is a sparse patch: it changes only listed single-cell keys, leaves every other cell untouched, and writes null as a blank without deleting a row or column. `append_rows` starts after the final non-empty used row, not after declared `rowCount`. An empty sheet starts at row 1. If needed, `rowCount` expands automatically. Its result reports one-based `startRow`, `appendedRows`, `appendedCells`, the actual A1 `range`, and the new `version`.\n\nBoth mutations can return `validationWarnings` entries with `cell`, `rule`, and `message`. These are soft warnings: the write succeeded. Tell the user about them; do not mark the call failed or retry it as though nothing was written. Every successful Agent mutation must create a workbook-history checkpoint in the same transaction. If the mandatory baseline or Agent checkpoint fails, the mutation fails rather than leaving an untracked write.\n\nSuccessful mutations broadcast the new workbook version and invalidate caches, so an open Sheet UI updates without asking the user to refresh. Batch large writes at no more than 5,000 cells per update, or 500 rows and 5,000 cells per append; refresh `baseVersion` from every batch result. Only `create_workbook` documents a dry-run result here. An update/append success result describes a live committed mutation and must never be presented as a dry run.\n",
  "aliases": [
    "baseVersion",
    "version mismatch",
    "modified concurrently",
    "update cells",
    "append rows",
    "validation warnings",
    "optimistic lock",
    "樂觀鎖",
    "並行修改"
  ],
  "tags": [
    "sheet",
    "mutation",
    "optimistic-locking",
    "checkpoints"
  ],
  "relatedActions": [
    "arinova.sheet.get_workbook_summary",
    "arinova.sheet.read_range",
    "arinova.sheet.update_cells",
    "arinova.sheet.append_rows"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/sheet/mutations-and-versioning/"
}
---

`update_cells` and `append_rows` require optimistic locking. Read `version` from `get_workbook_summary` or `read_range`, pass it as `baseVersion`, then use the new `version` returned by a successful mutation as the next mutation’s base. Never reuse an old version or guess by adding one. A stale base returns `resource_conflict: version mismatch` with `details.baseVersion` and `details.currentVersion`; reread, inspect any changed cells, reconcile, and retry. Even a matching base can lose a database race and return `resource_conflict: workbook was modified concurrently`; handle it with the same reread-and-retry flow.

`update_cells` is a sparse patch: it changes only listed single-cell keys, leaves every other cell untouched, and writes null as a blank without deleting a row or column. `append_rows` starts after the final non-empty used row, not after declared `rowCount`. An empty sheet starts at row 1. If needed, `rowCount` expands automatically. Its result reports one-based `startRow`, `appendedRows`, `appendedCells`, the actual A1 `range`, and the new `version`.

Both mutations can return `validationWarnings` entries with `cell`, `rule`, and `message`. These are soft warnings: the write succeeded. Tell the user about them; do not mark the call failed or retry it as though nothing was written. Every successful Agent mutation must create a workbook-history checkpoint in the same transaction. If the mandatory baseline or Agent checkpoint fails, the mutation fails rather than leaving an untracked write.

Successful mutations broadcast the new workbook version and invalidate caches, so an open Sheet UI updates without asking the user to refresh. Batch large writes at no more than 5,000 cells per update, or 500 rows and 5,000 cells per append; refresh `baseVersion` from every batch result. Only `create_workbook` documents a dry-run result here. An update/append success result describes a live committed mutation and must never be presented as a dry run.