Cloud Bigtable Guide

# Enable the Bigtable APIs
gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com

# Create a development instance (1 node, lower cost)
gcloud bigtable instances create my-bigtable-dev \
  --display-name="Development Instance" \
  --cluster-config=id=my-cluster-1,zone=us-central1-a,nodes=1,storage-type=SSD \
  --instance-type=DEVELOPMENT

# Create a production instance with replication
gcloud bigtable instances create my-bigtable-prod \
  --display-name="Production Instance" \
  --cluster-config=id=cluster-us-central,zone=us-central1-a,nodes=3,storage-type=SSD \
  --cluster-config=id=cluster-us-east,zone=us-east1-b,nodes=3,storage-type=SSD

# Install the cbt CLI tool
gcloud components install cbt

# Configure cbt defaults
echo "project = MY_PROJECT" > ~/.cbtrc
echo "instance = my-bigtable-dev" >> ~/.cbtrc

# Create a table with column families
cbt createtable events
cbt createfamily events data
cbt createfamily events metadata

# Set garbage collection policy (keep last 3 versions)
cbt setgcpolicy events data maxversions=3
cbt setgcpolicy events metadata maxage=30d

# Write data to a row
cbt set events "device01#2026-03-14T10:30:00" \
  data:temperature=72.5 \
  data:humidity=45.2 \
  metadata:device_type=sensor \
  metadata:location=building-a

# Read a single row
cbt read events prefix="device01#2026-03-14"

# Read a range of rows
cbt read events \
  start="device01#2026-03-14T00:00:00" \
  end="device01#2026-03-14T23:59:59"

# Count rows in a table
cbt count events

# List all tables
cbt ls

# Delete a row
cbt deleterow events "device01#2026-03-14T10:30:00"

# Drop a table
cbt deletetable events

import hashlib
import struct
import time

# Pattern 1: Time-series with entity prefix (most common)
def time_series_key(device_id: str, timestamp: float) -> str:
    """Good for per-device queries over time ranges."""
    ts_str = f"{timestamp:.6f}"
    return f"{device_id}#{ts_str}"

# Pattern 2: Reverse timestamp for latest-first queries
MAX_TIMESTAMP = 9999999999.0

def reverse_time_key(device_id: str, timestamp: float) -> str:
    """Returns latest entries first in a scan."""
    reversed_ts = MAX_TIMESTAMP - timestamp
    return f"{device_id}#{reversed_ts:.6f}"

# Pattern 3: Hashed prefix for write distribution
def hashed_key(entity_id: str, timestamp: float) -> str:
    """Distributes writes evenly across tablets."""
    hash_prefix = hashlib.md5(entity_id.encode()).hexdigest()[:4]
    return f"{hash_prefix}#{entity_id}#{timestamp:.6f}"

# Pattern 4: Salted key with fixed number of buckets
NUM_BUCKETS = 10

def salted_key(entity_id: str, timestamp: float) -> str:
    """Fixed number of salt buckets for predictable scatter-gather."""
    bucket = hash(entity_id) % NUM_BUCKETS
    return f"{bucket:02d}#{entity_id}#{timestamp:.6f}"

# Scale nodes up (takes effect within minutes)
gcloud bigtable clusters update cluster-us-central \
  --instance=my-bigtable-prod \
  --num-nodes=5

# Enable autoscaling
gcloud bigtable clusters update cluster-us-central \
  --instance=my-bigtable-prod \
  --autoscaling-min-nodes=3 \
  --autoscaling-max-nodes=10 \
  --autoscaling-cpu-target=60 \
  --autoscaling-storage-target=2560

# Monitor key metrics via gcloud
gcloud bigtable instances describe my-bigtable-prod

# Run the official load test tool
# Install: go install cloud.google.com/go/bigtable/cmd/loadtest@latest
# loadtest -project MY_PROJECT -instance my-bigtable-dev -table loadtest

# Add a replication cluster to an existing instance
gcloud bigtable clusters create cluster-europe \
  --instance=my-bigtable-prod \
  --zone=europe-west1-b \
  --num-nodes=3 \
  --storage-type=SSD

# Create an app profile for multi-cluster routing
gcloud bigtable app-profiles create multi-cluster-profile \
  --instance=my-bigtable-prod \
  --route-any \
  --force

# Create an app profile for single-cluster routing (strong consistency)
gcloud bigtable app-profiles create single-cluster-profile \
  --instance=my-bigtable-prod \
  --route-to=cluster-us-central \
  --force

# List app profiles
gcloud bigtable app-profiles list --instance=my-bigtable-prod

# Check replication status
gcloud bigtable clusters list --instance=my-bigtable-prod

from google.cloud import bigtable
from google.cloud.bigtable import column_family, row_filters
import datetime

# Create a client and connect to the instance
client = bigtable.Client(project="MY_PROJECT", admin=True)
instance = client.instance("my-bigtable-dev")
table = instance.table("events")

# Write a batch of rows
rows = []
for i in range(100):
    ts = datetime.datetime.now(datetime.timezone.utc)
    row_key = f"sensor-01#{ts.isoformat()}#{i:04d}".encode()
    row = table.direct_row(row_key)
    row.set_cell("data", "temperature", str(72.5 + i * 0.1), timestamp=ts)
    row.set_cell("data", "humidity", str(45.0 + i * 0.05), timestamp=ts)
    row.set_cell("metadata", "source", "prod-pipeline", timestamp=ts)
    rows.append(row)

# Mutate rows in batch (max 100K mutations per batch)
response = table.mutate_rows(rows)
for i, status in enumerate(response):
    if status.code != 0:
        print(f"Row {i} failed: {status.message}")

# Read a range of rows with filters
partial_rows = table.read_rows(
    start_key=b"sensor-01#2026-03-14",
    end_key=b"sensor-01#2026-03-15",
    filter_=row_filters.ColumnRangeFilter(
        "data", start_column=b"temperature", end_column=b"temperature"
    ),
    limit=50
)
for row in partial_rows:
    print(row.row_key.decode(), row.cells["data"][b"temperature"][0].value.decode())

# Delete the development instance
gcloud bigtable instances delete my-bigtable-dev --quiet

# Delete the production instance (deletes all clusters and data)
gcloud bigtable instances delete my-bigtable-prod --quiet