Google Sheets

io.google-sheets Storage v0.1.0

Works with Google Sheets (API v4): append rows, read a range (as objects via the header row), update or clear a range, create a spreadsheet, or add a sheet. Uses a Google OAuth2 credential's access token.

Ports

Direction	Port	Label
Input	`input`	Payload
Output	`output`	Result

Properties

Property	Type	Default	Description
Credential `credentialId`	`credential`	`""`	Use a stored credential for this connection — its fields are filled in at run start. Pick "None" to enter the connection details manually. accepts credential templates: `google-oauth2`
Access token `accessToken`	`string`	`""`	Google OAuth2 access token — use ${credential.google-oauth2.accessToken}. Empty is allowed here; it must resolve by run time.
Operation `operation`	`select`	`"append"`	Append rows, read a range, update a range, clear a range, create a spreadsheet, or add a sheet to an existing spreadsheet. `appendreadupdateclearcreateSpreadsheetaddSheet`
Spreadsheet ID `spreadsheetId`	`string`	`""`	The spreadsheet's ID — the long token in its URL between /d/ and /edit. Shown when `(operation ?? "append") !== "createSpreadsheet"`
Range `range`	`string`	`""`	A1-notation range, e.g. Sheet1!A1:D10 or just Sheet1. Shown when `sheetsRangeOps(operation)`
Rows `values`	`json`	`[]`	Rows to write as a JSON array — arrays of cells ([[1, "a"], …]) or objects (columns from the first row's keys). Leave empty to use the rows from the input. Shown when `["append", "update"].includes(operation ?? "append")`
Rows field `valuesPath`	`string`	`""`	Dot-path to the rows on the input (overrides the static rows). Leave blank to use the whole payload when it is an array. Shown when `["append", "update"].includes(operation ?? "append")`
Value input `valueInputOption`	`select`	`"USER_ENTERED"`	USER_ENTERED parses values like typed input (dates, formulas); RAW stores them verbatim. `USER_ENTEREDRAW` Shown when `["append", "update"].includes(operation ?? "append")`
Insert mode `insertDataOption`	`select`	`"INSERT_ROWS"`	INSERT_ROWS inserts new rows for the data; OVERWRITE writes over existing cells after the table. `INSERT_ROWSOVERWRITE` Shown when `(operation ?? "append") === "append"`
Major dimension `majorDimension`	`select`	`"ROWS"`	Read the grid row-by-row or column-by-column. `ROWSCOLUMNS` Shown when `operation === "read"`
Value render `valueRenderOption`	`select`	`"UNFORMATTED_VALUE"`	How cell values come back: unformatted (raw numbers), formatted (as displayed), or the formulas themselves. `UNFORMATTED_VALUEFORMATTED_VALUEFORMULA` Shown when `operation === "read"`
First row is headers `firstRowHeaders`	`boolean`	`true`	Turn each data row into an object keyed by the header row (blank/extra columns become col<N>). Shown when `operation === "read"`
Title `title`	`string`	`""`	Title of the new spreadsheet. Shown when `operation === "createSpreadsheet"`
Sheet titles `sheetTitles`	`json`	`[]`	Optional JSON array of sheet (tab) names to create, e.g. ["Orders", "Summary"]. Shown when `operation === "createSpreadsheet"`
Sheet title `sheetTitle`	`string`	`""`	Name of the sheet (tab) to add. Shown when `operation === "addSheet"`
Base URL `baseUrl`	`string`	`""`	Sheets API base URL (override for testing; also NINER_GOOGLE_SHEETS_API_BASE). Blank = https://sheets.googleapis.com.
Timeout (ms) `timeoutMs`	`int`	`30000`	Abort each API request after this many milliseconds.

Examples

Append order rows (the shipped demo)

Objects in a list become rows — keys map to columns in order:

{
  "id": "append",
  "type": "io.google-sheets",
  "config": {
    "accessToken": "${credential.google-oauth2.accessToken}",
    "operation": "append",
    "spreadsheetId": "<your spreadsheet id>",
    "range": "Orders!A:D",
    "valuesPath": "orders",
    "valueInputOption": "USER_ENTERED",
    "insertDataOption": "INSERT_ROWS"
  }
}

With input { "orders": [ { "id": 1, "customer": "Smith, John", "total": 149.95 }, … ] } each order object appends as one row.

Read a range into items

{ "operation": "read", "spreadsheetId": "<id>", "range": "Orders!A1:D50" }

Tips

OAuth client setup is the hard part — redirect URI, enabled APIs, test users and the 7-day testing caveat are walked through in the Google Sheets guide.
USER_ENTERED lets Sheets parse "149.95" and "2026-06-12" the way typing would; RAW stores exactly the strings you send.
The spreadsheet id is the long path segment of the sheet’s URL (docs.google.com/spreadsheets/d/<THIS>/edit).
Token refresh is automatic: the vault refreshes the access token whenever a run resolves a near-expiry credential — deployed apps included.

This page is generated from the node registry by gen-node-docs.mjs on every site build — ports, properties, defaults and visibility rules cannot drift from the code. The examples above are hand-authored and merged in.