> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truestate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Sheets

> Authorise Google, choose a spreadsheet, and import a worksheet range.

Use this integration to turn a Google Sheets range into a Dawn dataset. You need a Google account that can read the spreadsheet.

## Authentication and data flow

You sign in with Google and approve access; Dawn receives OAuth tokens rather than your Google password. The connection identifies the spreadsheet, and the import identifies the worksheet range.

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Dawn
    participant Google
    You->>Dawn: Select Authorize account
    Dawn->>Google: Open consent for Sheets read access
    You->>Google: Sign in and approve
    Google-->>Dawn: Return authorisation code
    Dawn->>Google: Exchange code for tokens
    Google-->>Dawn: Access token and refresh token when issued
    Dawn->>Dawn: Save tokens as a credential
    Note over Dawn,Google: When an import runs
    Dawn->>Google: Request the selected spreadsheet range
    Google-->>Dawn: Cell values
    Dawn->>Dawn: Use first row as headers and save dataset
```

For later runs, Dawn can obtain a new access token using the saved refresh token when needed. If refresh is unavailable or the grant has been revoked, reauthorise the credential. The approved scope and the Google account's access determine which spreadsheets are readable; entering one spreadsheet URL does not narrow the OAuth grant.

## Permissions

Dawn requests `https://www.googleapis.com/auth/spreadsheets.readonly` and offline access so scheduled work can refresh authorisation without requiring you to sign in for every run. It does not request a Sheets write scope in this flow.

The OAuth scope covers spreadsheet read access available to the authorised account. The spreadsheet URL in your Dawn connection selects what to use; it does not narrow the scope of the Google authorisation. See [Google's scope reference](https://developers.google.com/workspace/sheets/api/scopes).

## Set up the connection

1. Open **Connections → New connection**.
2. Select **Google Sheets** and enter a descriptive name.
3. Paste the **Spreadsheet URL or ID**.
4. Use **Authorize account**, sign in to the appropriate Google account, and review the consent screen. Alternatively, select an existing Google Sheets credential.
5. Save the connection.

If your Google Workspace organisation restricts third-party apps, an administrator may need to allow the authorisation.

## Choose the data to import

Set the import's sheet range using A1 notation, for example `Sales!A1:F5000` or `'Monthly Sales'!A:F`. Include the header row. If the range is left blank, the connector uses the first worksheet.

The first row of the returned range becomes the column names. Subsequent rows become data records. Use a consistent table rather than merged cells or several unrelated tables on one sheet.

```text theme={null}
Use this Google Sheets connection to import the range 'Monthly Sales'!A1:F5000
into monthly_sales. Create an import pipeline, then let me review it.
```

After running the import, check the number of rows, headers, date values, and totals. A range ending at row 5000 will omit later rows; choose the range deliberately as the sheet grows.

## Refresh and disconnect

Run the import again to read updated values. Configure a repeatable pipeline when you need scheduled refreshes. Changes to the source sheet do not automatically update a previously imported dataset.

To change accounts, authorise a new credential and select it in the connection. To revoke access, remove the app's access in Google and disable the Dawn connection. Previously imported data remains in Dawn.

## Troubleshooting

| Problem                               | Check                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------- |
| Spreadsheet cannot be read            | The authorised account can open it, and the URL or ID is correct.           |
| Wrong worksheet imported              | Supply an explicit sheet range rather than leaving it blank.                |
| Empty or missing rows                 | Check the range boundaries and whether the source cells contain values.     |
| Scheduled refresh loses authorisation | Reauthorise the credential; ask support if token refresh continues to fail. |
| Unexpected column names               | Ensure the first row of the selected range contains the headers.            |