Bigtable Emulator Coverage

This page documents the feature coverage of LocalCloud’s extended Bigtable emulator (bigtable-emulator-extended), which adds persistence, change streams, continuous materialized views, and additional Admin API support on top of the upstream Google Cloud Bigtable emulator.

The emulator is compatible with standard Bigtable SDKs via the BIGTABLE_EMULATOR_HOST environment variable.

Support legend

Status	Meaning
Supported	Provides functional and API parity to Bigtable production capabilities.
Supported*	Exposes and accepts the API but may not enforce behavior (e.g., IAM stubs, metadata-only backups).
Not supported	Unsupported, cloud-only, outside emulator scope, or returns Unimplemented.

Support summary

Area	Status	What this means for developers
Data API (reads and writes)	Supported	ReadRows, MutateRow, MutateRows, CheckAndMutateRow, ReadModifyWriteRow, and SampleRowKeys execute locally with full filter and mutation support.
Read filters	Supported	All 17 filter types including composite (chain, interleave, condition), regex, range, limiting, and transformer filters.
Table Admin API	Supported	Table CRUD, column family management with GC rules, DropRowRange, consistency tokens, and deletion protection.
Instance Admin API	Supported	Instance, cluster, and app profile CRUD with cascading deletes and partial updates.
Change streams	Supported	Single-partition streaming with continuation tokens, start-time filtering, and heartbeats.
Continuous materialized views	Supported	Write-time re-keying with automatic shadow table creation and propagation. LocalCloud-extended feature.
Backups	Supported*	Full CRUD and CopyBackup for metadata. RestoreTable creates table with schema but no data restore.
Authorized and logical views	Supported*	Metadata CRUD works. No access enforcement on reads/writes.
IAM	Supported*	Permissive stubs — GetIamPolicy, SetIamPolicy, and TestIamPermissions always succeed.
Persistence	Supported	SQLite3 (default) or PostgreSQL backends. All entities persist across restarts.
GoogleSQL for Bigtable	Not supported	PrepareQuery and ExecuteQuery return Unimplemented.
Replication and multi-cluster	Not supported	Single-process emulator. No replication, failover, or multi-cluster consistency.

Data API

Area	Status	Covered	Limits
ReadRows	Supported	Streaming reads with full filter pipeline, row key ranges, row key sets, and multiple row ranges.	No read throttling or quota enforcement.
MutateRow	Supported	Atomic single-row mutations: SetCell, DeleteFromColumn, DeleteFromFamily, DeleteFromRow.	No server-side timestamp assignment differences from production.
MutateRows	Supported	Streaming batch mutations with per-entry error reporting and status codes.	No batch size limits enforced.
CheckAndMutateRow	Supported	Predicate-based conditional mutations with true/false mutation branches.	No production-grade atomicity guarantees in concurrent scenarios.
ReadModifyWriteRow	Supported	Atomic increment (AddToCell for int64 sum) and append operations.	Only int64 sum aggregation supported. HyperLogLog and other aggregate types return raw input unchanged.
SampleRowKeys	Supported	Returns approximate row key samples for partitioning.	Sampling is approximate; no production-grade distribution guarantees.
PingAndWarm	Supported	No-op, always succeeds.	—
PrepareQuery	Not supported	Returns Unimplemented.	GoogleSQL for Bigtable not supported.
ExecuteQuery	Not supported	Returns Unimplemented.	GoogleSQL for Bigtable not supported.

Read filters

Filter	Status	Behavior	Limits
Chain	Supported	Applies multiple filters in sequence, each filtering the output of the previous.	—
Interleave	Supported	Union of filter results with deduplication of matching cells.	—
Condition	Supported	If/then/else branching — applies true or false filter based on predicate match.	—
BlockAllFilter	Supported	Drops all cells.	—
PassAllFilter	Supported	Passes all cells unchanged.	—
RowKeyRegexFilter	Supported	Binary regex matching against row keys.	—
FamilyNameRegexFilter	Supported	Regex matching against column family names.	—
ColumnQualifierRegexFilter	Supported	Regex matching against column qualifiers.	—
ValueRegexFilter	Supported	Regex matching against cell values.	—
ColumnRangeFilter	Supported	Range by column qualifier within a family, with inclusive/exclusive bounds.	—
TimestampRangeFilter	Supported	Microsecond-precision range filtering on cell timestamps.	—
ValueRangeFilter	Supported	Range filtering on cell values with inclusive/exclusive bounds.	—
CellsPerRowLimitFilter	Supported	Limits number of cells returned per row.	—
CellsPerRowOffsetFilter	Supported	Skips first N cells per row.	—
CellsPerColumnLimitFilter	Supported	Limits number of versions per column.	—
RowSampleFilter	Supported	Probabilistic row sampling.	—
StripValueTransformer	Supported	Removes cell values while keeping metadata (family, qualifier, timestamp).	—
ApplyLabelTransformer	Supported	Adds custom string labels to matched cells.	—

Table Admin API

Area	Status	Covered	Limits
CreateTable	Supported	Create tables with column families, GC rules, and initial row key splits.	—
ListTables	Supported	List all tables in an instance.	—
GetTable	Supported	Returns table metadata including deletion protection status.	—
UpdateTable	Supported	Update deletion_protection and automated_backup_policy fields.	—
DeleteTable	Supported	Respects deletion protection. Returns error if protection enabled.	—
ModifyColumnFamilies	Supported	Create, update, and delete column families with GC rules (MaxNumVersions, MaxAge, union, intersection).	—
DropRowRange	Supported	Clear row range by prefix or delete all rows from table.	—
GenerateConsistencyToken	Supported	Returns consistency token for replication checks.	—
CheckConsistency	Supported	Always returns consistent (single-process emulator).	—
UndeleteTable	Not supported	Returns Unimplemented.	—
Snapshot APIs	Not supported	SnapshotTable, GetSnapshot, ListSnapshots, DeleteSnapshot, CreateTableFromSnapshot all return Unimplemented. Deprecated upstream.	—

Instance Admin API

Area	Status	Covered	Limits
Instance CRUD	Supported	CreateInstance (auto-creates clusters, sets type/display name/labels), GetInstance, ListInstances, UpdateInstance, PartialUpdateInstance, DeleteInstance (cascades to tables, clusters, app profiles).	No billing or quota enforcement.
Cluster CRUD	Supported	CreateCluster, GetCluster, ListClusters, UpdateCluster, PartialUpdateCluster (update serve_nodes), DeleteCluster.	Serve nodes and storage type stored but not enforced.
App Profile CRUD	Supported	CreateAppProfile (auto-sets SingleClusterRouting and StandardIsolation defaults), GetAppProfile, ListAppProfiles, UpdateAppProfile, DeleteAppProfile.	Routing policy stored but not enforced for reads/writes.
IAM	Supported*	GetIamPolicy returns stored policy or empty default. SetIamPolicy stores policy in memory. TestIamPermissions always returns all requested permissions.	Permissive stubs — no actual access control enforcement.
ListHotTablets	Not supported	Returns Unimplemented.	—

Change streams and materialized views

Area	Status	Covered	Limits
GenerateInitialChangeStreamPartitions	Supported	Returns one stable full-table partition token.	Single partition only. No partition-level row key range filtering.
ReadChangeStream	Supported	Streaming change events with continuation tokens, start-time filtering, configurable heartbeat duration (default 5s), and mutation type tracking (set_cell, delete_from_column, delete_from_family, delete_from_row). Microsecond-precision commit timestamps.	Single partition only. No multi-partition fan-out or partition merging.
Change log storage	Supported	SQL-backed change_log_t table with automatic append on MutateRow, MutateRows, and ReadModifyWriteRow.	—
CreateMaterializedView	Supported	SQL query parsing, composite key mapping with reordering, configurable key separator, optional source key appending, selective column family inclusion, automatic shadow table creation. LocalCloud-extended feature.	CMV SQL parser scoped to standard Bigtable CMV query format. No backfill of existing data.
CMV write-time propagation	Supported	Automatic propagation on MutateRow, MutateRows, CheckAndMutateRow, ReadModifyWriteRow. Delete propagation for DeleteFromRow and DropRowRange.	GC policy changes after CMV creation not reflected in shadow table. No ModifyColumnFamilies sync to shadow tables.
GetMaterializedView	Supported	Returns CMV metadata including query, deletion protection, and source table reference.	—
ListMaterializedViews	Supported	List all CMVs in an instance.	—
UpdateMaterializedView	Supported	Toggle deletion protection. Query is immutable after creation.	—
DeleteMaterializedView	Supported	Respects deletion protection. Removes shadow table.	—

Backups, views, and protection

Area	Status	Covered	Limits
Backup CRUD	Supported*	CreateBackup, GetBackup, UpdateBackup (expire time), DeleteBackup, ListBackups (by parent cluster). State is always READY immediately.	Metadata-only — no actual data snapshot is taken.
CopyBackup	Supported*	Clones backup metadata with source_backup reference.	Metadata copy only.
RestoreTable	Supported*	Creates new table with source table schema (column families and GC rules).	Schema restore only — no row data is restored.
Authorized view CRUD	Supported*	CreateAuthorizedView, GetAuthorizedView, ListAuthorizedViews, UpdateAuthorizedView, DeleteAuthorizedView. Deletion protection supported.	No access enforcement — reads/writes return full table data regardless of view restrictions.
Logical view CRUD	Supported*	CreateLogicalView, GetLogicalView, ListLogicalViews, UpdateLogicalView, DeleteLogicalView. Deletion protection supported.	Query strings stored but not executed.
Deletion protection	Supported	Enforced for tables, materialized views, authorized views, logical views. DeleteTable/Delete* returns error when protection enabled.	Not supported for instances.

Garbage collection

Area	Status	Covered	Limits
MaxNumVersions	Supported	Keeps only the N most recent cell versions per column.	—
MaxAge	Supported	Removes cells older than specified duration.	—
Union and intersection rules	Supported	Composite GC rules combining multiple policies.	—
GC execution model	Supported	Lazy GC applied at read and write time on a per-row basis.	Single-process model. No background GC compaction.

Explicit non-production behavior

Area	Status	Tested behavior
IAM policies	Supported*	SetIamPolicy stores policy, GetIamPolicy returns it, TestIamPermissions returns all requested permissions. No access control enforcement.
Backups	Supported*	Full metadata lifecycle works. No actual data snapshot — RestoreTable recreates schema only.
Authorized views	Supported*	CRUD operations work. No read/write filtering — all data accessible regardless of view definition.
Logical views	Supported*	CRUD operations work. Query strings are stored but never executed.
Consistency checks	Supported*	CheckConsistency always returns consistent. Single-process emulator has no replication lag.
Aggregate mutations	Supported*	AddToCell and MergeToCell support int64 sum aggregation. HyperLogLog and other aggregate types return raw input without transformation.
Change stream partitions	Supported*	Single full-table partition only. No partition splitting, merging, or row key range filtering.

Unsupported product areas

Area	Status	What to expect
GoogleSQL for Bigtable	Not supported	PrepareQuery and ExecuteQuery return Unimplemented. Use the Data API filter pipeline for queries.
Replication and multi-cluster	Not supported	Single-process emulator. No cross-cluster replication, automatic failover, or multi-cluster routing.
Encryption (CMEK)	Not supported	No customer-managed encryption key support. Data stored unencrypted in SQLite/PostgreSQL.
Autoscaling	Not supported	Node counts and storage type are stored as metadata but not enforced. No autoscaling behavior.
Hot tablets and Key Visualizer	Not supported	ListHotTablets returns Unimplemented. No Key Visualizer or performance profiling.
Data Boost	Not supported	No Data Boost read isolation. All reads go through the single emulator process.
Snapshots (deprecated)	Not supported	SnapshotTable, GetSnapshot, ListSnapshots, DeleteSnapshot, and CreateTableFromSnapshot return Unimplemented. These APIs are deprecated upstream.
Connector parity	Not supported	HBase, Beam, Spark, Flink, and Kafka connector compatibility is not tested. Standard gRPC SDK clients work.
Schema bundles	Not supported	No schema bundle management support.
Production operations	Not supported	Quota enforcement, billing, audit logging, monitoring metrics, and production-grade authentication are outside emulator scope.

Developer workflow coverage

Based on the supported features above, the emulator is suited for local workflows that need to:

• Set up instances, clusters, tables, and column families with GC rules in tests.
• Read and write rows with full filter pipelines, conditional mutations, and atomic read-modify-write operations.
• Test change stream consumers with realistic mutation events and continuation tokens.
• Develop materialized view workflows with automatic write-time re-keying propagation.
• Exercise backup and view management APIs for setup and teardown code paths.
• Persist all state across emulator restarts via SQLite or PostgreSQL.
• Run SDK-backed integration tests against a local endpoint using BIGTABLE_EMULATOR_HOST.

This is developer-environment support for local tests and CI, not a production implementation parity claim. Replication, encryption, autoscaling, quota enforcement, and production auth are outside the supported scope.

Persistence and configuration

The emulator supports two persistence backends:

Backend	Storage format	Default
SQLite3	BLOB binary, AUTOINCREMENT IDs	Yes
PostgreSQL	BYTEA binary, BIGSERIAL IDs	No

All entities are persisted across restarts: rows, tables, instances, clusters, app profiles, materialized views (metadata and shadow table data), change log records, authorized views, backups, and logical views.

SDK integration: Set BIGTABLE_EMULATOR_HOST to the emulator address. Standard Bigtable SDKs (Go, Python, Node.js, Java, etc.) connect automatically with unauthenticated gRPC.

Embedded usage: The emulator can be embedded as a Go library via the bttest package for in-process testing.