---
{
  "id": "platform.sheet.ranges-and-cell-values",
  "topic": "sheet",
  "title": "Sheet ranges and cell values",
  "locale": "en",
  "version": "2026-07-29",
  "summary": "Sheet reads expose bounded values, formula source, cached results, and explicit completeness metadata.",
  "content": "Sheet ranges use A1 notation such as `A1`, `A1:D20`, or `AA1:AZ100`; reversed ranges such as `D20:A1` are invalid. `Sheet1!A1`, whole-column `A:A`, whole-row `1:1`, and R1C1 are unsupported. Select a tab with `sheetId` or `sheetName`; ID wins when both are supplied. A name must match exactly; duplicate names return an ambiguous error, so use `list_sheets` and retry with an ID. Omitting both chooses the first tab.\n\nEvery `update_cells.cells` key must be one cell such as `\"A1\"`; `\"A1:B2\"` is rejected. Expand a rectangle into individual keys or use `append_rows`. A JSON null writes a blank and clears that cell’s value. Booleans, numbers, and strings retain their public scalar type; other JSON values are stringified. A string beginning with `=` is stored as a formula cell.\n\nThe server calculates bounded `SUM(A1:B2)` formulas immediately after Agent writes and appends. Other formula source is preserved for the browser formula engine and may have an empty or previously cached result. `read_range.valueMode` defaults to `display`, which returns cached formatted display strings when present; `raw` returns the underlying scalar. Every read also returns a same-shaped `formulas` matrix (source begins with `=`) and `formulaResults` matrix, plus `empty`, `usedRange`, `complete`, `truncated`, and the workbook’s current `version`.\n\nFor a large workbook, begin with `get_workbook_summary`, whose preview is limited to 20 rows. Check `previewComplete` and `previewTruncated`; when truncated, `readRangeRequired` names the occupied range required before a workbook-wide claim. `read_range.complete` is true only when the request covers `usedRange`. Use additional A1 windows when action limits require them.\n",
  "aliases": [
    "A1 notation",
    "spreadsheet range",
    "cell value",
    "formula cell",
    "display value",
    "raw value",
    "range error",
    "儲存格範圍",
    "公式"
  ],
  "tags": [
    "sheet",
    "ranges",
    "cells",
    "formulas"
  ],
  "relatedActions": [
    "arinova.sheet.list_sheets",
    "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/ranges-and-cell-values/"
}
---

Sheet ranges use A1 notation such as `A1`, `A1:D20`, or `AA1:AZ100`; reversed ranges such as `D20:A1` are invalid. `Sheet1!A1`, whole-column `A:A`, whole-row `1:1`, and R1C1 are unsupported. Select a tab with `sheetId` or `sheetName`; ID wins when both are supplied. A name must match exactly; duplicate names return an ambiguous error, so use `list_sheets` and retry with an ID. Omitting both chooses the first tab.

Every `update_cells.cells` key must be one cell such as `"A1"`; `"A1:B2"` is rejected. Expand a rectangle into individual keys or use `append_rows`. A JSON null writes a blank and clears that cell’s value. Booleans, numbers, and strings retain their public scalar type; other JSON values are stringified. A string beginning with `=` is stored as a formula cell.

The server calculates bounded `SUM(A1:B2)` formulas immediately after Agent writes and appends. Other formula source is preserved for the browser formula engine and may have an empty or previously cached result. `read_range.valueMode` defaults to `display`, which returns cached formatted display strings when present; `raw` returns the underlying scalar. Every read also returns a same-shaped `formulas` matrix (source begins with `=`) and `formulaResults` matrix, plus `empty`, `usedRange`, `complete`, `truncated`, and the workbook’s current `version`.

For a large workbook, begin with `get_workbook_summary`, whose preview is limited to 20 rows. Check `previewComplete` and `previewTruncated`; when truncated, `readRangeRequired` names the occupied range required before a workbook-wide claim. `read_range.complete` is true only when the request covers `usedRange`. Use additional A1 windows when action limits require them.