Example: Python "Hello World" Application

This example is a very simple "hello world" application, written in Python, that illustrates how to:

  • Connect to a Cloud Bigtable instance.
  • Create a new table.
  • Write data to the table.
  • Read the data back.
  • Delete the table.

Running the sample

This example uses the Cloud Bigtable package of the Google Cloud Client Library for Python to communicate with Cloud Bigtable. The Cloud Bigtable package is the best choice for new applications. If you need to move an existing HBase workload to Cloud Bigtable, see the "hello world" example that uses the HappyBase package.

To run this sample program, follow the instructions for the sample on GitHub.

Using the Cloud Client Library with Cloud Bigtable

The sample application connects to Cloud Bigtable and demonstrates some simple operations.

Installing and importing the client library

Use PIP to install the required Python packages into a virtualenv environment. The sample includes a requirements file defining the needed packages.

samples/hello/requirements.txt 
google-cloud-bigtable==1.2.1
google-cloud-core==1.3.0

Import the modules.

samples/hello/main.py 
import datetime

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

Connecting to Cloud Bigtable

Connect to Cloud Bigtable using a bigtable.Client.

samples/hello/main.py 
# The client must be created with admin=True because it will create a
# table.
client = bigtable.Client(project=project_id, admin=True)
instance = client.instance(instance_id)

Creating a table

Instantiate a table object using Instance.table(). Create a column family and set its garbage-collection policy, then pass the column family to Table.create() to create the table.

samples/hello/main.py 
print('Creating the {} table.'.format(table_id))
table = instance.table(table_id)

print('Creating column family cf1 with Max Version GC rule...')
# Create a column family with GC policy : most recent N versions
# Define the GC policy to retain only the most recent 2 versions
max_versions_rule = column_family.MaxVersionsGCRule(2)
column_family_id = 'cf1'
column_families = {column_family_id: max_versions_rule}
if not table.exists():
    table.create(column_families=column_families)
else:
    print("Table {} already exists.".format(table_id))

Writing rows to a table

Loop through a list of greeting strings to create some new rows for the table. In each iteration, use Table.row() to define a row and assign it a row key; call Row.set_cell() to set a value for the current cell; and append the new row to an array of rows. Finally, call Table.mutate_rows() to add the rows to the table.

samples/hello/main.py 
print('Writing some greetings to the table.')
greetings = ['Hello World!', 'Hello Cloud Bigtable!', 'Hello Python!']
rows = []
column = 'greeting'.encode()
for i, value in enumerate(greetings):
    # Note: This example uses sequential numeric IDs for simplicity,
    # but this can result in poor performance in a production
    # application.  Since rows are stored in sorted order by key,
    # sequential keys can result in poor distribution of operations
    # across nodes.
    #
    # For more information about how to design a Bigtable schema for
    # the best performance, see the documentation:
    #
    #     https://cloud.google.com/bigtable/docs/schema-design
    row_key = 'greeting{}'.format(i).encode()
    row = table.direct_row(row_key)
    row.set_cell(column_family_id,
                 column,
                 value,
                 timestamp=datetime.datetime.utcnow())
    rows.append(row)
table.mutate_rows(rows)

Creating a filter

Before you read the data that you wrote, create a filter using row_filters.CellsColumnLimitFilter() to limit the data that Cloud Bigtable returns. This filter tells Cloud Bigtable to return only the most recent version of each value, even if the table contains older versions that haven't been garbage-collected.

samples/hello/main.py 
row_filter = row_filters.CellsColumnLimitFilter(1)

Reading a row by its key

Call the table's Table.read_row() method to get a reference to the row with a specific row key, passing in the key and the filter, to get one version of each value in that row.

samples/hello/main.py 
print('Getting a single greeting by row key.')
key = 'greeting0'.encode()

row = table.read_row(key, row_filter)
cell = row.cells[column_family_id][column][0]
print(cell.value.decode('utf-8'))

Scanning all table rows

Use Table.read_rows() to read a range of rows from a table.

samples/hello/main.py 
print('Scanning for all greetings:')
partial_rows = table.read_rows(filter_=row_filter)

for row in partial_rows:
    cell = row.cells[column_family_id][column][0]
    print(cell.value.decode('utf-8'))

Deleting a table

Delete a table with Table.delete().

samples/hello/main.py 
print('Deleting the {} table.'.format(table_id))
table.delete()

Putting it all together

Here is the full example without comments.

samples/hello/main.py 


"""Demonstrates how to connect to Cloud Bigtable and run some basic operations.

Prerequisites:

- Create a Cloud Bigtable cluster.
  https://cloud.google.com/bigtable/docs/creating-cluster
- Set your Google Application Default Credentials.
  https://developers.google.com/identity/protocols/application-default-credentials
"""

import argparse
import datetime

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


def main(project_id, instance_id, table_id):
    client = bigtable.Client(project=project_id, admin=True)
    instance = client.instance(instance_id)

    print('Creating the {} table.'.format(table_id))
    table = instance.table(table_id)

    print('Creating column family cf1 with Max Version GC rule...')
    max_versions_rule = column_family.MaxVersionsGCRule(2)
    column_family_id = 'cf1'
    column_families = {column_family_id: max_versions_rule}
    if not table.exists():
        table.create(column_families=column_families)
    else:
        print("Table {} already exists.".format(table_id))

    print('Writing some greetings to the table.')
    greetings = ['Hello World!', 'Hello Cloud Bigtable!', 'Hello Python!']
    rows = []
    column = 'greeting'.encode()
    for i, value in enumerate(greetings):
        row_key = 'greeting{}'.format(i).encode()
        row = table.direct_row(row_key)
        row.set_cell(column_family_id,
                     column,
                     value,
                     timestamp=datetime.datetime.utcnow())
        rows.append(row)
    table.mutate_rows(rows)

    row_filter = row_filters.CellsColumnLimitFilter(1)

    print('Getting a single greeting by row key.')
    key = 'greeting0'.encode()

    row = table.read_row(key, row_filter)
    cell = row.cells[column_family_id][column][0]
    print(cell.value.decode('utf-8'))

    print('Scanning for all greetings:')
    partial_rows = table.read_rows(filter_=row_filter)

    for row in partial_rows:
        cell = row.cells[column_family_id][column][0]
        print(cell.value.decode('utf-8'))

    print('Deleting the {} table.'.format(table_id))
    table.delete()


if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.ArgumentDefaultsHelpFormatter)
    parser.add_argument('project_id', help='Your Cloud Platform project ID.')
    parser.add_argument(
        'instance_id', help='ID of the Cloud Bigtable instance to connect to.')
    parser.add_argument(
        '--table',
        help='Table to create and destroy.',
        default='Hello-Bigtable')

    args = parser.parse_args()
    main(args.project_id, args.instance_id, args.table)