Google Sheets
Connect Google Sheets with Google consent, choose the spreadsheets Xentropy may read, and read bounded A1 ranges into datasets.
A Google Sheets connection reads ranges of the spreadsheets you choose.
Consent happens on Google's consent screen in your browser, and Xentropy asks
only for the drive.file scope: it can open the files you pick and nothing
else in your Google Drive.
Set up the connection
A connection holds up to 100 chosen files. A dataset can only read a chosen
spreadsheet. Reads of any other file fail with PERMISSION_DENIED. If a
spreadsheet is removed from the connection during a read, that read fails too.
Agents cannot give consent. An agent with connections:manage can start the
flow, but the owner finishes it in a browser.
Ranges
A dataset reads one explicit A1 rectangle, such as Sheet1!A1:F200. Quote tab
names that contain spaces or symbols: 'Q3 targets'!A1:D50.
| Limit | Value |
|---|---|
| Cells per range | 10,000 cells |
| Columns per range | 100 columns |
| Rows per range | 1,000 |
| Response size | 8 MB |
| Request timeout | 20 s |
For a larger sheet, save several datasets with separate bounded ranges.
Header row
The first row of the range is the header row. Every header cell must be a
unique, non-empty text value, otherwise the read fails with
VALIDATION_FAILED. Column types come from the values in the range. Once a
dataset is saved, its fields are fixed: if a selected column is removed or
renamed in the sheet, refreshes fail with SCHEMA_CHANGED.
Refreshes and connection health
Every refresh reads the range again. A successful test or read marks the connection healthy. When Google refuses a read, the connection's health records why: a missing permission, or a temporary error such as a rate limit.
If you revoke Xentropy's access in your Google account, or Google expires the
grant, the connection needs a reconnect. The read that finds out fails with
INVALID_GRANT. Later reads fail with RECONNECT_REQUIRED until you
reconnect, and Xentropy does not call Google in the meantime.
Rate limits
Google limits read requests per user and per project. When a limit is reached,
whether Google answers HTTP 429 or a quota 403 such as rateLimitExceeded, the
read fails with PROVIDER_UNAVAILABLE and HTTP status 429. The error is
retryable. When Google says how long to wait, details.retryAt holds that
time. A quota limit does not mark the connection as missing permission.
Errors
| Code | Cause | What to do |
|---|---|---|
PROVIDER_RANGE_INVALID | Google could not read the range: an unknown tab, or a range outside the sheet | Check the tab name and the A1 rectangle |
LIMIT_EXCEEDED | The range is larger than 10,000 cells or 100 columns, or the response exceeds 8 MB | Read smaller ranges |
VALIDATION_FAILED | The header row is missing, empty or has duplicate names | Fix the header row |
SCHEMA_CHANGED | A selected column was removed from the sheet | Restore the column, or save a new dataset |
PROVIDER_FILE_NOT_FOUND | The spreadsheet was deleted, or is no longer shared with your account | Restore the file, or choose another one |
MISSING_PROVIDER_SCOPE | Google denied access to the file, for example because of an account policy | Check the file's sharing and your organization's policy, then reconnect |
INVALID_GRANT, then RECONNECT_REQUIRED | Access was revoked or the grant expired | Reconnect the connection |
PROVIDER_UNAVAILABLE (429) | Google's rate limit or quota was reached | Retry after details.retryAt, or later. Do not retry in a loop |
PROVIDER_UNAVAILABLE (503) | Google could not be reached or answered with an error | Retry the read later |
PERMISSION_DENIED | The spreadsheet is not chosen on this connection | Choose it with Choose spreadsheets |