hot.dev/google-sheets / ::google::sheets::values

Cell values: read one range or many, overwrite, append, clear, the batch forms of each, and records on top (read-records, write-records, append-records).

Reading options (get-values, batch-get-values): valueRenderOption (FORMATTED_VALUE default, UNFORMATTED_VALUE, FORMULA), dateTimeRenderOption (SERIAL_NUMBER default, FORMATTED_STRING; ignored for FORMATTED_VALUE), majorDimension (ROWS default, COLUMNS).

Writing options (update-values, append-values, batch-update-values): valueInputOption (USER_ENTERED by default here, so numbers, dates and formulas parse as if typed; RAW stores strings as is), includeValuesInResponse, responseValueRenderOption, responseDateTimeRenderOption, and for append-values insertDataOption (OVERWRITE default, INSERT_ROWS). majorDimension sets the body's orientation.

Scopes. Reads use spreadsheets.readonly, writes spreadsheets; drive.file works for spreadsheets the app created or the user opened with it.

Values

BODY_KEYS

BODY_KEYS: Vec [
  "majorDimension"
]

Functions

append-records

fn (spreadsheet-id: Str, range: Str, records: Vec, columns: Vec): Map
fn (spreadsheet-id: Str, range: Str, records: Vec, columns: Vec, opts: Map): Map

Append records below the table at range, one row each, cells in columns order (match the sheet's header). Missing values are written as empty cells. Scope: spreadsheets.

::google::sheets::values/append-records(id, "Leads!A:C", [{name: "Ada", email: "ada@example.com", source: "web"}], ["name", "email", "source"])

append-values

fn (spreadsheet-id: Str, range: Str, values: Vec): Map
fn (spreadsheet-id: Str, range: Str, values: Vec, opts: Map): Map

POST /{id}/values/{range}:append - append rows after the last row of the table found at range (e.g. "Log!A:C"). insertDataOption: "INSERT_ROWS" inserts new rows instead of overwriting empty ones. Returns {tableRange, updates}. Scope: spreadsheets.

::google::sheets::values/append-values(id, "Log!A:C", [["2026-11-01", "deploy", "ok"]], {insertDataOption: "INSERT_ROWS"})

batch-clear-values

fn (spreadsheet-id: Str, ranges: Vec): Map
fn (spreadsheet-id: Str, ranges: Vec, opts: Map): Map

POST /{id}/values:batchClear - clear several ranges. Returns {clearedRanges}. Scope: spreadsheets.

batch-get-values

fn (spreadsheet-id: Str, ranges: Vec): Map
fn (spreadsheet-id: Str, ranges: Vec, opts: Map): Map

GET /{id}/values:batchGet - read several ranges in one call. Returns {spreadsheetId, valueRanges: [...]} in request order. Same options as get-values. Scope: spreadsheets.readonly.

batch-update-body

fn (data: Any, opts: Map): Map

The values:batchUpdate body (pure). data is a Vec of {range, values, majorDimension?} or a Map of range to rows. valueInputOption defaults to USER_ENTERED; the response options are copied from opts when set.

batch-update-values

fn (spreadsheet-id: Str, data: Any): Map
fn (spreadsheet-id: Str, data: Any, opts: Map): Map

POST /{id}/values:batchUpdate - write several ranges in one call.

::google::sheets::values/batch-update-values(id, {"Summary!B2": [[42]], "Summary!B3": [["=SUM(Data!C:C)"]]})

Returns {totalUpdatedCells, responses, ...}. Scope: spreadsheets.

clear-values

fn (spreadsheet-id: Str, range: Str): Map
fn (spreadsheet-id: Str, range: Str, opts: Map): Map

POST /{id}/values/{range}:clear - clear a range's values (formatting and validation are kept). Returns {clearedRange}. Scope: spreadsheets.

get-values

fn (spreadsheet-id: Str, range: Str): Map
fn (spreadsheet-id: Str, range: Str, opts: Map): Map

GET /{id}/values/{range} - read a range in A1 notation (e.g. "Sheet1!A1:C10", "Leads" for a whole sheet, or a named range). Returns {range, majorDimension, values?}; values is absent when the range is empty. Scope: spreadsheets.readonly.

raw ::google::sheets::values/get-values(id, "Data!A2:D", {valueRenderOption: "UNFORMATTED_VALUE"})

read-params

fn (opts: Map): Map

The query parameters a read sends (pure): only the options you set (valueRenderOption, dateTimeRenderOption, majorDimension, fields, ...).

read-records

fn (spreadsheet-id: Str, range: Str): Vec
fn (spreadsheet-id: Str, range: Str, opts: Map): Vec

Read a range whose first row is a header and return one Map per row (::google::sheets::records/rows-to-records). Uses valueRenderOption: "UNFORMATTED_VALUE" unless set, so numbers come back as numbers. Scope: spreadsheets.readonly.

leads ::google::sheets::values/read-records(id, "Leads!A:F")
filter(leads, (l) { eq(l.status, "new") })

update-values

fn (spreadsheet-id: Str, range: Str, values: Vec): Map
fn (spreadsheet-id: Str, range: Str, values: Vec, opts: Map): Map

PUT /{id}/values/{range} - overwrite a range with rows (a Vec of Vecs). Returns {updatedRange, updatedRows, updatedColumns, updatedCells, updatedData?}. See the namespace doc for options. Scope: spreadsheets.

value-range

fn (range: Str, values: Vec, opts: Map): Map

A ValueRange body (pure): {range, majorDimension, values} with majorDimension from opts (default ROWS).

write-params

fn (opts: Map): Map

The query parameters a write sends (pure): valueInputOption: "USER_ENTERED" unless set, plus your options; majorDimension stays in the body.

write-records

fn (spreadsheet-id: Str, range: Str, records: Vec): Map
fn (spreadsheet-id: Str, range: Str, records: Vec, columns: Vec): Map
fn (spreadsheet-id: Str, range: Str, records: Vec, columns: Vec, opts: Map): Map

Overwrite range with a header row (columns, default every key in order of first appearance) and one row per record. Clear the old data first with clear-values if the new table is shorter. Scope: spreadsheets.