Services BigQuery emulator features

BigQuery emulator feature reference

The current LocalCloud source packages a native GoogleSQL Analyzer and DuckDB query engine. Supervisord manages the BigQuery process inside the LocalCloud Docker container. Running LocalCloud requires Docker; the default BigQuery process does not need a Docker-socket mount. An optional custom BigQuery image uses a companion container and requires Docker access.

Connection and endpoints

Surface	Canonical endpoint	Boundary
REST API	`http://localhost:5388`	BigQuery dataset, table, job, and query routes.
Storage API	`localhost:5389`	Separate gRPC listener with TLS; configure the Storage client and trust the LocalCloud CA.
Environment export	`BIGQUERY_EMULATOR_HOST=http://localhost:5388`	Use the actual value from `localcloud env`; some SDKs need explicit client options.
Gateway proxy	`http://localhost:5380/bigquery/v2/`	Gateway authentication and routing differ from direct listeners.
Persistence	`/var/lib/localcloud/bigquery-data`	DuckDB and metadata beneath the mounted LocalCloud data volume.

The CLI may remap host ports. The Python SDK example passes the generated REST endpoint explicitly and uses anonymous credentials. A REST client configuration does not configure the Storage API client.

Current operation contract

Operation area	Status	Boundary
datasets.create/list/update/delete	Supported
tables.create/list/update/delete	Supported	Table creation, metadata updates, deletion, table clones with time travel (FOR SYSTEM_TIME AS OF), table copies, temp tables, wildcard tables, row-level access policies, policy tags, and data masking.
jobs.query/cancel/delete/serviceAccount/projects	Supported	Job execution, cancellation, deletion, serviceAccount lookup, dry runs with byte estimates, project listing, scheduled queries, reservation routing, and BigQuery ML model training/evaluation lifecycle.
SELECT, JOIN, window functions, CTEs, PIVOT/UNPIVOT, MERGE	Supported	Query coverage varies by capability and input. Review the dependency coverage matrix, and test semantics and errors with your application queries.
DECLARE, SET, IF/WHILE/LOOP/REPEAT/FOR, BEGIN/EXCEPTION, CALL, EXECUTE IMMEDIATE	Supported	Full procedural language support with variable declaration, flow-of-control, exception handling, dynamic SQL (EXECUTE IMMEDIATE with USING/INTO), and stored procedures (CREATE PROCEDURE / CALL).
CREATE MATERIALIZED VIEW, auto-refresh	Supported	CREATE MATERIALIZED VIEW with PARTITION BY, CLUSTER BY, OPTIONS, always-fresh reads, and automated refresh procedure.
query Parquet/CSV/JSON/Avro/ORC files (local + GCS)	Supported	External tables and load jobs over emulated gs:// (CSV with BigQuery header autodetect, JSONL, Parquet, Avro, ORC with schema autodetect and hive partitions). EXTERNAL_QUERY over SQLite, PostgreSQL, and MySQL.
gRPC Storage Read/Write API (AVRO + Arrow)	Supported	gRPC endpoint on port 5389. ReadRows with streaming support; AppendRows Storage Write API. Spark Storage Read connector verified 11/11 cases across client profiles.
INFORMATION_SCHEMA views	Supported	Full catalog coverage including COLUMNS, TABLES, SCHEMATA, PARTITIONS, VIEWS, ROUTINES, ROUTINE_OPTIONS, PARAMETERS, COLUMN_FIELD_PATHS, TABLE_OPTIONS, TABLE_STORAGE, OBJECT_PRIVILEGES, MATERIALIZED_VIEWS, JOBS_BY_, SESSIONS_BY_, RESERVATIONS, and search/vector index views.

Validate a data pipeline locally

Follow the deterministic query example to configure the REST client, then create an owned dataset and tables with small, known fixtures.
Run the application’s query, script, or stored procedure. Assert exact rows, column types, null handling, and expected errors.
For external tables, upload a CSV, JSONL, Parquet, Avro, or ORC fixture to local Cloud Storage and query it. Check the returned data instead of relying on stored connection metadata.
If the pipeline uses Storage Read/Write, configure its separate gRPC endpoint and CA trust, then verify Avro or Arrow records through that client.
Delete the owned dataset and Storage fixtures after the test. Keep application cases in the suite so future image updates run the same assertions.

The BigQuery documented workflows cover query, job, security, BQML, Vector Search, and metadata scenarios. Check exact SQL, model, geography, and connector inputs against the matrix below.

To weigh LocalCloud against standalone emulators and real BigQuery, see BigQuery emulator alternatives.

Coverage matrix

The BigQuery emulator keeps a versioned coverage matrix. It includes canonical and derived records, so its total is a count of records, not a count of distinct canonical GoogleSQL capabilities or executed tests.

Dimension	Implemented	Implemented with limits	Unsupported	Unknown	Total records
Development	1075	12	69	381	1537
Production parity	1075	12	69	381	1537

“Implemented” is a matrix classification tied to the emulator’s implementation and test references; test the exact feature, input shape, and client your application uses. “Implemented with limits” rows work locally within the concrete boundaries listed below; derived rows can overlap their child features.

Capabilities implemented with documented limits

The matrix records 12 development capabilities that work locally within documented limits. Each row names the capability and the boundary recorded for it.

Capability	Recorded boundary
PARTITION BY `sql.ddl.partition-by`	The _PARTITIONTIME/_PARTITIONDATE pseudocolumns of ingestion-time partitioned tables are not readable: rows carry no local ingestion time
CREATE MODEL (BQML) `sql.ddl.create-model-bqml`	STRUCT and non-numeric ARRAY features, TRANSFORM for PCA/DNN/autoencoder/time-series/matrix-factorization/contribution models, DNN_LINEAR_COMBINED_*, and TensorFlow/AutoML model types are refused locally
ST_SNAPTOGRID `sql.function.st-snaptogrid`	Only points and empty values are snapped; lines, polygons and multi-part values need S2Builder IntLatLngSnapFunction, which the installed S2 bindings do not expose
CREATE MODEL `metadata.enterprise.create-model`	STRUCT and non-numeric ARRAY features, TRANSFORM for PCA/DNN/autoencoder/time-series/matrix-factorization/contribution models, DNN_LINEAR_COMBINED_*, and TensorFlow/AutoML model types are refused locally
Column-level security `metadata.enterprise.column-level-security`	Policy tags on nested RECORD fields are refused; taxonomy import/export and cross-location replication are not served
Cloud Storage (CSV, JSON, Avro, Parquet, ORC, Bigtable) `metadata.advanced.cloud-storage-csv-json-avro-parquet-orc-bigtable`	Bigtable external tables are not implemented; Google Sheets, HTTP(S) and local-file sources are also outside the native external-table path (see the child rows)
Column-level security (policy tags) `metadata.advanced.column-level-security-policy-tags`	Policy tags on nested RECORD fields are refused; taxonomy import/export and cross-location replication are not served
ML.TRANSFORM `metadata.advanced.ml-transform`	TRANSFORM works for linear/logistic regression, KMEANS, boosted trees, random forests and TRANSFORM_ONLY; * REPLACE, expression.*, named preprocessing arguments and WARM_START are refused
Spark BigQuery connector Storage Read data path `client.spark.spark-bigquery-connector-storage-read`	Production Storage Read IAM is not emulated. Managed service scale and global availability are outside the pinned client profile.
TRANSFORM `sql.ddl.transform`	TRANSFORM works for linear/logistic regression, KMEANS, boosted trees, random forests and TRANSFORM_ONLY; * REPLACE, expression.*, named preprocessing arguments and WARM_START are refused
S2_COVERINGCELLIDS `sql.function.s2-coveringcellids`	Multi-point, multi-linestring and mixed collections, and buffers on non-point values, are refused
ST_UNION_AGG `sql.function.st-union-agg`	Linestring inputs (BigQuery merges them into one LINESTRING) and mixed point/polygon results are refused

Unsupported and unknown records

Before relying on a capability that this page does not list, test it with your application’s queries. Unsupported and unknown states must not be reduced to cloud scale alone: syntax, model variants, external sources, collation, and individual API methods can have developer-visible gaps. A successful dry run, stored configuration, or metadata operation does not prove execution support.

How to check a capability

Check the required capability ID and its exact operation and input boundary.
Confirm the dependency identity used by the LocalCloud image; dependency HEAD can differ from a packaged payload.
Run the application’s query or API workflow, assert the result and errors, and test restart when persistent state matters.
Record client versions, platform, dependency revision, assembled-image digest, failures, and skips.
Validate required production behavior against Google Cloud using a separate environment.

Runtime and production boundaries

Data and metadata live beneath the mounted BigQuery data directory. Verify the application’s queries after restart; a mounted volume alone is not a recovery guarantee.

Ingestion-time partition pseudocolumn reads, nested policy tags, and native Bigtable/Sheets/HTTP/local-file external sources are unavailable. Validate production IAM, billing, quotas, reservations, managed integrations, and recovery in Google Cloud.

Was this page helpful?