Google Cloud Bigtable Python Client Library

2.35.0 · active · verified Sat Mar 28

The `google-cloud-bigtable` library is the official Python client for Google Cloud Bigtable, a fully managed, scalable NoSQL database service designed for high-performance and low-latency applications. It powers many core Google services like Search, Analytics, Maps, and Gmail. Currently at version 2.35.0, the library is actively maintained with frequent updates, adding new features and ensuring compatibility with the Bigtable service.

Warnings

breaking Python versions older than 3.7 are no longer supported by recent `google-cloud-bigtable` releases. Python 3.6 support ended with v2.10.1 (2022-06-03), and Python 2.7/3.5 support ended with v1.7.0 (2021-02-09).
Fix: Upgrade your Python environment to 3.7 or newer to use current versions of the library.
gotcha The `BigtableDataClientAsync` client (introduced in v2.23.0) is designed for `asyncio` codebases. It is generally not recommended to use the async client within an otherwise synchronous application, as it can negate performance benefits and lead to unexpected behavior.
Fix: Design your application to be fully asynchronous from the ground up to leverage the `BigtableDataClientAsync` client, or stick to the synchronous `Client` for synchronous codebases.
gotcha Suboptimal performance can occur if your Bigtable client application is not running in the same Google Cloud zone as your Bigtable cluster, or if your Bigtable schema is poorly designed, leading to hot-spotting or inefficient reads/writes.
Fix: Deploy your client applications in the same zone as your Bigtable instance. Follow Bigtable schema design best practices to distribute reads and writes evenly across your table.
gotcha The `table.read_row()` method returns `None` if a row with the specified key does not exist. Cell values are returned as bytes and require explicit decoding (e.g., `.decode("utf-8")`) for string representation.
Fix: Always check for `None` when reading a row: `if read_row: ...`. Remember to decode byte values to strings or other appropriate types when processing data.
gotcha For new projects, prefer using the native `google-cloud-bigtable` client directly over wrapper libraries like `google-cloud-happybase` (which mimics the Apache HBase API). The native client provides more direct access to Bigtable features and better performance due to avoiding object conversion overhead.
Fix: Utilize `from google.cloud import bigtable` and its API directly for optimal performance and access to the latest Bigtable features, unless strict Apache HBase API compatibility is a requirement.

Install

pip install google-cloud-bigtable Install stable version

Imports

Client
```
from google.cloud import bigtable
```
BigtableDataClientAsync
```
from google.cloud.bigtable.data import BigtableDataClientAsync
```
Introduced in v2.23.0 for asyncio-based applications; generally not recommended for synchronous codebases.

Quickstart

This quickstart demonstrates how to initialize the `google-cloud-bigtable` client, create a table (if it doesn't exist), write a simple row, and then read that row back. Ensure your `GOOGLE_CLOUD_PROJECT` and `BIGTABLE_INSTANCE_ID` environment variables are set, and you have authenticated to Google Cloud (e.g., via `gcloud auth application-default login`) with appropriate permissions to manage and access Bigtable.

import os
from google.cloud import bigtable
from google.cloud.bigtable import row
from google.cloud.bigtable import column_family

# Configuration
PROJECT_ID = os.environ.get("GOOGLE_CLOUD_PROJECT", "your-gcp-project-id") # e.g., "my-project-123"
INSTANCE_ID = os.environ.get("BIGTABLE_INSTANCE_ID", "your-bigtable-instance-id") # e.g., "my-instance"
TABLE_ID = os.environ.get("BIGTABLE_TABLE_ID", "your-table-id") # e.g., "my-table"
COLUMN_FAMILY_ID = "cf1"
COLUMN_QUALIFIER = "greeting"
ROW_KEY = "r1"

# Initialize Bigtable client
# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set for local dev
# or gcloud auth application-default login has been run.
# Use admin=True if you need to create/manage tables/instances.
client = bigtable.Client(project=PROJECT_ID, admin=True)
instance = client.instance(INSTANCE_ID)

# Check if table exists, create if not
table = instance.table(TABLE_ID)
if not table.exists():
    print(f"Creating table {TABLE_ID}...")
    table.create(column_families={COLUMN_FAMILY_ID: column_family.ColumnFamily()})
    print(f"Table {TABLE_ID} created.")
else:
    print(f"Table {TABLE_ID} already exists.")

# Write a row
print(f"Writing row '{ROW_KEY}'...")
row_entry = row.DirectRow(ROW_KEY.encode("utf-8"))
row_entry.set_cell(COLUMN_FAMILY_ID, COLUMN_QUALIFIER.encode("utf-8"),
                   b"Hello Bigtable!", timestamp=client.timestamp())
table.mutate_rows([row_entry])
print(f"Row '{ROW_KEY}' written.")

# Read a row
print(f"Reading row '{ROW_KEY}'...")
read_row = table.read_row(ROW_KEY.encode("utf-8"))

if read_row:
    # Get the latest cell value for the specific column
    cells = read_row.cells[COLUMN_FAMILY_ID][COLUMN_QUALIFIER.encode("utf-8")]
    latest_value = cells[0].value.decode("utf-8")
    timestamp = cells[0].timestamp
    print(f"Read: {COLUMN_FAMILY_ID}:{COLUMN_QUALIFIER} = '{latest_value}' (at {timestamp})")
else:
    print(f"Row '{ROW_KEY}' not found.")

# Optional: Delete the table for cleanup
# print(f"Deleting table {TABLE_ID}...")
# table.delete()
# print(f"Table {TABLE_ID} deleted.")

view raw JSON →