> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/google-sheets.md).

# Google Sheets

[Google Sheets](https://www.google.com/sheets/about/) is a cloud spreadsheet service. Nilus uses Google Sheets as a batch source to load a single sheet (range) at a time into a downstream warehouse, useful for analyst-maintained reference tables and ad-hoc inputs.

Under the hood, Nilus calls the [Google Sheets API](https://developers.google.com/sheets/api) using a Google Cloud service account. The spreadsheet must be shared with the service account's email (`...@<project>.iam.gserviceaccount.com`).

## Requirements

Connectivity and credentials must both be in place before the pipeline can run.

### Connectivity

* The Nilus runtime must be able to reach `https://sheets.googleapis.com` over HTTPS.
* The service account email must be added as a **Viewer** of the spreadsheet (or higher).
* The Google Cloud project must have the Google Sheets API enabled.

{% hint style="info" %}
Service-account JSON keys are sensitive. Store via Nilus secrets/projections (or use `credentials_base64` from a secret) rather than committing the JSON to YAML.
{% endhint %}

### Required parameters

| Parameter            | Required                                          | Default | Description                                                                                                              |
| -------------------- | ------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `credentials_path`   | Yes                                               | -       | Path to the service-account JSON key file inside the runtime container. Use `credentials_base64` for inline credentials. |
| `credentials_base64` | One of `credentials_path` or `credentials_base64` | -       | Base64-encoded contents of the service-account JSON. Use this when projecting the credential from a secret.              |
| `spreadsheet_id`     | Yes                                               | -       | Google Sheets spreadsheet ID (the long alphanumeric segment of the sheet URL).                                           |

### URI format

```
gsheets://?credentials_path=<service-account-json-path>&credentials_base64=<credentials-base64>&spreadsheet_id=<spreadsheet-id>
```

## Source table syntax

| Form                   | Description                                                                      |
| ---------------------- | -------------------------------------------------------------------------------- |
| `<sheet_name>`         | Read the entire sheet by tab name (e.g. `Orders`). Headers are in the first row. |
| `<sheet_name>!<range>` | Read a specific A1 range (e.g. `Orders!A1:F1000`).                               |

## Source options

| Option            | Required      | Description                                                                                                                   |
| ----------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `source_table`    | Yes           | One of the resources in the [source table syntax](#source-table-syntax) table.                                                |
| `incremental_key` | Not supported | Google Sheets ingestion is snapshot-oriented; use `replace` unless downstream semantics require another destination strategy. |

## Sink options

| Option                 | Required | Description                                                                                 |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `dest_table`           | Yes      | Destination table name. Use one stable target per source resource so re-runs merge cleanly. |
| `incremental_strategy` | Yes      | Destination write behavior. Use `replace` for normal sheet snapshots.                       |

## Sample Nilus config

```yaml
name: gsheets-orders-a1-f1000-batch
version: v1alpha
type: nilus
spec:
  type: batch
  compute: universe-compute
  source:
    address: gsheets://?credentials_path=/etc/dataos/secret/gsheets-sa.json&spreadsheet_id=1AbCdEfGhIjKlMnOpQrStUvWxYz0123456789
    options:
      source_table: Orders!A1:F1000
  sink:
    address: dataos://warehouse?purpose=rw
    options:
      dest_table: ops.gsheets_orders
      incremental_strategy: replace
```

## Behavior and capabilities

* **Pipeline mode**: Google Sheets runs as a `batch` source.
* **Object selection**: set `source.options.source_table` to one sheet tab or A1 range. Each pipeline reads one sheet/range at a time.
* **Fetch semantics**: Google Sheets loads the selected range as a snapshot; use `replace` for destinations unless downstream logic intentionally appends historical snapshots.
* **Schema inference**: the first row is treated as the header row, and later rows are inferred from spreadsheet cell values.
* **Operational fit**: this connector is best for small reference tables, analyst-maintained inputs, and controlled spreadsheet ranges rather than high-volume application data.

## Troubleshooting

| Symptom             | Likely cause                                                          | Resolution                                                                                          |
| ------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `PERMISSION_DENIED` | Spreadsheet is not shared with the service account email.             | Open the sheet → Share → add the service account email with Viewer access.                          |
| `Sheet not found`   | Tab name in `source_table` does not match.                            | Verify the tab name (case-sensitive); use the exact spelling from the bottom of the sheet.          |
| `SERVICE_DISABLED`  | Google Sheets API not enabled in the service account's Cloud project. | Enable the API in Cloud Console → APIs & Services.                                                  |
| Wrong column types  | First row treated as headers; subsequent rows mixed types.            | Normalize the data in the sheet, or set `incremental_strategy: replace` and cast in downstream SQL. |

## Related docs

* [Batch sample configs](/concepts/resources/nilus/batch/sample-configs.md)
* [Understanding Batch Pipeline Config](/concepts/resources/nilus/batch/pipeline-config.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/google-sheets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.