Managing Tables

The easiest way to manage your Cloud Bigtable tables is to use the cbt command-line tool. This page explains how to use cbt to create, modify, and delete tables and how to get information about existing tables with cbt or the Google Cloud Platform Console.

The cbt tool supports several commands that are not described on this page. See the cbt reference for a complete list of commands.

You can also manage tables programmatically with one of the Cloud Bigtable client libraries or service APIs, or you can manage tables with the HBase shell command-line tool. See the HBase documentation for instructions on how to use the HBase shell.

Before you begin

Before you begin, you'll need to install the cbt tool.

Configuring the cbt tool

You can specify defaults for the following cbt configuration settings:

• The project where your Cloud Bigtable instance is located.
• The Cloud Bigtable instance to connect to.
• The credentials file, in JSON format, to use when connecting to your instance. See the instructions for creating a service account key. If you have authenticated by running gcloud auth application-default login, or if you are using the cbt tool on a Compute Engine instance, you do not need a credentials file.
• The API endpoints to use. You will not normally need to change these values.

To specify defaults for these settings, create a .cbtrc file in your home directory. You can override the default values in .cbtrc by using command-line flags.

To create a .cbtrc file, run the following command, replacing [PROJECT_ID] and [INSTANCE_ID] with the appropriate values:

echo -e "project = [PROJECT_ID]\ninstance = [INSTANCE_ID]" > ~/.cbtrc

For simplicity, the rest of the instructions on this page assume that you have set the project ID and instance ID in your .cbtrc file. You can also use the -project and -instance flags to set these values each time you run cbt.

Creating a table

When you create a table with the cbt tool, you do not need to specify the column families to use in the table. You can add or delete column families later.

To create a table, use the following command, replacing [TABLE_NAME] with the name of your table:

cbt createtable [TABLE_NAME]

Splitting the table by row key

When you create a table, you can pre-split the table based on the row key to spread the load across multiple Cloud Bigtable nodes. For example, you might pre-split the table if you are about to write a very large number of rows to your table.

In general, pre-splitting your table is not essential, because Cloud Bigtable automatically splits the table as necessary behind the scenes. Also, keep in mind that Cloud Bigtable will eventually split your table on different row keys, based on how much data is in the table and how frequently each row is accessed.

To pre-split a table based on the row key, use the following syntax to create the table, replacing [TABLE_NAME] with the table name and [SPLITS] with a comma-separated list of row-key prefixes to use for the pre-splits:

cbt createtable [TABLE_NAME] splits=[SPLITS]

For example, to pre-split the table my-table at row keys that begin with 10 and 20:

cbt createtable my-table splits=10,20

Modifying column families in a table

You can use the cbt tool to add or delete column families in an existing table.

Adding column families

To add a column family to a table, use the following command, replacing [TABLE_NAME] with the table name and [FAMILY_NAME] with the column family name:

cbt createfamily [TABLE_NAME] [FAMILY_NAME]

For example, to add the column families cf1 and cf2 to the table my-table:

cbt createfamily my-table cf1
cbt createfamily my-table cf2

Deleting column families

To delete a column family from a table, use the following command, replacing [TABLE_NAME] with the table name and [FAMILY_NAME] with the column family name:

cbt deletefamily [TABLE_NAME] [FAMILY_NAME]

For example, to delete the column family cf2 from the table my-table:

cbt deletefamily my-table cf2

Viewing a list of tables

cbt ls

Viewing information about a table

You can use the cbt tool to get a list of existing column families in a table.

To view a table's column families, use the following command, replacing [TABLE_NAME] with the table name:

cbt ls [TABLE_NAME]

Setting garbage collection policies

You can use the cbt tool to control how many versions of each value are retained, as well as an expiration time for values.

Retaining multiple versions of each value

When you create a column family, you can specify how many versions of each value you want to retain in that column family. If you do not specify this setting, Cloud Bigtable uses one of the following default settings:

• If you create the column family with the HBase client for Java or the HBase shell, or another tool that uses the HBase client for Java, Cloud Bigtable retains only 1 version of each value in the column family. This default setting is consistent with HBase.
• If you create the column family with any other client library or tool, including cbt, Cloud Bigtable retains an infinite number of versions of each value.

To change the number of versions that are retained within a column family, use the following command, replacing [TABLE_NAME] with the table name, [FAMILY_NAME] with the column family name, and [VERSIONS] with the number of versions to retain:

cbt setgcpolicy [TABLE_NAME] [FAMILY_NAME] maxversions=[VERSIONS]

For example, to update the column family cf1 in the table my-table so that it retains five versions of each value:

cbt setgcpolicy my-table cf1 maxversions=5

Setting an expiration time for values

When you create a column family, you can specify when each value in that column family should expire. If you do not specify this setting, then values in the column family will never expire.

To cause values to expire after a specified amount of time, use the following command, replacing [TABLE_NAME] with the table name, [FAMILY_NAME] with the column family name, and [DAYS] with the number of days to retain each value:

cbt setgcpolicy [TABLE_NAME] [FAMILY_NAME] maxage=[DAYS]d

For example, to cause values in the column family cf1 to be deleted after one day:

cbt setgcpolicy my-table cf1 maxage=1d

Deleting a table

To delete a table, use the following command, replacing [TABLE_NAME] with the table name:

cbt deletetable [TABLE_NAME]