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.

Related actions

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

Also known as

A1 notation, spreadsheet range, cell value, formula cell, display value, raw value, range error, 儲存格範圍, 公式

---

Machine-readable Markdown · Knowledge index