Read and Edit Google Sheets Ranges in Jinba Flow

Use these tools when you know a spreadsheet ID and an A1-style range such as Sheet1!A1:D5. Connect a Google account with Google OAuth, then provide its token in the token configuration. For row records and worksheet tabs, use the Google Spreadsheet tools.

Read a cell range

GOOGLE_SHEETS_GET_SHEET requires spreadsheet_id and range. Its result can contain range, majorDimension, and values (an array of rows). Check result.values to verify that the expected cells were read.

- id: read_range
  tool: GOOGLE_SHEETS_GET_SHEET
  config:
    - name: token
      value: "<Google OAuth token>"
  input:
    - name: spreadsheet_id
      value: "<spreadsheet ID>"
    - name: range
      value: "Sheet1!A1:D5"

Replace the placeholders with a configured token and the ID from the spreadsheet URL. If the result is empty or the step fails, check the tab name, range, spreadsheet ID, and the connected account’s access.

Export rows as JSON records

To pass sheet data to an API, database, or AI step, turn the rows into records keyed by the header row. This keeps the structured-export task from the former advanced page:

- id: rows_to_records
  tool: PYTHON_SANDBOX_RUN
  needs: [read_range]
  input:
    - name: data_type
      value: OBJECT
    - name: code
      value: |
        import json
        text = r'''{{steps.read_range.result.values}}'''
        rows = json.loads(text) if text.strip() else []
        headers = rows[0] if rows else []
        records = [
            {h: (row[i] if i < len(row) else "") for i, h in enumerate(headers)}
            for row in rows[1:]
        ]
        print(json.dumps({"records": records, "count": len(records)}))

result.data.records holds one object per data row, and result.data.count the number of rows. All cell values are strings. When the range is empty the read step returns no values, so the code treats that as no rows.

Read multiple worksheet tabs

The former advanced page also showed processing several tabs in one workbook. Use one range read per tab, with the same spreadsheet ID:

- id: read_sales
  tool: GOOGLE_SHEETS_GET_SHEET
  config:
    - name: token
      value: "<Google OAuth token>"
  input:
    - name: spreadsheet_id
      value: "<spreadsheet ID>"
    - name: range
      value: "Sales!A1:D100"

- id: read_inventory
  tool: GOOGLE_SHEETS_GET_SHEET
  config:
    - name: token
      value: "<Google OAuth token>"
  input:
    - name: spreadsheet_id
      value: "<spreadsheet ID>"
    - name: range
      value: "Inventory!A1:D100"

Inspect each step’s result.values before combining the rows in a later step. The current tool returns values from the requested range; it does not expose the formatting and metadata fields claimed by the former advanced page. A later step can combine the tabs into one summary, such as the headers and row count of each:

- id: combine_tabs
  tool: PYTHON_SANDBOX_RUN
  needs: [read_sales, read_inventory]
  input:
    - name: data_type
      value: OBJECT
    - name: code
      value: |
        import json

        def load(text):
            rows = json.loads(text) if text.strip() else []
            return rows[0] if rows else [], rows[1:]

        sales_headers, sales = load(r'''{{steps.read_sales.result.values}}''')
        inventory_headers, inventory = load(r'''{{steps.read_inventory.result.values}}''')
        print(json.dumps({
            "tabs": {
                "Sales": {"headers": sales_headers, "row_count": len(sales)},
                "Inventory": {"headers": inventory_headers, "row_count": len(inventory)},
            },
            "total_rows": len(sales) + len(inventory),
        }))

Use result.data as input for a report step, or extend the code to join rows across tabs by a shared column.

Check data before using it

Read only the columns and rows the workflow needs, then check them before sending the rows to another tool. This example reads a bounded order range and reports rows with missing required cells or unexpected status values:

- id: read_orders
  tool: GOOGLE_SHEETS_GET_SHEET
  config:
    - name: token
      value: "<Google OAuth token>"
  input:
    - name: spreadsheet_id
      value: "<spreadsheet ID>"
    - name: range
      value: "Orders!A1:D100"

- id: check_orders
  tool: PYTHON_SANDBOX_RUN
  needs: [read_orders]
  input:
    - name: data_type
      value: OBJECT
    - name: code
      value: |
        import json
        text = r'''{{steps.read_orders.result.values}}'''
        rows = json.loads(text) if text.strip() else []
        headers = rows[0] if rows else []
        required = ["Order ID", "Customer", "Status"]
        allowed_status = {"open", "shipped", "cancelled"}
        problems = []
        for n, row in enumerate(rows[1:], start=2):
            record = {h: (row[i].strip() if i < len(row) else "") for i, h in enumerate(headers)}
            missing = [f for f in required if not record.get(f)]
            if missing:
                problems.append({"row": n, "issue": "missing " + ", ".join(missing)})
            elif record["Status"].lower() not in allowed_status:
                problems.append({"row": n, "issue": "unexpected status " + record["Status"]})
        print(json.dumps({"checked_rows": len(rows) - 1 if rows else 0, "problems": problems}))

result.data.problems lists each problem with its sheet row number. Branch on it, or send it to a person, before using the data. Replace the column names and allowed statuses with your own. The read tool returns cell values only; it does not report spreadsheet formatting, formulas as metadata, or validation rules.

Edit or append cell values

GOOGLE_SHEETS_EDIT_SHEET requires spreadsheet_id, range, and values. values is a JSON-encoded string of rows, not a YAML array. Set optional append_to_bottom to append rather than write to the range.

- id: write_range
  tool: GOOGLE_SHEETS_EDIT_SHEET
  config:
    - name: token
      value: "<Google OAuth token>"
  input:
    - name: spreadsheet_id
      value: "<spreadsheet ID>"
    - name: range
      value: "Sheet1!A1:B2"
    - name: values
      value: '[["Name","Status"],["Ada","Ready"]]'

A successful write returns result.updated_range. Run a read step against the same range to verify the written values. The old GET_SHEET ID is not the current tool ID; use GOOGLE_SHEETS_GET_SHEET.

​Read a cell range

​Export rows as JSON records

​Read multiple worksheet tabs

​Check data before using it

​Edit or append cell values

Read a cell range

Export rows as JSON records

Read multiple worksheet tabs

Check data before using it

Edit or append cell values