Blog 2026-10-14

Read-only doesn't mean cheap: cap BigQuery query costs

A read-only query can still scan a large table. BigQuery's maximum-bytes-billed setting provides a concrete guardrail for ordinary on-demand query jobs: set the limit on the job, rather than assuming that a small result is cheap.

The Frontier Research Club's talk on agent-first data systems, uploaded October 13, describes agents issuing overlapping exploratory queries. We reviewed its description and chapters, not a loaded transcript. Its benchmark results were not reproduced here.

One answer, potentially many bytes

Consider a fictional question: “What was October revenue from completed orders?” A SUM returns one value, but producing it requires reading the relevant source data. Define the accounting measure, currency and UTC window first. A date predicate helps prune a compatible partitioned table; it is not a guarantee that an arbitrary table will be scanned cheaply.

SELECT SUM(amount_cents) AS october_revenue_cents
FROM `YOUR_PROJECT.YOUR_DATASET.orders`
WHERE status = 'completed'
  AND completed_at >= TIMESTAMP('2026-10-01 00:00:00+00')
  AND completed_at < TIMESTAMP('2026-11-01 00:00:00+00');

Replace the table identifier with an existing native BigQuery table. The example assumes completed_at is a TIMESTAMP and amount_cents is an INT64 in one currency. It does not prepare or ingest the data.

Estimate first; enforce the cap on execution

Save the SQL as query.sql. With your own authenticated Google Cloud CLI and billing project, inspect the dry-run estimate:

bq --project_id=YOUR_PROJECT --location=US query \
  --use_legacy_sql=false --dry_run < query.sql

Use the dataset's actual location. A dry run validates and estimates the query without executing its data scan. When you are ready to run it, keep an explicit one-GiB maximum on the execution job:

bq --project_id=YOUR_PROJECT --location=US query \
  --use_legacy_sql=false --use_cache=false \
  --maximum_bytes_billed=1073741824 < query.sql

The second command can incur query charges and is provided for review, not run here. One GiB is 1,073,741,824 bytes. Google's documentation says that an ordinary on-demand query whose estimated bytes exceed the configured maximum fails without a query charge. Fix an overly broad query or intentionally review the cap; do not have an agent automatically increase it or retry unchanged.

Illustrative—not measured—outcomes: a three-GiB estimate exceeds a one-GiB cap; a 128-MiB estimate is below it. An actual job can still fail for permissions, syntax, missing data or other reasons. Estimates on clustered tables can be conservative. Dry-run zero estimates for row-level-security or some external/federated sources are not proof that execution is free.

Where Bufflehead fits

Bufflehead v0.30.0 already forwards MaxBytesBilled to BigQuery query jobs. Its connection model defaults to 20 GiB per query and supports a positive max_bytes_billed value for a tighter connection-specific limit. Its read-only SQL gate and result pagination are separate controls. We verified the tagged source and current main; we did not exercise this configuration against a live BigQuery account or test the UI in this example.

A one-GiB limit on every job is not a one-GiB limit on an entire agent task. Multiple queries and retries can accumulate usage. Client attempt/concurrency budgets and project/user quotas need separate consideration. A bytes limit is not a universal dollar cap for capacity-based reservations, storage, transfers or other services.

Google's cost-control guidance documents dry runs and maximum bytes billed. This example provides a reproducible procedure, not measured BigQuery outcomes or an AI benchmark. No cloud jobs or billable operations were performed while preparing it.

Try it on your own data.

Native binary, no Docker, no cloud egress. Free for local files and direct database connections — request a demo for the AWS SSM path.

Download free Request a demo