Compatibility matrix¶
Auto-regenerated each release from test results.
Legend: ✅ supported · ⚠️ partial · ❌ unsupported / out of scope
REST API¶
| Resource | Operation | Status |
|---|---|---|
| Projects | list | ✅ |
| Projects | getServiceAccount | ✅ |
| Datasets | list / get / insert / patch / update / delete | ✅ |
| Datasets | undelete | ⚠️ no-op stub |
| Tables | list / get / insert / patch / update / delete | ✅ |
| Tables | getIamPolicy / setIamPolicy | ⚠️ no-op stub |
| Jobs | query (synchronous) | ✅ |
| Jobs | insert (query type) / get / getQueryResults | ✅ |
| Jobs | insert (load / extract / copy) / list / cancel / delete | ✅ |
| Jobs | Load from local file (multipart upload) | ✅ |
| Jobs | Load from local file (resumable upload) | ✅ |
| TableData | insertAll / list | ✅ |
| Routines | CRUD | ✅ |
| Models | CRUD (metadata only) | ✅ |
| Row access policies | CRUD + enforcement | ✅ |
gRPC Storage Read API¶
| Operation | Format | Status |
|---|---|---|
| CreateReadSession, ReadRows | Arrow IPC | ✅ |
| CreateReadSession, ReadRows | Avro | ✅ |
| SplitReadStream | — (format-agnostic) | ✅ |
The canonical
BigQueryReadClient.create().createReadSession(...) Java code path
(Avro is Java's default wire format) runs unchanged against the
emulator. See ADR 0030.
gRPC Storage Write API¶
| Stream type | Input format | Status |
|---|---|---|
| DEFAULT | Arrow / proto | ✅ |
| COMMITTED | Arrow / proto | ✅ |
| PENDING | Arrow / proto | ✅ |
| BUFFERED | Arrow / proto | ✅ |
SQL features¶
| Feature | Status |
|---|---|
| SELECT / JOIN / WHERE / GROUP BY / HAVING / ORDER BY / LIMIT | ✅ |
| CTEs (WITH, WITH RECURSIVE) | ✅ |
| Window functions | ✅ |
| ARRAY, STRUCT, UNNEST | ✅ |
| MERGE / INSERT / UPDATE / DELETE / TRUNCATE | ✅ |
| Transactions (BEGIN / COMMIT / ROLLBACK) | ✅ |
| Partitioning (time-unit / ingestion / integer-range) | ✅ |
| Clustering | ✅ |
Wildcard tables (_TABLE_SUFFIX) |
✅ |
| SQL UDFs | ✅ |
| JavaScript UDFs | ✅ |
| Table-valued functions | ✅ |
| Procedural scripting (DECLARE / BEGIN / END / IF / LOOP) | ✅ |
Time travel (FOR SYSTEM_TIME AS OF) |
✅ |
| Table snapshots + CLONE | ✅ |
| Materialized views | ✅ |
| Row access policies (enforced) | ✅ |
| Authorized views | ✅ |
| INFORMATION_SCHEMA (SCHEMATA, TABLES, COLUMNS, TABLE_OPTIONS, VIEWS, PARTITIONS, ROUTINES, MATERIALIZED_VIEWS, ROW_ACCESS_POLICIES) | ✅ — JOBS family deliberately out of scope |
| GEOGRAPHY (via spatial extension) | ✅ |
| RANGE |
✅ |
| INTERVAL | ✅ |
| BigQuery ML | ❌ out of scope |
Types¶
| Type | Status |
|---|---|
| INT64, FLOAT64, BOOL, STRING, BYTES | ✅ |
| NUMERIC, BIGNUMERIC | ✅ |
| DATE, TIME, DATETIME, TIMESTAMP | ✅ |
| JSON | ✅ |
| ARRAY |
✅ |
| GEOGRAPHY | ✅ |
| RANGE |
✅ |
| INTERVAL | ✅ |
Load + extract file formats¶
| Format | Load | Extract |
|---|---|---|
| CSV | ✅ | ✅ |
| NEWLINE_DELIMITED_JSON | ✅ | ✅ |
| PARQUET | ✅ | ✅ |
| AVRO | ✅ | ✅ |
| ORC | ✅ (requires [orc] extra) |
❌ (out of scope — BigQuery itself does not extract to ORC) |
bqemulator is a strict superset of both goccy and BigQuery on
the load/extract format axis: equal to BigQuery on the
intersect-with-BigQuery set, ahead of goccy on Parquet extract +
Avro/ORC load + Avro extract. See
ADR 0027 for the design
decisions behind the Avro extension + pyorc integration.
Supported clients¶
bqemulator's REST + gRPC surfaces are exercised by five conformance clients on every CI run. Every shipped feature is proven against this matrix; a regression that surfaces in one client but not another fails the build.
| Client | Surface |
|---|---|
google-cloud-bigquery (Python) |
REST + gRPC |
@google-cloud/bigquery (Node.js) |
REST + gRPC |
cloud.google.com/go/bigquery (Go) |
REST + gRPC |
com.google.cloud:google-cloud-bigquery (Java) |
REST + gRPC |
bq CLI (gcloud SDK) |
REST |
The bq CLI does not exercise the Storage Read or Storage Write gRPC
surfaces — it has no commands that talk to those APIs. See
ADR 0032 for design
notes and docs/guides/using-bq-cli.md
for the canonical configuration recipe.
goccy bigquery-emulator's
FEATURE.md
documents Python, Ruby, PHP, Node.js, Java, and the bq CLI as
its supported-clients matrix. bqemulator is a strict superset on
this axis at v1.0 tag time (we ship Go in place of Ruby/PHP; the
latter two are deferred to a follow-up RFC if user demand
surfaces).
Conformance corpus snapshot¶
Auto-generated. Edit fixtures under
tests/conformance/or update the XFAIL registry intests/conformance/divergences.py, then runmake compat-matrixto regenerate this block. The CI gate (--check) refuses to merge a PR whose committed snapshot has drifted from the corpus.
- Corpus totals: 1291 fixtures (1213 SQL + 52 HTTP + 26 gRPC); 1280 PASS / 11 XFAIL
- XFAIL contract: every pin in
KNOWN_DIVERGENCESreferences an ADR orout-of-scope.mdsection — invented divergences are forbidden (see ADR 0023).
Per-phase fixture coverage¶
Each row aggregates fixtures by corpus (SQL / HTTP / gRPC) and the on-disk phase directory. The Status column is derived: ✅ when every fixture in the phase passes; ⚠ when at least one fixture is pinned in the XFAIL registry.
| Corpus | Phase | Fixtures | PASS | XFAIL | Status |
|---|---|---|---|---|---|
| SQL | api_configuration |
63 | 63 | 0 | ✅ |
| SQL | export_data |
11 | 11 | 0 | ✅ |
| SQL | information_schema |
18 | 18 | 0 | ✅ |
| SQL | partitioning_clustering |
23 | 23 | 0 | ✅ |
| SQL | rest_crud |
169 | 169 | 0 | ✅ |
| SQL | routines_scripting |
70 | 70 | 0 | ✅ |
| SQL | row_access |
23 | 22 | 1 | ⚠ |
| SQL | specialized_types |
150 | 143 | 7 | ⚠ |
| SQL | standard_functions |
662 | 659 | 3 | ⚠ |
| SQL | versioning |
24 | 24 | 0 | ✅ |
| HTTP | jobs |
52 | 52 | 0 | ✅ |
| gRPC | storage_read |
16 | 16 | 0 | ✅ |
| gRPC | storage_write |
10 | 10 | 0 | ✅ |
| Total | 1291 | 1280 | 11 | ⚠ |
XFAIL pin registry¶
All 11 entries in tests/conformance/divergences.py — each rationale references an ADR or out-of-scope.md section so closure paths stay traceable.
| Fixture id | Rationale (short) |
|---|---|
row_access/caller_information_schema_visibility |
INFORMATION_SCHEMA.ROW_ACCESS_POLICIES requires bigquery.rowAccessPolicies.list IAM permission. |
specialized_types/spheroidal_buffer_neighborhood_match |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/spheroidal_buffer_state_xfail |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/spheroidal_buffer_street_match |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/st_asbinary_point |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/st_buffer_continental |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/st_centroid_polygon |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
specialized_types/st_intersection_polygons |
Spheroidal-vs-planar divergence — see ADR 0019 and docs/reference/out-of-scope.md#spheroidal-geometry-on-geog… |
standard_functions/agg_hll_count_init_basic |
HLL sketch BYTES format differs — see docs/reference/out-of-scope.md#hll-sketch-binary-format-hll_countinit-m… |
standard_functions/agg_hll_count_merge_partial_basic |
HLL sketch BYTES format differs — see docs/reference/out-of-scope.md#hll-sketch-binary-format-hll_countinit-m… |
standard_functions/bound_bignumeric_max |
BIGNUMERIC literal with 39 integer digits exceeds DuckDB's DECIMAL(38, 0) cap; literals with ≤ 38 integer dig… |