BigQuery emulator

BigQuery is a SQL analytics warehouse for exploring and transforming datasets. It is designed for reporting, aggregations, and analytical pipelines rather than individual application record updates.

When to use BigQuery

Typical uses

Use when you need to scan datasets, join analytical tables, and calculate aggregates with SQL. Validate reporting queries and transformation outputs against small local fixtures.

Examples

Analytics and business reporting
SQL transformations and model experiments

Analytics

Hello world

Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1. Install and start · shell

curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and BIGQUERY_EMULATOR_HOST
eval "$(localcloud env)"

Python

Run a deterministic GoogleSQL query

2. Install SDK · shell

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigquery

3. Save as hello.py

import os
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

client = bigquery.Client(
    project=os.environ['GOOGLE_CLOUD_PROJECT'],
    credentials=AnonymousCredentials(),
    client_options={"api_endpoint": os.environ["BIGQUERY_EMULATOR_HOST"]},
)
rows = list(client.query("SELECT 'Hello from LocalCloud!' AS message").result(timeout=30))
assert rows[0].message == 'Hello from LocalCloud!'
print(rows[0].message)
client.close()

4. Runpython hello.py

Full example guide

Documented workflows

Datasets, tables, clones, and time travel
Row access policies, top-level policy tags, and masking
Joins, window functions, CTEs, PIVOT/UNPIVOT, and MERGE
Procedural scripts, stored procedures, and dynamic SQL
Jobs, dry runs, scheduled queries, and selected ML models
Materialized views and INFORMATION_SCHEMA
Emulated GCS: CSV, JSONL, Parquet, Avro, ORC; EXTERNAL_QUERY
gRPC Storage Read/Write with Avro and Arrow

Service boundaries

Function/input-specific SQL limits; check the feature matrix
No ingestion-time partitioning or nested policy tags
No native Bigtable, Sheets, HTTP, or local-file external sources
Model, ML transform, and geography input limits
Managed reservations, production IAM, and fleet scale are cloud-only

Try it in your project

Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples

Agent testing

Use BigQuery with an AI agent

Before the agent changes application logic, have it create local BigQuery state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

BigQuery local test

Use LocalCloud to test BigQuery code locally. Read https://local.cloud/ai/agents.md and the BigQuery docs, set BIGQUERY_EMULATOR_HOST for localhost, create a local dataset/table, insert sample rows, run a representative query, and call out any unsupported SQL features instead of using real BigQuery.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.