Sheet mutations and optimistic 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.

Related actions

arinova.sheet.get_workbook_summary, arinova.sheet.read_range, arinova.sheet.update_cells, arinova.sheet.append_rows

Also known as

baseVersion, version mismatch, modified concurrently, update cells, append rows, validation warnings, optimistic lock, 樂觀鎖, 並行修改

---

Machine-readable Markdown · Knowledge index