Learn BigQuery emulator features

BigQuery emulator feature reference

Use this page to decide whether a BigQuery workflow is appropriate for local validation. It describes local behavior, not production BigQuery parity.

Connection and persistence

Surface	Value	Boundary
REST	`http://localhost:24087`	Primary local REST surface.
Storage API profile	`localhost:24088`	Client- and feature-specific; not blanket gRPC parity.
SDK environment	`BIGQUERY_EMULATOR_HOST=http://localhost:24087`	Use an SDK path that supports the emulator endpoint explicitly.
Persistence	DuckDB files under `/var/lib/localcloud/bigquery-data`	Retention depends on the mounted LocalCloud volume; assembled dependency identity remains release-unverified.

Evidence states

State	Meaning on this page
Release-unverified	Behavior exists in source or dependency tests but has not been qualified in an identified assembled LocalCloud image.
Partial	A bounded compatibility path exists with material semantic, security, or client-profile limits.
Unsupported	Do not expect this behavior locally.

Do not derive a coverage percentage, function total, test total, or supported-language matrix from these states.

Current operation contract

Operation area	State	Qualification boundary
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.

Feature-specific interpretation

SQL and grouping

Common query, join, CTE, window, DML, and metadata workflows have dependency evidence. ROLLUP, CUBE, GROUPING SETS, and TABLESAMPLE also have newer upstream execution evidence, but their semantics and the assembled LocalCloud release are not qualified. Do not present them as production-equivalent SQL coverage.

DuckDB coercion, integer division, division-by-zero, geography, and error behavior can differ from BigQuery. A query accepted locally may still fail or return different results in production.

Scripting and procedures

The dependency has a local procedural interpreter for bounded variables, control flow, dynamic SQL, transactions, and procedure paths. Treat this as partial local interpretation, not complete BigQuery scripting or session parity. Authorization, complete system-variable behavior, every parameter mode, and production session semantics require real BigQuery validation.

Materialized views

Materialized views are emulated with physical local tables and explicit refresh behavior. This is useful for application workflow tests, but it does not reproduce BigQuery’s automatic or incremental refresh, optimizer integration, staleness policy, or distributed maintenance behavior.

External data and load/export

External tables are source- and format-specific. Local CSV, JSON, Parquet, and configured local Cloud Storage paths can have dependency evidence; BigLake, object tables, cross-cloud authentication, production sharding, full autodetect behavior, and all schema-evolution options do not follow from that evidence.

Storage APIs

Read and write profiles exist for selected AVRO, Arrow, stream, append, offset, and commit workflows. Client behavior is profile-specific. Do not claim universal SDK or connector compatibility without an assembled client matrix.

`INFORMATION_SCHEMA`

The dependency contains a mixture of:

populated, tested metadata views;
schema-compatible views that return empty local rows;
views with unknown qualification; and
unsupported production-control-plane views.

There is no durable fixed view count. Empty compatibility rows are not production metadata parity.

Types and functions

BIGNUMERIC: local precision-preserving helper/text paths do not establish complete native 76-digit semantics.
AEAD: a bounded local AES-GCM subset does not establish KMS, keyset, deterministic encryption, rotation, or wrapping parity.
NET: document only individually tested functions; do not infer the full namespace.
Search and vector: local matching and brute-force nearest-neighbor behavior do not provide production indexes, analyzers, ranking, planning, or acceleration.
GEOGRAPHY: local approximations are not BigQuery’s complete spherical semantics.

Unsupported production systems

The local emulator does not reproduce BigQuery ML lifecycle, distributed slots and reservations, BI Engine, billing, quota enforcement, production IAM, audit logging, regional restrictions, managed disaster recovery, scheduled queries, transfer orchestration, or production performance.

Validation rule

Before publishing a stronger claim, record all of the following together:

dependency source revision;
dependency image digest and platform digest;
assembled LocalCloud image digest;
client/profile qualification result;
durable evidence path; and
release association.

Until then, keep the feature state release-unverified and validate release behavior against real BigQuery.

Was this page helpful?