# Google Sheets

Connect Google Sheets and a sheet becomes a <Term id="table">table</Term> in <Term id="nexus">Nexus</Term>: queried, charted, joined with everything else, and refreshed when the sheet changes.

Your <Term id="studio">Studio</Term>'s AI prepares the connection; you finish it by signing in with Google.

<Callout type="info" title="Only need it once?">
  If the sheet does not change, download it as a file and use **Turn a spreadsheet into a table** on the Add data page instead. See [Add data](/docs/data/add-data).
</Callout>

## Before you start [#before-you-start]

- A <Term id="project">project</Term>. Its Studio's AI does the work. See [Create a project](/docs/projects/create-a-project).
- A Google account that can open the sheet.
- Ideally one header row and one record per row. Mention merged cells, totals rows or notes above the header in your request.

## Connect it [#connect-it]

<Steps>
<Step>
### Open Google Sheets [#open-google-sheets]
Go to <AppLink to="connectors" />, search for **Google Sheets** and open it.
</Step>
<Step>
### Send the request to a project's AI [#send-the-request-to-a-projects-ai]
Under **Connect it with your Studio's AI**, choose the **Project** that should use Google Sheets. **What the AI is asked** starts as "Connect Google Sheets to this project so it can read a spreadsheet as data to analyse and map." Edit it to say exactly what you want, for example: "Load the Orders tab of the 2026 Orders sheet into a table called orders and refresh it every hour". Then select **Send to AI**.

The AI starts at once if the Studio is open, or when it next opens. Select **Open Studio** to go there.

<Screenshot src="/docs/_media/connect-data-with-ai-in-dashboard-data-page.png" alt="Connecting Google Sheets with a project's AI from the Connectors page" />
</Step>
<Step>
### Finish the connection [#finish-the-connection]
The AI drafts the connection and never asks for a key in the chat. The draft shows as **Waiting for you**. Select **Connect** to open the **Connect Google Sheets** dialog.

Choose **Sign in with Google**. The dialog shows the only site this sign-in is used with. Sign in with the Google account that can see the files and approve the access Google asks for. The connection then shows **Signed in as** your account.

Google's file picker then opens. Pick the spreadsheet (or several). The AI reaches only these and files it creates itself.
</Step>
<Step>
### Choose what the AI may do [#choose-what-the-ai-may-do]
Under **What the AI may do with it**, choose **Can read** (nothing there changes) or **Can read and change** (the AI may also add, change and remove things). Then select **Connect**.

<Screenshot src="/docs/_media/slack-connector-how-to-connect-in-ui.png" alt="The Connect Google Sheets dialog with the access choice" />
</Step>
<Step>
### Test it and tell the AI [#test-it-and-tell-the-ai]
The dialog says **Google Sheets is connected**. Select **Test it**, then **Tell the AI** so it carries on.
</Step>
</Steps>

You can also start inside a project: in **Settings**, **Keys**, describe it in **What do you want to connect?** and select **Ask AI to connect**.

## What the table looks like [#what-the-table-looks-like]

Each tab you ask for becomes a table: the header row gives the column names, each row below is a record. Ask the AI to:

- **Name the table and columns** the way your team talks about them.
- **Keep it fresh.** The AI can build an <Term id="agent">agent</Term> that reloads the sheet on a schedule. See [What agents do](/docs/agents).
- **Put addresses on a map.** A sheet of addresses can be geocoded with [Google Maps Platform](/docs/connectors/google-maps) and joined by location.

Then query the table in the <AppLink to="data.sql" />, add column descriptions and data checks, and decide who sees it. See [Tables](/docs/data/tables).

## Test, pause and reconnect [#test-pause-and-reconnect]

A project's connections are listed in its **Settings**, under **Keys**, with their status.

<Screenshot src="/docs/_media/manage-connections-by-toggle-on-off-per-project.png" alt="A project's connections in Settings, Keys" />

| Status | What it means |
| --- | --- |
| **Waiting for you** | Drafted by the AI. Select **Connect** to finish it. |
| **Works** | Connected and usable by the project. |
| **Needs reconnecting** | The key or sign-in stopped working. Select **Reconnect**. |
| **Paused** | Nobody can use it until you select **Resume**. |

From the same row: **Test**, **Pause**, **Turn off here** (this project stops using it) or **Remove** (deletes the key, and every Studio using it stops reaching Google Sheets).

A connection belongs to the project it was made in. Owners and admins see all of them under **Your connections** on <AppLink to="connectors" />. It stays off for other projects until an admin switches it on under **Projects that may use** it.

## If the test fails [#if-the-test-fails]

**Test** reports one of these:

- It works: the project reached the service.
- The key was rejected: select **Reconnect** and enter a new one.
- The service cannot be reached: check that it is up and accepts outside connections, then test again.
- Internet is off: the project's internet is **Off**. Turn it on in its **Settings**. With **Only allowed**, the Studio reaches only its connections and the sites you add.
- It is not connected yet: select **Connect**.

Specific to Google:

- **Limited: permissions were not granted.** Some actions will fail. Select **Reconnect** and approve everything the job needs.
- **Was signed in as an account. Sign in again to keep using it.** A password change or an expired grant ended it. Select **Reconnect**.
- **Signed in. Picking files is not set up here yet, so the AI can only reach files it creates.** The file picker is not available here, so the AI cannot open your sheet. Download it and upload it with [Add data](/docs/data/add-data) instead.

## Use your own sign-in app [#use-your-own-sign-in-app]

If your organization only allows sign-ins through its own registered app, choose **Use your own app instead** in the connect dialog. Register an app with the provider, add the **Return address for your app** Klarety shows, then paste its **Client id** and **Client secret** and select **Save your app**. The secret is sealed and never shown again.

## Where your key goes [#where-your-key-goes]

The key or sign-in is encrypted with a managed key service the moment you select **Connect**, and not even the AI can read it. The Studio never holds the key. If the one site it is sent to is not the service's own address, Klarety warns you and asks you to type the site to confirm.

## Next steps [#next-steps]

- [Tables](/docs/data/tables)
- [Google Drive](/docs/connectors/google-drive)
- [How connectors work](/docs/connectors)