Services Bigtable emulator features

Bigtable emulator feature reference

LocalCloud runs a separately maintained Bigtable emulator for row and administration APIs. The current Docker build pins a source commit.

Connection and persistence

Surface	Canonical value	Boundary
Primary API	gRPC on `localhost:5385`	Use `BIGTABLE_EMULATOR_HOST` from `localcloud env` for actual mapped ports.
Backing store	PostgreSQL under the mounted LocalCloud volume	A standalone dependency’s SQLite configuration is not the LocalCloud default.
Console SQL	LocalCloud SQL-to-row-API translator	Separate from native GoogleSQL `PrepareQuery` / `ExecuteQuery` and session protocols.

Current operation contract

Use the Bigtable documented workflows for application scenarios; this table describes individual API areas.

Operation area	Status	Boundary
instances/tables/families	Supported	The pinned little_bigtable v0.5.0 emulates instance, cluster, app-profile, table and schema-bundle administration as validated metadata (ID and field rules, response views, update masks, pagination, deletion protection, soft delete and 7-day undelete, atomic column-family changes, initial splits, row key schema) with a durable long-running-operation registry. Cluster nodes and autoscaling settings are stored without capacity effects. Dependency conformance tests pass.
row mutations and reads	Supported	The emulator validates every mutation before applying any (single-row atomicity), reports real per-entry MutateRows codes, honors idempotency tokens and aggregate (Sum/Min/Max, HLL++) families, implements every RowFilter including Interleave duplicates, Sink (cells bypass subsequent filters; invalid inside Condition) and ValueBitmask, chunks ReadRows like production with request stats, samples SampleRowKeys within row ranges, enforces authorized-view, materialized-view and app-profile targets, and serves the OpenTable/OpenAuthorizedView/OpenMaterializedView session protocol. last_scanned_row_key is not emitted. Sink output and rejection inside Condition have named dependency conformance tests; validate Sink filters in your own test suite. Dependency conformance tests pass.
cbt CLI compatibility	Supported	Set BIGTABLE_EMULATOR_HOST and pass -project to cbt unless the project is already configured in.cbtrc or gcloud. GOOGLE_CLOUD_PROJECT alone does not select the cbt project. Table commands also require -instance. Clear stored -admin-endpoint and -data-endpoint overrides when relying on the emulator variable. A non-secret -access-token=localcloud can avoid credential discovery for local plaintext use; it is optional for the tested cbt version. It is not a Google credential. Arbitrary project and instance IDs are accepted on-demand without pre-registration, matching Google Cloud SDK CBT emulator behavior. The gRPC data plane accepts requests without an authorization header or credential provider. Instance CRUD (create/list/get/delete instance) is supported via gRPC. Table and row operations work as expected. The pinned cbt conformance test was skipped because cbt was not installed; validate cbt scripts in your own test suite.
localcloud console data browser	Supported	REST endpoints for instance/table/row CRUD exposed via BigtableAdminService: - GET /.../tables/{table}/rows — browse rows - POST /.../tables/{table}/rows — write cells - DELETE /.../tables/{table}/rows/{rowKey} — delete row SDK and console share the same PostgreSQL-backed emulator state. Instance, table and backup routes forward to the emulator and return its errors with the Google API HTTP mapping (FAILED_PRECONDITION as 400, for example). Row writes and deletes, app-profile and view routes still ignore emulator errors and report success from local placeholder state, and instance PATCH/PUT and table PATCH answer locally without reaching the emulator, so a rejected request on those routes can appear to succeed.
data survives emulator restart	Supported	The emulator persists all resource state in PostgreSQL, including table policy fields, views, schema bundles, backups and their row snapshots, IAM policies, long-running operations, the change-stream outbox and idempotency tokens. On first start it migrates table metadata in place (one-way). Its restart tests ran on SQLite; validate PostgreSQL restart durability in your own test suite.
materialized views (CMVs)	Supported	The emulator implements continuous materialized views from GoogleSQL GROUP BY or ORDER BY definitions over existing tables. Views are read-only, read through materialized_view_name (ReadRows, SampleRowKeys, sessions) or GoogleSQL, recomputed before a read when stale, limited to 50 per instance and 5 per source table, and their query is immutable. Multi-column row-key encoding is emulator-specific.
GoogleSQL queries and logical views	Supported	The emulator builds its GoogleSQL engine by default. PrepareQuery returns a prepared-query token valid for one hour; ExecuteQuery streams typed ProtoRows batches with CRC32C checksums and resume tokens, and returns FailedPrecondition (PREPARED_QUERY_EXPIRED) after a schema change. Logical-view queries are validated against existing tables and are queryable. Query statistics and view parameters are not emulated. The Console SQL editor uses LocalCloud's separate translator.
change streams	Supported	The emulator records changes only for tables with change_stream_config (1-7 day retention). ReadChangeStream returns one grouped record per row commit, garbage-collection and DropRowRange records, heartbeats with continuation tokens and low watermarks, resumes from tokens and closes at end_time. It requires a single-cluster app profile. One partition covers the whole key space, so partition split and merge are not exercised.
snapshots and backups	Supported	Backups are immutable schema-and-row snapshots with create, get, list (filter, order, pagination), update, copy, delete and restore to a new table independent of the live source, including expire-time, backup-type and quota rules. UndeleteTable restores a deleted table within 7 days. Legacy table snapshot RPCs return Unimplemented because they are a deprecated private-alpha API. The LocalCloud REST facade forwards backup create, get, list, update (with the required updateMask), copy, delete, restore and undelete to the emulator and returns its errors.
IAM policy management	Supported	The emulator persists policies on existing Bigtable resources with etags (Aborted on mismatch) and update masks, and returns NotFound for missing resources. Policies are permissive. TestIamPermissions grants every requested permission and nothing is enforced on the direct gRPC listener, because the emulator is unauthenticated.
new proto methods return Unimplemented (no panics)	Supported	The executable ledger dispositions all 89 registered RPCs of the cloud.google.com/go/bigtable v1.58.0 interface, and a test fails if one is missing. Intentionally unsupported RPCs (legacy snapshots, hot tablets, memory layers) return Unimplemented instead of panicking. PingAndWarm validates the instance name and app profile.

Runtime and recovery limits

LocalCloud uses PostgreSQL-backed persistence. Test a restart against the mounted volume and compare exact row bytes. IAM is permissive, change streams use one partition, and local HLL++/multi-column view-key encodings differ from cloud representations.

Verify backup and cleanup behavior

Write known row keys, families, qualifiers, timestamps, and values through the native client.
Create a data-bearing backup and restore it to a separate table. Read the restored cells and compare the bytes; metadata readback alone is insufficient.
List backups through the native administration API when using filters, ordering, or pagination. The REST path ignores those options.
Delete owned backups and clear resource deletion protection before deleting the instance or project. If cleanup fails, inspect the native API error and retained project record.

For row-filter tests, Sink preserves cells past subsequent filters and is invalid inside a Condition. Verify writes through the native API when the Console does not surface a rejection. Validate managed replication and production authorization in Google Cloud.

Was this page helpful?