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

Databases

Hello world

Example usage

Install the CLI, start LocalCloud, and export its environment in the same shell. Generated endpoints account for remapped ports.

1. Install and start · shell

curl -fsSL https://local.cloud/install.sh | sh
localcloud start --local-only
# Export GOOGLE_CLOUD_PROJECT and BIGTABLE_EMULATOR_HOST
eval "$(localcloud env)"

Python

Write and read a Bigtable cell

2. Install SDK · shell

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

3. 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()

4. Runpython hello.py

Full example guide

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

Sink preserves cells past later filters; invalid inside a Condition
Verify backup listing and project deletion through the native admin API
Validate Sink filters, PostgreSQL-backed durability, and cbt scripts in your own test suite
Delete owned backups and clear resource deletion protection before instance or project deletion
Failed project cleanup keeps the project record; confirm deletion through the native admin API
Native backup listing supports filter/order/pagination; REST ignores those options
Confirm writes through the native API; the Console view may not surface rejected writes
Permissive IAM; one change-stream partition
No query statistics, view parameters, or legacy snapshot RPCs
Local encodings for HLL++ bytes and multi-column view keys

Try it in your project

Code examples and integrations

Start with the local guides. Official Google Cloud samples may need endpoint changes and can cover features outside the workflows listed here.

Integration

Build an integration test loop

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

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.