Google Sheets integration

Overview

Read, write, append, update, and manage data in Google Sheets spreadsheets. The node works at two levels: the Sheet resource operates on a single tab inside a spreadsheet — appending rows, upserting, updating matched rows, reading rows with filters, clearing ranges, deleting rows or columns, and creating or deleting tabs — while the Spreadsheet resource creates and deletes whole spreadsheets.

Rows are exchanged as key-value objects keyed on the sheet’s header row, so incoming item fields can be mapped onto columns automatically. Authentication is available via OAuth2 or a service account.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Google Sheets OAuth2, Google Service Account credentials. See the Credentials Guide for setup instructions.

Configure the one that matches the Authentication parameter — OAuth2 or service account, not both.

Resources

Resource	Value
Sheet	sheet
Spreadsheet	spreadsheet

Operations

Operation	Value	Description
Append Row	append	Append a new row to a sheet
Append or Update Row	appendOrUpdate	Upsert: update matching rows or append if no match
Clear	clear	Clear rows, columns, or entire sheet data
Create	create	Create a new sheet tab or spreadsheet
Delete	delete	Delete a sheet tab or spreadsheet
Delete Rows or Columns	deleteRowsOrColumns	Delete specific rows or columns from a sheet
Get Rows	getRows	Read rows from a sheet, optionally filtered
Update Row	update	Update rows matching specified column criteria

Create and Delete are offered for both resources; every other operation belongs to the Sheet resource.

Parameters

Append Row takes no parameters of its own — see All Operations. Append or Update Row takes no parameters of its own — see All Operations. Clear takes no parameters of its own — see All Operations. Delete Rows or Columns takes no parameters of its own — see All Operations. Get Rows takes no parameters of its own — see All Operations. Update Row takes no parameters of its own — see All Operations.

Sheet: Append Row

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
Data Mode	options	No	autoMapInputData	How to map incoming item data to sheet columns.
				Options: autoMapInputData (use item JSON fields; names must match column headers), defineBelow (manually specify column name/value pairs), nothing (do not append any row)
Fields to Send	fixedCollection	No	{}	(shown when Data Mode is defineBelow)
— Column Name	string	No	—	The sheet column header name.
— Field Value	string	No	—	The value to write into this column.
Options (appendOptions)	collection	No	{}
				Options: USER_ENTERED
— Cell Format	options	No	USER_ENTERED	How values are interpreted when written.
				Options: USER_ENTERED (interpret values as if typed by the user (formulas evaluated, dates parsed)), RAW (store values exactly as provided without parsing)
— Header Row	number	No	1	The 1-based row index that contains column headers.
— Use Google Sheets Append API	boolean	No	false	Use the native Google Sheets append endpoint instead of a targeted PUT. Ensures no data is overwritten.

Sheet: Append or Update Row

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
Matching Columns	string	Yes	—	Comma-separated column names used to identify matching rows (e.g. “email” or “id,region”).
Data Mode	options	No	autoMapInputData	How to map incoming item data to sheet columns.
				Options: autoMapInputData, defineBelow, nothing
Fields to Send	fixedCollection	No	{}	(shown when Data Mode is defineBelow)
— Column Name	string	No	—
— Field Value	string	No	—
Options (appendOrUpdateOptions)	collection	No	{}
				Options: USER_ENTERED
— Cell Format	options	No	USER_ENTERED
				Options: USER_ENTERED, RAW
— Header Row	number	No	1
— Data Start Row	number	No	2	First row that contains data (after the header).
— Use Google Sheets Append API	boolean	No	false

Sheet: Clear

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
Clear	options	No	wholeSheet	What to clear in the sheet.
				Options: wholeSheet, specificRows, specificColumns, specificRange
Keep First Row	boolean	No	false	Preserve the header row (row 1) when clearing the whole sheet. (shown when Clear is wholeSheet)
Start Row Number	number	No	1	The 1-based number of the first row to act on (the first row cleared, or the first row deleted). (shown when Clear is specificRows)
Number of Rows to Clear	number	No	1	(shown when Clear is specificRows)
Start Column	string	No	A	The letter of the first column to act on (e.g. A, B, C) — the first column cleared, or the first column deleted. (shown when Clear is specificColumns)
Number of Columns to Clear	number	No	1	(shown when Clear is specificColumns)
Range	string	Yes	A:F	A1 notation range to clear (e.g. “A1:D10” or “Sheet1!A1:D10”). (shown when Clear is specificRange)

Sheet: Create

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Title	string	Yes	New Sheet	Name for the new sheet tab or spreadsheet.
Options (sheetCreateOptions)	collection	No	{}
— Hidden	boolean	No	false	Whether the sheet is hidden in the UI.
— Right to Left	boolean	No	false	Whether the sheet uses RTL text direction.
— Sheet ID	number	No	0	Numeric sheet ID. Cannot be changed once set.
— Sheet Index	number	No	0	Position of the sheet tab within the spreadsheet (0-based).
— Tab Color	string	No	—	Hex color for the sheet tab (e.g. #FF0000).

Sheet: Delete

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.

Sheet: Delete Rows or Columns

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
To Delete	options	No	rows	Whether to delete rows or columns.
				Options: rows, columns
Start Row Number	number	No	2	The 1-based number of the first row to act on (the first row cleared, or the first row deleted). (shown when To Delete is rows)
Number of Rows to Delete	number	No	1	(shown when To Delete is rows)
Start Column	string	No	A	The letter of the first column to act on (e.g. A, B, C) — the first column cleared, or the first column deleted. (shown when To Delete is columns)
Number of Columns to Delete	number	No	1	(shown when To Delete is columns)

Sheet: Get Rows

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
Filters	fixedCollection	No	{}
— Column	string	No	—	The column header name to filter by.
— Value	string	No	—	The value the column must equal for a row to be included.
Combine Filters	options	No	AND	How multiple filter conditions are combined.
				Options: AND (all filter conditions must match), OR (at least one filter condition must match)
Return All	boolean	No	false	Whether to return all matching rows or only up to the limit.
Limit	number	No	50	Maximum number of rows to return. (shown when Return All is false)
Options (getRowsOptions)	collection	No	{}
				Options: FORMATTED_VALUE
— Output Formatting	options	No	FORMATTED_VALUE	How cell values are rendered in the output.
				Options: FORMATTED_VALUE (values as displayed in the sheet (with formatting applied)), UNFORMATTED_VALUE (raw computed values without display formatting), FORMULA (return the formula string instead of the calculated value)
— Header Row	number	No	1	1-based row index containing column headers.
— Data Start Row	number	No	2	1-based index of the first data row (after headers).
— Range	string	No	—	Limit reading to this A1-notation range (optional). If omitted, reads the whole sheet.

Sheet: Update Row

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).
Sheet Name	string	Yes	Sheet1	The name of the sheet tab to operate on.
Matching Columns	string	Yes	—	Comma-separated column names used to identify matching rows (e.g. “email” or “id,region”).
Data Mode	options	No	autoMapInputData	How to map incoming item data to sheet columns.
				Options: autoMapInputData, defineBelow, nothing
Fields to Send	fixedCollection	No	{}	(shown when Data Mode is defineBelow)
— Column Name	string	No	—
— Field Value	string	No	—
Options (updateOptions)	collection	No	{}
				Options: USER_ENTERED
— Cell Format	options	No	USER_ENTERED
				Options: USER_ENTERED, RAW
— Header Row	number	No	1
— Data Start Row	number	No	2

Spreadsheet: Create

Parameter	Type	Required	Default	Description
Title	string	No	—	Name for the new sheet tab or spreadsheet.
Sheets	fixedCollection	No	{}
— Title	string	No	—	Name of the sheet tab.
— Hidden	boolean	No	false	Whether the sheet is hidden in the UI.
Options (spreadsheetCreateOptions)	collection	No	{}
— Locale	string	No	—	Spreadsheet locale in ISO format (e.g. en_US).
— Recalculation Interval	options	No	—	How often volatile functions are recalculated.
				Options: leave empty for the default, ON_CHANGE, MINUTE, HOUR

Spreadsheet: Delete

Parameter	Type	Required	Default	Description
Spreadsheet ID	string	Yes	—	The ID of the Google Sheets spreadsheet (found in its URL).

All Operations

Parameter	Type	Required	Default	Description
Authentication	options	No	oAuth2	Authentication method to use.
				Options: oAuth2, serviceAccount
Google Account	credential	No	—	Connect or select your Google account. (shown when Authentication is oAuth2)
Service Account Email	string	Yes	—	The email address of the Google service account. (shown when Authentication is serviceAccount)
Private Key	string	Yes	—	The private key from the service account JSON key file. (shown when Authentication is serviceAccount)
Max Concurrency	number	No	5	Maximum number of items to process in parallel.

Output Data

The result replaces the item’s JSON — the incoming fields do not pass through.

Get Rows fans out: one output item per matching row. Each row is an object keyed on the header row, plus row_number — the 1-based position of the row in the sheet, which you need if you want to address that row again later:

{
  "Name": "Ada Lovelace",
  "Email": "ada@example.com",
  "Status": "Active",
  "row_number": 4
}

Every other operation produces exactly one item:

Operation	Output
sheet / append	success: true and appended — 1, or 0 when Data Mode is nothing.
sheet / appendOrUpdate	success: true, operation (update or append, telling you which branch ran) and rowsAffected.
sheet / update	success: true, updated (how many rows matched) and rows (their row numbers). When nothing matched: updated: 0 and a message.
sheet / clear	success: true and cleared — the A1 range that was cleared.
sheet / create	success: true, spreadsheetId and the new tab’s properties.
sheet / delete	success: true, spreadsheetId and deletedSheetId.
sheet / deleteRowsOrColumns	success: true, spreadsheetId, dimension (rows or columns) and the startIndex / endIndex that were removed.
spreadsheet / create	The new spreadsheet resource as Google returned it, including its spreadsheetId, spreadsheetUrl and sheets.
spreadsheet / delete	success: true and deletedSpreadsheetId.

Example Configuration

Append a row using the incoming item’s fields:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "append",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "dataMode": "autoMapInputData",
    "appendOptions": {
      "headerRow": 1,
      "cellFormat": "USER_ENTERED"
    }
  }
}

Append a row with explicit column mapping:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "append",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "dataMode": "defineBelow",
    "fieldsUi": {
      "fieldValues": [
        { "fieldId": "Name", "fieldValue": "{{ $json.fullName }}" },
        { "fieldId": "Email", "fieldValue": "{{ $json.email }}" }
      ]
    }
  }
}

Update rows matched on a column:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "update",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "matchingColumns": "email",
    "dataMode": "autoMapInputData",
    "updateOptions": {
      "headerRow": 1,
      "dataStartRow": 2
    }
  }
}

Upsert — update if a row matches, otherwise append:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "appendOrUpdate",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "matchingColumns": "id",
    "dataMode": "autoMapInputData",
    "appendOrUpdateOptions": {
      "headerRow": 1,
      "dataStartRow": 2
    }
  }
}

Read filtered rows:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "getRows",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "filtersUI": {
      "values": [
        { "lookupColumn": "Status", "lookupValue": "Active" }
      ]
    },
    "combineFilters": "AND",
    "returnAll": false,
    "limit": 100
  }
}

Clear a block of rows:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "clear",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "clearMode": "specificRows",
    "startRow": 5,
    "rowsToDelete": 10
  }
}

Delete rows permanently:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "deleteRowsOrColumns",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "sheetName": "Sheet1",
    "toDelete": "rows",
    "startRow": 2,
    "numberToDelete": 5
  }
}

Create a new tab in an existing spreadsheet:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "sheet",
    "operation": "create",
    "spreadsheetId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "title": "New Data Sheet",
    "sheetCreateOptions": {
      "hidden": false,
      "index": 1,
      "tabColor": "#4285f4"
    }
  }
}

Create a whole new spreadsheet:

{
  "type": "google_sheets",
  "parameters": {
    "resource": "spreadsheet",
    "operation": "create",
    "title": "My New Spreadsheet",
    "sheetsUi": {
      "sheetValues": [
        { "title": "Data", "hidden": false },
        { "title": "Summary", "hidden": false }
      ]
    },
    "spreadsheetCreateOptions": {
      "locale": "en_US",
      "autoRecalc": "ON_CHANGE"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Google Sheets reads, writes, appends, updates, clears, and deletes data in spreadsheets and their tabs. This tool is ideal for managing structured data, such as for reporting or data collection, especially when row-level operations or sheet creation are needed. It produces row data as key-value objects or confirmations of successful operations.

• Sheet Name is the tab, not the spreadsheet title. The one exception is Sheet → Create, where the Sheet Name (within spreadsheet) field holds the target spreadsheet ID and Title holds the new tab’s name.
• Auto-mapping matches on header text. With Data Mode autoMapInputData, an item property is written to the column whose header has the same name; properties with no matching header are ignored. Use defineBelow when the names differ.
• Header Row and Data Start Row describe your layout. If your sheet has a title block above the headers, raise both numbers so the node reads the right row as headers and starts writing below them.
• USER_ENTERED behaves like typing. Formulas evaluate and dates parse; switch Cell Format to RAW when a value such as a leading-zero code must be stored verbatim.
• Matching Columns can name more than one column. All named columns must match for a row to be considered the same record.
• Clear empties cells; Delete Rows or Columns removes them. Clearing leaves the grid the same size, deleting shifts everything below or to the right.
• Get Rows returns row_number. Keep it if you plan to come back and change that exact row.
• Get Rows fans out — each matching row becomes its own item, so downstream nodes process rows individually.