Select spec version:

Google Sheets Destination Config Reference

Beta

Complete Rudder CLI reference for the Google Sheets destination config keys, column mapping, source types, and secrets.

Available Plans

free
growth
enterprise

5 minute read

Google Sheets is a streaming destination. RudderStack appends each event as a row to one sheet of a Google Sheets spreadsheet, writing the event fields you map into columns.

In a Google Sheets destination spec:

type: googlesheets
definition_version: 1

Sample configuration

yaml

version: rudder/v1
kind: destination
metadata:
  name: google-sheets-prod
spec:
  id: google-sheets-prod
  display_name: Google Sheets Production
  type: googlesheets
  definition_version: 1
  enabled: true
  config:
    credentials: '{{ .GOOGLE_SHEETS_CREDENTIALS }}'
    sheet_id: 1kZ8rTq3mVn5Lp0XwYb7Hc2Jd9Fg4Sa6Ue1Ri8Ot3Qy
    sheet_name: Events

    event_key_map:
      - from: event
        to: Event
      - from: userId
        to: User ID
      - from: email
        to: Email
      - from: properties.revenue
        to: Revenue

    connection_mode:
      web: cloud
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics

The above example writes four columns after messageId, which RudderStack always puts first — see Column mapping. credentials is JSON, so its reference is single-quoted — see Secrets.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Connection

credentials

RequiredSecret

Type: string

Description: Contents of the JSON key file for a Google Cloud service account RudderStack writes to the spreadsheet as.

Notes:

The service account needs permission to edit the spreadsheet, and the Google Sheets API must be enabled in its Google Cloud project.
Only checked for presence locally.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

See Service account permissions for creating the service account and its key.

sheet_id

Required

Type: string

Description: ID of the spreadsheet: the part of its URL between /spreadsheets/d/ and the next /.

Notes:

Only checked for presence locally.

Despite its name, sheet_id identifies the whole spreadsheet, not one sheet in it — it isn’t the numeric gid in the URL. sheet_name picks the sheet.

For https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=920137070, sheet_id is aBC-123_xYz.

sheet_name

Required

Type: string

Description: Name of the sheet RudderStack writes to, as shown on its tab — for example Sheet1. The sheet must already exist in the spreadsheet.

Notes:

Only checked for presence locally.

Column mapping

event_key_map

Required

Type: array of objects

Description: Columns RudderStack writes for each event, in order, after a first messageId column.

Notes:

from — the event field to read: a top-level field such as event, or a dotted path such as properties.revenue or context.app.build. RudderStack reads it from the root of the event first and, when nothing’s there, looks it up in properties, then traits, then context.traits — so a bare email finds properties.email, traits.email, or context.traits.email, in that order.
to — the column header.
A field the event doesn’t carry leaves its cell empty, and so does a 0 or false value.
RudderStack writes messageId and the to headers into the sheet’s first row, overwriting whatever is there, and appends each event as a new row below.
Rudder CLI requires the key but accepts an empty list, and validates neither field of an entry. With an empty list, each row carries only messageId.

yaml

event_key_map:
  - from: properties.revenue
    to: Revenue
  - from: context.app.build
    to: App Build

See Connection settings for how to write paths to traits, properties, and nested fields.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Google Sheets in, using the modes in Source types.

Notes:

An entry is required for each source type you connect — see Connect a source.

yaml

connection_mode:
  web: cloud
  cloud: cloud

consent_management

Type: object

Description: Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.

Source types

Google Sheets accepts events from these source types in the mentioned connection modes:

Source type	Connection mode
`android`	`cloud`
`android_kotlin`	`cloud`
`ios`	`cloud`
`ios_swift`	`cloud`
`web`	`cloud`
`unity`	`cloud`
`react_native`	`cloud`
`flutter`	`cloud`
`cordova`	`cloud`
`cloud`	`cloud`
`warehouse`	`cloud`

Every source type is cloud only — RudderStack writes to the spreadsheet from its servers, never in device mode.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Google Sheets to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'google-sheets-prod' config has no 'connection_mode' entry for source type 'web'

Google Sheets needs no additional config keys to connect a source of any type.

Secrets

credentials is the only secret key. Write it as a {{ .VAR }} reference and supply the value at apply time:

yaml

config:
  credentials: '{{ .GOOGLE_SHEETS_CREDENTIALS }}'

bash

export RUDDER_GOOGLE_SHEETS_CREDENTIALS="$(cat service-account.json)"
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

credentials is JSON, so write its reference in single quotes, as above. Rudder CLI pastes the value into the YAML before parsing it, and the JSON’s double quotes would end a double-quoted string.
rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

No changes since this type became available.

For changes across every destination type, see Destination Type Changes by Release.

See more

Google Sheets Destination for service account setup, the Google Sheets API, and property mapping
Destination Type Reference for Rudder CLI for the rules shared across destination types
Destination YAML Reference for the spec envelope

Google Sheets Destination Config Reference

Sample configuration

Config keys

Connection

Column mapping

Per-source keys

Source types

Connect a source

Secrets

Changes by release

See more

Questions? Let's figure it out together.