Endpoint: BIGQUERY_EMULATOR_HOST=http://localhost:24087.
BigQuery agent testing
BigQuery local testing for AI agents
Use LocalCloud when an agent needs to create, exercise, and reset BigQuery resources without touching a real Google Cloud project. The same SDK shape points at localhost through BIGQUERY_EMULATOR_HOST=http://localhost:24087.
Endpoints: HTTP/REST :24087 · gRPC :24088.
Evidence state: partial; Local development coverage is partial. Known limits: DuckDB type coercion is permissive where BigQuery is strict — queries accepted locally may error in production., Division by zero returns Inf/NaN instead of error; integer division returns int instead of FLOAT64., GROUP BY ROLLUP/CUBE/GROUPING SETS not supported., SEMI/ANTI JOIN syntax not supported (rely on EXISTS/NOT EXISTS transpile)., BQML (CREATE MODEL, ML.PREDICT, ML.EVALUATE, etc.) returns clear error., AEAD encryption functions and KLL quantile functions not implemented., GEOGRAPHY functions use haversine approximation, not true WGS84 geodesic., BIGNUMERIC truncated to DECIMAL(38,9); FARM_FINGERPRINT requires pyfarmhash for correct values., Time travel (FOR SYSTEM_TIME AS OF), continuous queries, graph queries, search/vector indexes not supported., External object tables (OBJ.* functions) not supported..
Registry default: on; assembled default: on (verified); minimum tier: community.
Persistence: service-data (release-unverified). Survives restart with the LocalCloud volume
Route the SDK before writing code
Start LocalCloud, export BIGQUERY_EMULATOR_HOST=http://localhost:24087, and make the agent perform one BigQuery operation before changing application logic. That catches accidental production routing early.
Prefer one representative behavior over broad smoke tests
A useful agent check creates local BigQuery state, reads it back with the project SDK, and records which feature was covered. It should not require a GCP account, service-account key, or billing project.
Use only documented setup paths
Create deterministic state through a contract-documented seed registrar or through an operation listed on this page. Do not assume every service supports seed data, reset, or persistent state.
Copy-ready setup
Commands and prompts
Use these snippets as starting points, then keep the checks scoped to localhost until you intentionally validate against real Google Cloud.
Environment
eval "$(localcloud env)"
# Verify that the generated environment includes BIGQUERY_EMULATOR_HOST; do not replace a CLI-remapped value with a hard-coded port. Compatibility
Local check versus release validation
| Area | LocalCloud local check | Real GCP still needed for |
|---|---|---|
| SDK routing | BIGQUERY_EMULATOR_HOST=http://localhost:24087 points clients at localhost. | Production endpoint, auth, IAM, quota, and regional behavior. |
| Supported features | datasets.create/list/delete (verified); tables.create/list/delete (verified); SELECT, JOIN, window functions, CTEs, PIVOT/UNPIVOT, MERGE (partial) — DuckDB-backed via SQLGlot transpiler. ~96% BigQuery SQL coverage, 175+ functions. 958 tests passing. Key gaps: GROUP BY ROLLUP/CUBE/GROUPING SETS, SEMI/ANTI JOIN, BQML (clear error), AEAD encryption, KLL quantiles, graph queries, continuous queries. ⚠ Type coercion risk: DuckDB is permissive where BigQuery is strict — queries that work locally may error in production. Division by zero returns Inf instead of error. GEOGRAPHY: 12 ST_* functions with haversine approximation (not true geodesic). ; DECLARE, SET, IF/WHILE/LOOP, BEGIN/EXCEPTION, CALL, EXECUTE IMMEDIATE (partial) — Full scripting interpreter with variable scoping, BREAK/CONTINUE, RAISE, transactions.; CREATE MATERIALIZED VIEW, auto-refresh (partial) — Supported in emulator with PARTITION BY, CLUSTER BY, OPTIONS.; query Parquet/CSV/JSON files (local + GCS) (partial) — CREATE EXTERNAL TABLE with format/uris options. Object tables not supported.; gRPC Storage Read/Write API (AVRO + Arrow) (partial) — gRPC endpoint on port 24088. ReadRows with streaming support.; INFORMATION_SCHEMA views (partial) — 11 views: COLUMNS, TABLES, SCHEMATA, PARTITIONS, VIEWS, ROUTINES, TABLE_OPTIONS, TABLE_STORAGE, JOBS_BY_*, COLUMN_FIELD_PATHS. | DuckDB type coercion is permissive where BigQuery is strict — queries accepted locally may error in production.; Division by zero returns Inf/NaN instead of error; integer division returns int instead of FLOAT64.; GROUP BY ROLLUP/CUBE/GROUPING SETS not supported.; SEMI/ANTI JOIN syntax not supported (rely on EXISTS/NOT EXISTS transpile).; BQML (CREATE MODEL, ML.PREDICT, ML.EVALUATE, etc.) returns clear error.; AEAD encryption functions and KLL quantile functions not implemented.; GEOGRAPHY functions use haversine approximation, not true WGS84 geodesic.; BIGNUMERIC truncated to DECIMAL(38,9); FARM_FINGERPRINT requires pyfarmhash for correct values.; Time travel (FOR SYSTEM_TIME AS OF), continuous queries, graph queries, search/vector indexes not supported.; External object tables (OBJ.* functions) not supported. |
| Agent safety | No default cloud account, credentials, or billing project required. | Final release validation in the target GCP project. |
Use the sandbox deliberately
- Permitted workflows use local endpoint values and should stop rather than fall back to real Google Cloud or real credentials. The Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud for non-production internal development, testing, CI, evaluation, and pilots.
- LocalCloud emulates bounded local development workflows. Validate application behavior against real Google Cloud before production deployment.
- Before production deployment, unset LocalCloud emulator environment variables and validate behavior against real Google Cloud.
- Local development coverage is partial. Known limits: DuckDB type coercion is permissive where BigQuery is strict — queries accepted locally may error in production., Division by zero returns Inf/NaN instead of error; integer division returns int instead of FLOAT64., GROUP BY ROLLUP/CUBE/GROUPING SETS not supported., SEMI/ANTI JOIN syntax not supported (rely on EXISTS/NOT EXISTS transpile)., BQML (CREATE MODEL, ML.PREDICT, ML.EVALUATE, etc.) returns clear error., AEAD encryption functions and KLL quantile functions not implemented., GEOGRAPHY functions use haversine approximation, not true WGS84 geodesic., BIGNUMERIC truncated to DECIMAL(38,9); FARM_FINGERPRINT requires pyfarmhash for correct values., Time travel (FOR SYSTEM_TIME AS OF), continuous queries, graph queries, search/vector indexes not supported., External object tables (OBJ.* functions) not supported..
Keep the agent on the supported path
- BigQuery service page — Service-specific supported and unsupported capability list.
- Compatibility matrix — Check current support boundaries before relying on a local-only test.
- Service catalog — Review every LocalCloud service, endpoint, and limitation.
- SDK examples — Use standard Google Cloud SDKs pointed at localhost.
- Seed data — Load deterministic fixtures for repeatable agent and CI runs.
Claims are tied to current sources
- LocalCloud service metadata — Reviewed 2026-08-26; implementation custom-emulator.
- LocalCloud agentic facts reviewed 2026-08-26.