Bigtable emulator

Bigtable is a wide-column database for large key-based datasets. Rows are sorted by key, making it useful for time-series data, event histories, and fast range reads.

When to use Bigtable

Typical uses

Use when high-volume records can be organized by a row key and retrieved through point lookups or bounded key-range scans. Design the row key around your most frequent reads.

Examples

Sensor readings and time-series events
Per-user activity and transaction histories

Example usage

Service ID: bigtable. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and BIGTABLE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Write and read a Bigtable cell

Write a cell and read its bytes back; Bigtable organizes wide-column data around efficient row-key access.

Create a test instance and table, write a cell, verify its bytes, and clean up.

SDK dependencies

Run in a new example directory

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-cloud-bigtable

Save as hello.py

import os
from uuid import uuid4
from google.cloud import bigtable

assert os.environ['BIGTABLE_EMULATOR_HOST']
client = bigtable.Client(project=os.environ['GOOGLE_CLOUD_PROJECT'], admin=True)
instance = client.instance('guide-' + uuid4().hex[:12])
instance.create(clusters=[instance.cluster('local', location_id='us-central1-a', serve_nodes=1)]).result(timeout=60)
try:
    table = instance.table('messages')
    table.create(column_families={'cf': None})
    row = table.direct_row(b'row-1')
    row.set_cell('cf', b'message', b'hello')
    row.commit()
    message = table.read_row(b'row-1').cells['cf'][b'message'][0].value
    assert message == b'hello'
    print(message.decode())
    table.delete()
finally:
    instance.delete()
    client.close()

Run the example

python hello.py

Verify the result

The command completes successfully and prints the expected output shown below.

Expected output

hello

Full example guide

Java

List local Bigtable instances

List database instances; Bigtable organizes large datasets for fast row-key lookups and range scans.

The Bigtable Java client detects BIGTABLE_EMULATOR_HOST automatically. Requires JDK 17+ and Maven.

Discovery check · reads existing local state.

SDK dependencies

Run in a new example directory

cat > pom.xml <<'XML'
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId><artifactId>local-example</artifactId><version>1</version>
  <dependencies><dependency>
    <groupId>com.google.cloud</groupId><artifactId>google-cloud-bigtable</artifactId><version>2.85.0</version>
  </dependency></dependencies>
</project>
XML
mvn -q dependency:build-classpath -Dmdep.outputFile=classpath.txt

Save as Hello.java

import com.google.cloud.bigtable.admin.v2.BigtableInstanceAdminClient;
import com.google.cloud.bigtable.admin.v2.BigtableInstanceAdminSettings;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    Objects.requireNonNull(System.getenv("BIGTABLE_EMULATOR_HOST"));
    var settings = BigtableInstanceAdminSettings.newBuilder()
        .setProjectId(Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"))).build();
    try (var client = BigtableInstanceAdminClient.create(settings)) {
      for (var instance : client.listInstances()) {
        System.out.println(instance.getId());
      }
    }
  }
}

Run the example

java --class-path "$(cat classpath.txt)" Hello.java

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

cbt CLI

Browse local Bigtable instances

Browse database instances; Bigtable stores wide-column data for fast key-based reads and scans.

Use the native Bigtable CLI with BIGTABLE_EMULATOR_HOST. Requires cbt from the Google Cloud CLI tools.

Discovery check · reads existing local state.

Configure cbt CLI

: "${BIGTABLE_EMULATOR_HOST:?Export the LocalCloud environment first}"

Run in your terminal

cbt -project="${GOOGLE_CLOUD_PROJECT:?Export the LocalCloud environment first}" listinstances

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

Instances, clusters, tables, families, app profiles, and schema bundles

Create an instance, cluster, table, and column family for a test namespace. Configure its app profile or schema bundle, then read the administration resources back before writing data.
Atomic mutations, row filters including Sink, aggregates, and read sessions

Write cells with explicit row keys and timestamps, apply an atomic mutation, and read a bounded key range. Assert returned bytes and filter results, including the effect of Sink on later filters.
Prepared GoogleSQL, logical views, and continuous materialized views

Prepare and execute a GoogleSQL query against fixture rows, then exercise the logical or continuous materialized view your application uses. Compare returned values after a source-row change.
Change streams

Open a change stream, mutate a row, and check the resulting record and continuation path. Use the local single-partition stream to test consumer handling of repeated records.
Data-bearing backups, copy/restore, and seven-day table undelete

Back up a table containing known bytes, restore or copy the backup, and compare the restored rows through the native client. Test seven-day table undelete separately from backup restoration.
IAM policy storage, cbt, and Console browsing

Read and update stored IAM policies, browse rows in the Console, and run the cbt commands used by your scripts. Check native API errors when a write or cleanup operation fails.

Service boundaries

Permissive IAM and one change-stream partition; no query statistics, view parameters, or legacy snapshots
Sink bypasses later filters and is invalid inside Condition; HLL++ and multi-column view keys use local encodings
Delete owned backups and clear deletion protection before cleanup; check native API errors and retained project records
Native backup listing supports filter/order/pagination; REST ignores them. Verify durability and row bytes with the native client

Code examples and integrations

Integration

Build an integration test loop

Start the runtime, verify readiness, exercise your SDK, and clean up test state.

Open guide

Comparison

Bigtable emulator feature comparison

Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.

Open guide

Google Cloud

Official SDK code samples

Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

Browse official samples

Agent testing

Use Bigtable with an AI agent

Before the agent changes application logic, have it create local Bigtable state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Bigtable emulator FAQ

How do I run Bigtable locally?

Start LocalCloud using the setup guide, then export its environment in the same terminal as your application.

Which environment variable points the SDK at the local Bigtable?

LocalCloud exports BIGTABLE_EMULATOR_HOST=localhost:5385. Use the generated value, because the CLI picks another port when the default is in use. Some SDKs also need explicit client endpoint options; the variable alone does not route them locally.

Does the local Bigtable behave exactly like Google Cloud?

No. LocalCloud runs the documented workflows on this page within the service boundaries listed here. Validate behavior against real Bigtable before production deployment.

Related guides

Compatibility: compare all 27 service guides.
Configuration: service selection and runtime settings.
Bigtable feature reference: detailed operation and recovery notes.
Official Bigtable documentation : service concepts and cloud usage.

Bigtable emulator

Typical uses

Explore another service

Example usage

Python

Write and read a Bigtable cell

Save as hello.py

Run the example

Verify the result

Expected output

Java

List local Bigtable instances

Save as Hello.java

Run the example

Verify the result

cbt CLI

Browse local Bigtable instances

Configure cbt CLI

Run in your terminal

Verify the result

Documented workflows

Instances, clusters, tables, families, app profiles, and schema bundles

Atomic mutations, row filters including Sink, aggregates, and read sessions

Prepared GoogleSQL, logical views, and continuous materialized views

Change streams

Data-bearing backups, copy/restore, and seven-day table undelete

IAM policy storage, cbt, and Console browsing

Service boundaries

Code examples and integrations

Build an integration test loop

Bigtable emulator feature comparison

Official SDK code samples

Use Bigtable with an AI agent

Configure this repo

Bigtable emulator FAQ

How do I run Bigtable locally?

Which environment variable points the SDK at the local Bigtable?

Does the local Bigtable behave exactly like Google Cloud?

Related guides