Klairr reads a Google Sheet using a service account that the customer shares the sheet with. No OAuth flow is required for the design-partner phase.
Prerequisites
- A Google Cloud project (a free personal one is fine)
- The sheet you want to query
Step 1: Create a service account
- In the Google Cloud Console, go to IAM & Admin → Service Accounts
- Click Create Service Account, name it “klairr-reader”
- Skip the “grant role” step — Klairr only needs sheet-level access
- Open the new account → Keys → Add Key → Create new key → JSON
- Save the JSON file
Step 2: Share the sheet with the service account
In Google Sheets, open the sheet you want to query. Click Share and paste the service account email (it ends in @…iam.gserviceaccount.com). Set the role to Viewer. Click Send.
The Viewer role is read-only by Google’s design — there is no Klairr-level configuration that can elevate it. This is the strongest guarantee Klairr can offer for a hosted spreadsheet.
Step 3: Add the connector
| Field | Example |
|---|---|
| Service account JSON | upload the file from Step 1 |
| Spreadsheet ID | 1AbCdEf... |
| Sheet (tab) name | Sheet1 (or leave blank for the first sheet) |
The spreadsheet ID is in the sheet’s URL: docs.google.com/spreadsheets/d/<ID>/edit.
What Klairr queries
- Schema is inferred from the header row plus type detection from the first 100 data rows. Mixed-type columns are flagged in the description.
- Question answering uses the same JSON DSL as the Excel/CSV connector: filters, groupBy, aggregate, sortBy, limit. Aggregations execute client-side.
- The OAuth scope used is
https://www.googleapis.com/auth/spreadsheets.readonly— the narrowest read scope offered by the Sheets API.
Notes
- Sheet contents are captured at refresh time. Live edits made between refreshes are not visible until you refresh.
- For very large sheets (100k+ rows) move the data into Postgres or a warehouse — Sheets is best for small operational data.
- OAuth-based personal Sheets connection is on the roadmap.