Google Sheets

The Google Sheets connector reads from and writes to Google Sheets. It uses OAuth 2.0 for authentication and provides write boundary modes to protect human-managed data.

Authentication

auth:
  type: oauth
  provider: google
  client_id: "{{ secrets.GOOGLE_CLIENT_ID }}"
  client_secret: "{{ secrets.GOOGLE_CLIENT_SECRET }}"
  scopes:
    - https://www.googleapis.com/auth/spreadsheets

On first run, Radhflow opens a browser for consent. The refresh token is stored locally.

Reading from Sheets

sheets.read pulls a sheet range into a Table. The first row is treated as headers.

read-leads:
  type: source
  op: sheets.read
  params:
    spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
    sheet: Leads
    range: A1:E100
    auth: { type: oauth, provider: google }
  outputs:
    leads:
      type: Table
      schema:
        name: { type: string }
        email: { type: string }
        score: { type: number }

If range is omitted, the entire sheet is read.

Writing: dedicated sheet mode (default)

Radhflow creates and owns a separate tab. It clears and rewrites the tab on each run. Human data in other tabs is untouched.

write-scores:
  type: deterministic
  op: sheets.write
  params:
    spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
    sheet: "RF: Scored Leads"
    write_mode: dedicated
    auth: { type: oauth, provider: google }
  inputs:
    data: { type: Table, from: ref(score-leads.scored) }

The RF: prefix signals a machine-managed tab.

Writing: shared columns mode

Radhflow writes to specific columns in a shared sheet. Human-managed columns are preserved. Rows are matched by a key column for upsert.

write-enriched:
  type: deterministic
  op: sheets.write
  params:
    spreadsheet_id: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
    sheet: Leads
    write_mode: shared
    key_column: email
    owned_columns: [score, enriched_company, enriched_title]
    auth: { type: oauth, provider: google }
  inputs:
    data: { type: Table, from: ref(enrich.results) }

Only owned_columns are written. Human-added notes, tags, and status fields remain untouched.

Orphan handling

Rows present in the sheet but absent from the latest run are orphans. Radhflow flags them instead of deleting.

Behavior	Description
Flag column	Sets _rf_orphan to true for rows not in the latest run.
Preserve data	Human-annotated columns on orphan rows are never cleared.

orphan_handling:
  flag_column: _rf_orphan
  clear_owned: false    # set true to blank owned columns on orphans

Config reference

Field	Required	Default	Description
spreadsheet_id	Yes	—	Google Sheets document ID.
sheet	Yes	—	Tab name.
range	Read only	Entire sheet	Cell range (e.g. A1:E100).
write_mode	Write only	dedicated	dedicated or shared.
key_column	Shared only	—	Column for row matching in upsert.
owned_columns	Shared only	—	Columns Radhflow may write.
orphan_handling	No	Flag only	Orphan row behavior.
auth	Yes	—	OAuth config.