BigQuery

BigQuery read-only · Live

Ask your warehouse without writing SQL.

Connect BigQuery via Google OAuth (or a service-account JSON) and let the agent discover datasets, list tables, and run read-only Standard SQL queries capped at 100 rows.

Connect BigQueryHow it worksLive
Auth
Google OAuth or service account
Access
Read-only · 100 rows per query
Plan
Every plan
Freshness
Live — every query hits BigQuery
Available on
Every plan

Examples

Questions teams actually ask.

The tools it pulls from are shown inline — every answer in Lumen cites the underlying records it read.

Analytics

Weekly revenue for the last 8 weeks, broken down by product category.

pullsdatasetstablesquery
Growth

How many new users signed up yesterday by acquisition channel, and how does that compare to last week's average?

pullsquery
Finance

What's the MRR trend over the last 6 months from `billing.subscriptions`?

pullstablesquery
Product

Show me retention cohorts for users who signed up in Q1 — day 7, 30, 60, 90.

pullsquery
Discovery

List every dataset in the project, and tell me which tables look like an orders table.

pullsdatasetstables

Preview

See what the answer looks like.

Toggle the tools Lumen is allowed to use. The plan, answer, and cited sources update to match.

Tools
Read-only
You

What's this week's revenue by product category vs last week?

Plan
  1. bigquery.listDatasets — find the dataset that looks like sales
  2. bigquery.listTables — identify the orders and line_items tables
  3. bigquery.query — SELECT category, SUM(amount) FROM `analytics.sales_line_items` WHERE week = CURRENT_DATE — ...
  4. bigquery.query — same shape for the previous week, then diff
Answer

This week: $184,210 across 4 categories. Apparel +12%, Accessories +4%, Footwear −7%, Home flat. Full query and row counts inlined.

Sources
  • [1]bigquery.listDatasets — 14 datasets scanned, `analytics` selected
  • [2]bigquery.listTables — 27 tables, `sales_line_items` picked
  • [3]bigquery.query — 4 rows returned, execution 1.8s

Scope

What Lumen sees. What it can change.

Read is on by default. Every write is a separate toggle, capped per user, and logged.

Read

What Lumen reads

Lumen runs queries through the BigQuery Jobs API using the OAuth grant (or service-account credentials) you supplied.

  • List datasets

    Discovers what's queryable; first call the agent usually makes

  • List tables in a dataset

    Includes table type (TABLE, VIEW, MATERIALIZED_VIEW, EXTERNAL)

  • Run Standard SQL SELECT queries

    Capped at 100 rows per query; fully-qualified table names required

Write · opt-in

What Lumen can write

BigQuery access is read-only. Lumen never requests DML scopes, and every query is constrained to SELECT by the role you grant at install.

    Every query is logged with user, the SQL text, the `explanation` the agent wrote, dataset scanned, and row count returned. Exportable as CSV.

    Install

    Connect in under a minute.

    No keys, no call, no app marketplace fine print.

    1. Connect
      01

      Sign in with Google

      In Settings → Integrations → BigQuery, click Connect with Google. Approve BigQuery read-only access on Google's consent screen. Optionally set a default GCP project ID and location (e.g. `US`, `EU`).

    2. Or paste a service account
      02

      Use a service account JSON

      Prefer a service account? Create one in GCP IAM with the BigQuery Data Viewer and BigQuery Job User roles, download the JSON key, and paste it into Lumen. Credentials are stored encrypted.

    3. Ask
      03

      Try a discovery question

      Start with "What datasets are in this project?" — the agent will call `listDatasets`, then `listTables` on whatever looks promising, and build the first query from there.

    Questions

    Frequently asked.

    Why the 100-row cap?
    BigQuery is cheap to scan but expensive to return to a chat. 100 rows keeps the answer in the conversation rather than a download. If you need more, the agent will narrow the query, aggregate, or summarise.
    Does Lumen write to BigQuery?
    No. The OAuth scope is read-only, and the service-account path expects Data Viewer + Job User roles. DML and DDL are not supported.
    How does Lumen pick the right dataset?
    The agent calls `listDatasets` first, then `listTables` on a dataset that matches what you're asking about. You can give it a hint in your question ("use the `analytics` dataset") to skip the discovery step.
    What about dry-run cost previews?
    Not yet. The agent reports execution time and scanned bytes from the BigQuery job summary — cost previews before execution are on the roadmap.
    Can I scope the agent to specific datasets?
    Best-practice is to grant your service account access only to the datasets you want Lumen to see. IAM is the source of truth — Lumen only sees what the credentials allow.
    Does Lumen cache results?
    Results live inside the conversation they ran in so the agent can cite rows back to you. They're deleted with the conversation. Nothing is persisted beyond that.
    What about views and materialised views?
    Both are listed alongside tables and are queryable the same way. Authorized views work as long as the credentials have access.

    Pairs with

    Better together.

    Connect BigQuery. Ask a real question.

    Google OAuth or service account. Read-only. 100 rows per query.

    Connect BigQueryBack to all integrations