# Bigtable emulator

> Run Bigtable locally: data, administration, GoogleSQL, change streams, materialized views, backups, and IAM workflows in one Docker container.
>
> Source: https://local.cloud/services/bigtable/

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.

## 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

Connection

Environment variable

`BIGTABLE_EMULATOR_HOST=localhost:5385`

Runtime details

- **Endpoints:** gRPC :5385
- **Minimum tier:** [Pro tier, free during preview](https://local.cloud/pricing/#pro-tier)
- **Persistence:** service-data
- **Implementation:** Custom Emulator

## 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](https://local.cloud/docs/)

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

Python:

### 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

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

#### Save as hello.py

```python
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

```bash
python hello.py
```

#### Verify the result

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

#### Expected output

```
hello
```

[Full example guide](https://local.cloud/docs/sdk-examples/#bigtable-python)

Java:

### 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

```bash
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

```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

```bash
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:

### 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

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

#### Run in your terminal

```bash
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

- [Build an integration test loop](https://local.cloud/gcp-integration-testing/): Start the runtime, verify readiness, exercise your SDK, and clean up test state.
- [Bigtable emulator feature comparison](https://local.cloud/compare/emulators/?service=bigtable): Browse features by category, see which ones only LocalCloud offers, and open Google's documentation for each.
- [Official SDK code samples](https://docs.cloud.google.com/bigtable/docs/samples): Browse language-specific samples. Adapt endpoints and use the local workflows listed above.

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](https://local.cloud/ai/) 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](https://local.cloud/compatibility/): compare all 27 service guides.
- [Configuration](https://local.cloud/docs/configuration/): service selection and runtime settings.
- [Bigtable feature reference](https://local.cloud/docs/bigtable-emulator-features/): detailed operation and recovery notes.
- [Official Bigtable documentation](https://docs.cloud.google.com/bigtable/docs/overview): service concepts and cloud usage.