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 to get information about existing tables.

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

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]

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

cbt createtable my-table 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

You can use the cbt tool to get a list of tables in your instance.

To view a list of tables, use the following command:

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

By default, tables have garbage collection configured to retain only one version of each value that you store within the column family. To retain multiple versions of each value, 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

By default, each value that you store in a column family never expires. To cause values to be deleted 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]

Send feedback about...

Cloud Bigtable Documentation