# Google Sheets Destination Config Reference


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



[Google Sheets](https://www.rudderstack.com/docs/destinations/streaming-destinations/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](#column-mapping). `credentials` is JSON, so its reference is single-quoted — see [Secrets](#secrets).

## Config keys

`config` accepts only the keys listed below. The [shared config key rules](https://www.rudderstack.com/docs/rudder-cli/destination-types/#config-key-rules) cover unknown keys, defaults, and immutability.

### Connection

<div class="rs-ckeys">
<div class="rs-ckey" id="credentials">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">credentials</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Contents of the JSON key file for a Google Cloud service account RudderStack writes to the spreadsheet as.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>The service account needs permission to edit the spreadsheet, and the Google Sheets API must be enabled in its Google Cloud project.</li>
<li>Only checked for presence locally.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <p>Supply it as a <code>{{ .VAR }}</code> reference rather than a literal — see <a href="#secrets" >Secrets</a>.</p>
<p>See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-sheets/#service-account-permissions" >Service account permissions</a> for creating the service account and its key.</p>

</div>

</div>

<div class="rs-ckey" id="sheet_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">sheet_id</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  ID of the spreadsheet: the part of its URL between <code>/spreadsheets/d/</code> and the next <code>/</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Only checked for presence locally.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <p><strong>Warning:</strong> Despite its name, <code>sheet_id</code> identifies the whole spreadsheet, not one sheet in it — it isn't the numeric <code>gid</code> in the URL. <code>sheet_name</code> picks the sheet.</p>
<p>For <code>https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=920137070</code>, <code>sheet_id</code> is <code>aBC-123_xYz</code>.</p>

</div>

</div>

<div class="rs-ckey" id="sheet_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">sheet_name</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Name of the sheet RudderStack writes to, as shown on its tab — for example <code>Sheet1</code>. The sheet must already exist in the spreadsheet.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Only checked for presence locally.</li>
</ul>

</div>

</div>

</div>

### Column mapping

<div class="rs-ckeys">
<div class="rs-ckey" id="event_key_map">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_key_map</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>array of objects</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Columns RudderStack writes for each event, in order, after a first <code>messageId</code> column.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>from</code> — the event field to read: a top-level field such as <code>event</code>, or a dotted path such as <code>properties.revenue</code> or <code>context.app.build</code>. RudderStack reads it from the root of the event first and, when nothing&rsquo;s there, looks it up in <code>properties</code>, then <code>traits</code>, then <code>context.traits</code> — so a bare <code>email</code> finds <code>properties.email</code>, <code>traits.email</code>, or <code>context.traits.email</code>, in that order.</li>
<li><code>to</code> — the column header.</li>
<li>A field the event doesn&rsquo;t carry leaves its cell empty, and so does a <code>0</code> or <code>false</code> value.</li>
<li>RudderStack writes <code>messageId</code> and the <code>to</code> headers into the sheet&rsquo;s first row, overwriting whatever is there, and appends each event as a new row below.</li>
<li>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 <code>messageId</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">event_key_map:
  - from: properties.revenue
    to: Revenue
  - from: context.app.build
    to: App Build</code></pre></div>
</div><p>See <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/google-sheets/#connection-settings" >Connection settings</a> for how to write paths to traits, properties, and nested fields.</p>
</div>

</div>

</div>

### Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under [Source types](#source-types). A key naming a source type this destination doesn't support fails validation.

<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach Google Sheets in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: cloud
  cloud: cloud</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

## 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](https://www.rudderstack.com/docs/sources/reverse-etl/) 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](https://www.rudderstack.com/docs/rudder-cli/yaml-retl-connections/#supported-destinations) — see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/).

**Info:** The dashboard additionally offers Google Sheets to AMP and Shopify sources. Rudder CLI doesn&#39;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](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/). Without it:

```text
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](https://www.rudderstack.com/docs/rudder-cli/destination-types/#secrets).

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Changes by release

<p>No changes since this type became available.</p>

For changes across every destination type, see [Destination Type Changes by Release](https://www.rudderstack.com/docs/rudder-cli/destination-types/changes/).

## See more

- [Google Sheets Destination](https://www.rudderstack.com/docs/destinations/streaming-destinations/google-sheets/) for service account setup, the Google Sheets API, and property mapping
- [Destination Type Reference for Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destination-types/) for the rules shared across destination types
- [Destination YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-destinations/) for the spec envelope