Connecting Google Sheets to Clarisights

Google Sheets is the lowest-friction connector in Clarisights. It's ideal for one-off datasets, target lists, manual KPIs, offline spend, or any small structured data your team already maintains in a spreadsheet — no API access or developer setup required.

At a glance

Connector type	Spreadsheet (read-only)
Authentication	Service account (Clarisights-managed) — you share the sheet with our service account email
Permissions needed	Viewer access on the sheet
Object support	One or more tabs in a Google Sheet
Refresh cadence	Set per pipeline
Limited rollout	No

Authentication options

Google Sheets uses a Clarisights-managed service account. There's nothing to configure on Google Cloud and no OAuth consent flow — you simply share your sheet with our service account email, the same way you'd share a sheet with a colleague.

• Your CSM or Clarisights support will provide the service account email address (it ends in @…iam.gserviceaccount.com).

• Viewer access is sufficient. Editor access is only required for special features your CSM will call out explicitly.

• Sharing remains valid as long as the service account stays a viewer on the sheet. Removing it stops the connector immediately.

Setting up the connection

Step 1 — Prepare the sheet

Open the Google Sheet you want to connect and confirm it's structured for ingestion:

• The first row of the tab is the header row. Subsequent rows are data.

• Data is contiguous — no fully blank rows in the middle of the dataset. A blank row is read as a blank record.

• If the tab contains computed columns using volatile formulas (NOW(), TODAY(), RAND()), copy them and use Paste special → Values only so the values stop changing on every read.

Step 2 — Share the sheet with the Clarisights service account

In Google Sheets, click Share in the top-right and add the Clarisights service account email as a Viewer. Uncheck "Notify people" if you'd like — the service account doesn't read email.

[TODO: Screenshot needed — Google Sheets share dialog with service account email added as Viewer]

⚠ Common error: "Permission denied" or "The caller does not have permission" → the sheet hasn't been shared with the service account, or the share was on a different sheet. Double-check the email and re-share. Allow ~1 minute for Google to propagate the permission.

Step 3 — Send connection details to Clarisights

Send the following to your CSM or to support so we can wire up the pipeline:

• The sheet URL (or sheet ID — the long token between /d/ and /edit in the URL).

• The tab name exactly as it appears in the bottom tab bar (case-sensitive).

• Optional: a cell range (e.g. A1:Z10000) if you want us to read only part of the tab.

⚠ Common error: "Sheet too large" or read failures on very large sheets → Google enforces a hard cap of 10 million cells per sheet. If you're at or near that limit, split the data across multiple sheets, or move the dataset to BigQuery or Snowflake and use those connectors instead.

Connection details exchange

You provide to Clarisights	Clarisights provides to you
Sheet URL or sheet ID	Service account email to share the sheet with
Tab name (exact, case-sensitive)	Confirmation once the first read succeeds
Optional: cell range to limit the read

What we read

• The first row of the tab is treated as the header row. Column names in row 1 become the field names available in Clarisights.

• Each subsequent row is one record. Cells are read as their displayed values.

• Multiple tabs within a single sheet are supported — each tab can be wired up as its own pipeline if you have several datasets in one workbook.

Connector specifics

• 10 million cell cap. This is Google's hard limit on a single spreadsheet. Sheets approaching this size become slow to read and may fail. Split the dataset across sheets, or use BigQuery/Snowflake for larger volumes.

• Volatile formulas recompute on every read. NOW(), TODAY(), RAND(), and similar will produce different values each time we read the sheet, which can cause unexpected diffs in your reports. Replace them with static values (Paste special → Values only) for any column you intend to ingest.

• Keep data contiguous. An empty row in the middle of the dataset is read as a blank record, not skipped. Trim trailing blank rows and avoid using blank rows as visual separators.

• Header row is row 1. If you rename a header upstream, that column needs to be re-mapped on the Clarisights side.

Limitations & known constraints

• 10 million cells per sheet (Google's limit). Larger datasets need a different connector.

• No nested data. Cells are flat values; arrays, JSON, and nested structures aren't supported.

• No images. Images embedded in cells (via =IMAGE() or paste) aren't ingested. URL columns rendering as image previews need to be configured on the Clarisights side.

• Read-only. Clarisights never writes back to your sheet.

Operating notes

• Refresh cadence is set per pipeline at setup time (e.g. hourly, daily). Each refresh reads the tab in full.

• Edits propagate on the next refresh. Adding, removing, or changing rows in the sheet shows up in Clarisights at the next scheduled read.

• Credential rotation: to rotate access, remove the service account from Share and re-share. There are no tokens or passwords on your side to manage.

• Renaming the tab or moving the file: if you rename the tab or move/replace the sheet, send the new tab name or URL to support so we can update the pipeline.

Need help?

When contacting support from the in-app messenger, please include:

• The sheet URL and tab name

• Confirmation that the Clarisights service account is still shared as a Viewer

• The exact error message or screenshot

• When the issue started