Skip to content

Add opt-in Connected Sheets support for BigQuery - #4

Closed
pragmabits wants to merge 1 commit into
mainfrom
feat/bigquery-connected-sheets
Closed

pragmabits wants to merge 1 commit into
mainfrom
feat/bigquery-connected-sheets

Conversation

@pragmabits

Copy link
Copy Markdown
Owner

Motivation

The Sheets API supports Connected Sheets, which links a spreadsheet to live BigQuery data. This adds three tools for it.

The scope problem, and why this is opt-in

Any data source request requires the bigquery.readonly OAuth scope. Adding it to SCOPES unconditionally would widen the scope set of every existing installation and force each user back through the consent flow, since a stored token no longer covers the requested scopes.

So the scope is only requested when ENABLE_BIGQUERY_TOOLS=1 (or --enable-bigquery) is set, and the three tools are not even registered otherwise. Verified:

Configuration Tools Scopes
default 20 2
ENABLE_BIGQUERY_TOOLS=1 23 3

Someone who does not want the feature sees no change at all.

Tools

  • add_bigquery_data_source — connect a table or raw SQL
  • refresh_data_source — re-run one or all data sources
  • get_data_source_data — read the resulting rows

Findings worth documenting regardless of this PR

Verified end to end against the real API:

  • It works on a personal gmail.com account. Google's own docs contradict themselves here — one page lists only Enterprise editions, another says personal accounts are supported.
  • DATA_SOURCE sheets are invisible to the values API. get_sheet_data fails on them with Unable to parse range. Reading requires grid data — this is why get_data_source_data exists rather than complicating get_sheet_data.
  • The addDataSource reply does not name the sheet it creates. It returns only dataSourceId, so the sheet has to be located by that id afterwards, otherwise the caller cannot reach the data.
  • Both service accounts and user OAuth work for addDataSource and refresh.

Regression this feature would have exposed

find_in_spreadsheet wrapped its whole per-sheet loop in a single try/except. Once a spreadsheet has a DATA_SOURCE sheet, the values call raises and the search returns an error, discarding matches already found in the other sheets. Reproduced against the real API, then fixed by skipping non-grid sheets. get_multiple_spreadsheet_summary was checked too and already degrades correctly.

Tests

Unit tests with fakes for configuration parsing, the registration gate, request construction and the missing-scope hint. The live suite gained a Connected Sheets case, skipped unless GOOGLE_TEST_BIGQUERY_PROJECT is set; both workflows pass the variables through, so enabling live coverage is a matter of creating two secrets.

The live bootstrap also learned to accept an already-authorized OAuth token, not just a service account — the README treats OAuth as a first-class auth method, but the live suite could not run with it. It never starts the interactive flow: a missing token skips.

Suite green on Python 3.10, 3.12 and 3.13.

Expose BigQuery data sources through add_bigquery_data_source,
refresh_data_source and get_data_source_data, all gated behind
ENABLE_BIGQUERY_TOOLS so the bigquery.readonly scope is only requested when the
feature is asked for and already-authorized tokens keep working. Data source
sheets are not addressable in A1 notation, which is why get_data_source_data
reads them through grid data, and find_in_spreadsheet now skips non-grid sheets
instead of failing the entire search when one is present. The live suite accepts
an authorized OAuth token in addition to a service account, and covers the new
tools when GOOGLE_TEST_BIGQUERY_PROJECT is configured.
@pragmabits pragmabits closed this Sep 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant