Google Sheets — Find row

Google Sheets — Find row

Type: googlesheets-find-row  ·  Package: Google Sheets Activities v1.0.5  ·  Output: Dictionary<string,object>

Finds the first row where a column matches a value, and returns the whole row as a dictionary. It is the equivalent of a VLOOKUP: locate a customer, order or invoice record by its identifier and read the rest of its data.

How it works

Reads range (default A:Z) of the sheet sheet and searches for value in the column column, row by row. Returns the first matching row.

• column takes a letter (A, B, AA) or a number (1, 2). It is counted from the first column of range: with range = "C:H", column A (or 1) is column C of the sheet.
• The comparison ignores case and leading/trailing spaces, and uses the text displayed in the cell.
• With has-headers = true (default), the first row of the range holds the headers: it is not searched and it provides the dictionary keys.
• Only the columns in range are read: with the default value, columns after Z do not appear in the result.

Required parameters

Parameter	Type	Default	Description
column	string	—	Column to search: letter (A, B) or number (1, 2), counted from the start of range.
value	object	—	Value to find; compared as text, ignoring case and leading/trailing spaces.

Optional parameters

Parameter	Type	Default	Description
session	ZoanGoogleSheetsSession	—	Session from Google Sheets — Open. Inside Open’s body it is inherited and you can leave it empty.
sheet	string	—	Sheet to search. If empty, the first sheet is used.
range	string	A:Z	Search range in A1 notation.
has-headers	bool	true	Use the first row of the range as the dictionary keys. If false, keys are Column1, Column2, …

Output

Returns a Dictionary with the row found, or null if no row matches (or the range is empty):

• With has-headers = true: one key per header, with the exact text of row 1 (row["Customer"], row["Total"]). If the row found is shorter than the headers, the missing keys are null.
• With has-headers = false: keys Column1, Column2, … up to the last cell with data in that row.
• It always includes the __row__ key (int): the number of the row found, counted from the first row of range and including the header row. With the default range it matches the sheet row number, so you can use it to write in that same row.

Values are text as displayed in the sheet.

Repeated or empty headers

If two headers have the same text, the dictionary keeps only the last one. An empty header produces the key "". Give every column a unique title.

Common errors

Message	Cause and fix
'column' is required.	column is empty or its expression returned null.
No Google Sheets session available. Provide 'session' from a googlesheets-open activity, or place this activity inside the Open activity's body …	The activity is outside Open’s body and received no session. Move it inside the body or pass the saved session.
The service sheets has thrown an exception. HttpStatusCode is …	Google rejected the call: missing sheet or range, no access, expired token or quota exceeded. See Google API errors.

Not finding the row is not an error: the output is null.

Example

Look up a customer by tax ID and update their status in the same row:

Google Sheets — Find row   session = book   sheet = "Customers"   column = "A"   value = taxId   → output: customer
If   condition = !isNull(customer)
 └─ then:
      Log   message = "Customer: " + str(customer["Name"]) + " (row " + customer["__row__"] + ")"
      Google Sheets — Write cell   session = book   sheet = "Customers"
                                   cell = "E" + customer["__row__"]   value = "Updated"

Related activities

• Find cell — find a specific cell.
• Read sheet — read everything and filter several rows at once.