BigQuery.

Connect Orchid to a BigQuery project. Auth via service-account JSON key, OAuth (sign in with your Google account), or Application Default Credentials.

Requirements

• Project ID — from the GCP console.
• Auth — service-account JSON key, OAuth via Google, or ADC.
• The auth principal must have at least roles/bigquery.dataViewer on the datasets you want to query and roles/bigquery.jobUser on the project (to run jobs).

Connect with a service account

1. In GCP, create a service account with BigQuery Data Viewer + BigQuery Job User.
2. Generate a JSON key, download it.
3. In Orchid: Integrations → + Add connection → BigQuery.
4. Paste the project ID, upload the JSON key.
5. Click Test connection → save.

Connect with OAuth

Pick Sign in with Google in the connector. A browser tab opens for the consent flow. The granted token is stored in your OS keychain and refreshed automatically. Tokens are scoped to BigQuery read + job submission only.

Connect with Application Default Credentials (ADC)

If you already authenticate with gcloud on your machine, Orchid can reuse those credentials. No JSON keys, no separate OAuth — same identity you use everywhere else.

# One-time, in your shell
$ gcloud auth application-default login
Your browser has been opened to visit:
  https://accounts.google.com/o/oauth2/auth?...

Credentials saved to file:
  ~/.config/gcloud/application_default_credentials.json
      

In Orchid, pick Application Default Credentials, set the project ID, save. ADC is also the right choice on GCE/Cloud Workstations, where the metadata server provides credentials automatically.

Optional settings

Default dataset

BigQuery requires fully-qualified table names in most contexts (project.dataset.table). Setting a default dataset in the connection settings lets you write SELECT * FROM orders instead of SELECT * FROM myproject.shop.orders.

Job location

Set the BigQuery job location to match your data's region (e.g. US, EU, us-central1). Cross-region queries fail with an explicit error.

Partition filter requirement

Many BigQuery tables are partitioned by date and configured with require_partition_filter = true. Queries that don't include a partition filter fail immediately:

-- Fails: missing partition filter
SELECT * FROM `proj.analytics.events` LIMIT 100;
-- ERROR: Cannot query over table 'analytics.events' without a filter
-- over column 'event_date' that can be used for partition elimination.
      

The fix is to always include a partition filter, ideally pinned to a recent window:

SELECT *
FROM `proj.analytics.events`
WHERE event_date BETWEEN '2026-05-01' AND '2026-05-14'
LIMIT 100;
      

Orchid shows the bytes-scanned estimate before you run a query (hover the query badge in the cell footer). Partition filters drop that number by orders of magnitude.

Billing controls

BigQuery charges per byte scanned (on-demand pricing) or per slot-hour (flat-rate). For on-demand projects, set a per-user quota in GCP to cap surprises.

# Set a 1 TiB / day quota for the bigquery JobUser identity
# (run by your project's billing admin)
$ gcloud alpha services quota update \
    --service=bigquery.googleapis.com \
    --consumer=projects/your-project \
    --metric=bigquery.googleapis.com/quota/query/usage \
    --value=1099511627776 \
    --unit=1/d/{project}/{user}
      

Common gotchas

• "Permission denied: BigQuery JobUser" — the principal needs both Data Viewer (on the dataset) and Job User (on the project). Missing either won't work.
• "Cannot query over table X without a filter over column Y" — partition filter required. See above.
• Region mismatch — a US dataset cannot join an EU dataset in the same query. Use a single region per query.
• Slow first dataset list — listing all datasets in a project is paginated; large projects take a few seconds on initial load.
• Standard vs Legacy SQL — Orchid uses Standard SQL by default. If a query needs Legacy, prefix it with #legacySQL on the first line.
• ADC says "could not find default credentials" — you haven't run gcloud auth application-default login, or the credentials JSON has been deleted. Re-run the login command.

Example queries

-- List datasets in the current project
SELECT schema_name
FROM INFORMATION_SCHEMA.SCHEMATA
ORDER BY schema_name;
      

-- Daily counts with partition filter
SELECT DATE(event_timestamp) AS day, COUNT(*) AS events
FROM `myproject.analytics.events`
WHERE DATE(event_timestamp) BETWEEN '2026-05-01' AND '2026-05-14'
GROUP BY 1
ORDER BY 1;
      

Where to go next

For more on writing SQL cells, see SQL cells.