Managing tables

This page explains how to use the cbt command-line tool to create, modify, and delete tables and how to get information about existing tables by using either the cbt tool or the Google Cloud Console.

Note: You can perform Cloud Bigtable operations at the command line using either the HBase shell or the cbt tool. Use the HBase shell if you are accustomed to it and prefer to use it. Otherwise, we recommend that you use the cbt tool, which has fewer dependencies and installation steps. The cbt tool is a component of Google Cloud SDK.

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.

Before you begin

Before you begin, 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 do 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

Note: For information about setting other values in .cbtrc, run the command cbt help.

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

One feature of Cloud Bigtable as a fully managed service is the automatic splitting of tables across multiple nodes. This feature optimizes performance by evenly distributing the amount of data stored on each node and keeping frequently accessed rows spread apart, where possible.

When you create a table, you can choose row keys to pre-split the table. For example, you might designate specific rows to pre-split the table if you are about to write many rows to your table. Pre-splitting your table is not essential, but it is beneficial because it provides Cloud Bigtable information about where the load and data footprint are likely to land when the table is created. The pre-split prevents Cloud Bigtable from having to split the tables and rebalance the load all at once as the data arrives.

The table does not remain split on the row keys you choose to pre-split on when you create the table. Cloud Bigtable eventually splits 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. Replace [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

Warning: When you delete a column family, you also delete the data stored in that column family. Deleting a column family cannot be undone.

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

Console

To view a list of tables in an instance:

1. Open the list of Cloud Bigtable instances in the Cloud Console.

   Open the instance list

2. Click the instance whose tables you want to view.

3. Click Tables in the left pane.

   The Tables page displays a list of tables in the instance.

   • Click the arrow next to the table ID to expand a list of replications of the table.
   • Click View Metrics next to a table name to view monitoring data for the table.

cbt

To view a list of tables in an instance, run 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

This section explains how to use the cbt tool to control how many versions of each value Cloud Bigtable retains and how to provide an expiration time for values. You can also set garbage-collection policies programmatically when you use a Cloud Bigtable client library.

Note: You can read obsolete and expired values until Cloud Bigtable completes garbage collection for the table. This process typically takes up to a week. Therefore, you should always use filters when you read data that is subject to garbage collection.

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 never expire.

To cause values to expire after a specified amount of time, use the following command. Replace [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 removed after one day:

cbt setgcpolicy my-table cf1 maxage=1d

Note: The removal of expired values happens opportunistically in the background, so you might still be able to read the data for several days after it has expired.

Backing up and restoring a table

Cloud Bigtable lets you create a backup of a table and assign it a TTL of up to 30 days. You can restore a backup to a new table in the instance where the backup was created. See Managing backups for instructions on how to back up and restore a table.

Deleting a table

Warning: When you delete a table, you also delete the data stored in that table. Deleting a table cannot be undone.

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

cbt deletetable [TABLE_NAME]