Managing tables

This page explains how to create, modify, delete, and get information about Cloud Bigtable tables using the cbt command-line tool or the Google Cloud 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 Bigtable client libraries or service APIs.

Before you begin

If you want to manage tables from the command line, install the cbt tool.

Configuring the cbt tool

You can specify defaults for the following cbt tool configuration settings:

  • The project where your Bigtable instance is located.
  • The 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

The cbt tool 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, you do not need to specify the column families to use in the table. You can add or delete column families later.

Console

To create a new table in an instance:

  1. Open the list of 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.

  4. Click Create a table.

  5. Enter a table ID for the table.

  6. Add column families (optional).

    You can add columns now or later. A table must have at least one column family before you can write data to it.

  7. Click Create.

cbt

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 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 using the cbt tool or a Bigtable client library, 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 Bigtable information about where the load and data footprint are likely to land when the table is created. The pre-split prevents 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. 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.

Console

You are not able to pre-split the rows when you create a table using the Google Cloud Console.

cbt

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 add or delete column families in an existing table.

Adding column families

Console

  1. Open the list of 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.

  4. Click for the table that you want to modify.

  5. For each column family that you want to add, complete the following:

    1. Click Add column family.
    2. Provide a unique identifier for the column family.
    3. Set the garbage collection policy for the column family.
    4. Click Done.
  6. Click Save.

cbt

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

Console

  1. Open the list of 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.

  4. Click for the table that you want to modify.

  5. For each column family that you want to delete, complete the following:

    1. Mouse over the row for the column family that you want to delete.
    2. Click .
  6. Click Save.

  7. To confirm that you understand that deleting a column family is permanent and that all data in the column family will be deleted, type "Delete column families" in the text box.

  8. Click Confirm.

cbt

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 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

Console

To view information about a table:

  1. Open the list of 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. For each table, the Cloud Console displays the number of clusters that the table is stored on, the table's status, storage utilization, and the identifiers for any current backups of the table.

  4. To view column family names for the table, click .

  5. To close the Edit table pane, click Cancel.

cbt

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

Use the following command, replacing [TABLE_NAME] with the table name:

cbt ls [TABLE_NAME]

Setting garbage collection policies

A garbage collection policy tells Bigtable which data to keep and which data to mark for deletion. Garbage collection policies are set at the column family level. You can set them when you create the table or later. This page describes how to set garbage collection policies using the cbt tool or the Cloud Console. You can also set garbage-collection policies programmatically when you use a Bigtable client library.

Garbage collection policies specify whether to let data expire based on age, maxage, or the number of cells in the column, maxversions.

Retaining multiple versions of each value

When you create a column family, you can specify the number of cells that you want to retain in every column in that column family. If you do not specify this setting, Bigtable uses one of the following default settings:

  • If you create the column family with the Cloud Bigtable HBase client for Java or the HBase shell, or another tool that uses the HBase client for Java, Bigtable retains only 1 cell for each row/column intersection in the column family. This default setting is consistent with HBase.

  • If you create the column family the Cloud Console, any other client library or the cbt tool, Bigtable retains an infinite number of cells in each column.

Console

To set the number of cells, or versions, to retain in a column family:

  1. Open the list of 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.

  4. Click .

  5. Expand the row for the column family that you want to set a garbage collection policy for.

  6. Select Version based policy.

  7. Enter the number of cells that you want to retain.

  8. Click Save.

cbt

To change the number of cells that are retained for each column in 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 cells 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.

Console

To set an expiration time for cells in a column family:

  1. Open the list of 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.

  4. Click .

  5. Expand the row for the column family that you want to set a garbage collection policy for.

  6. Select Age based policy.

  7. Enter the age by entering a number in the Max age text box and using the Unit dropdown to select the unit of time.

    For example, to retain a column family's data for 30 minutes, enter 30 and choose minutes.

  8. Click Save.

cbt

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 [NUMBER] with the number and [UNIT]. Acceptable units are ms, s, m, h, and d, which stand for milliseconds, seconds, minutes, hours, and days.

cbt setgcpolicy [TABLE_NAME] [FAMILY_NAME] maxage=[NUMBER][UNIT]

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

cbt setgcpolicy my-table cf1 maxage=1d

Backing up and restoring a table

See Managing backups for instructions on how to back up a table and restore from a backup to a new table.

Deleting a table

Console

  1. Open the list of 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.

  4. Click for the table that you want to delete.

  5. Click Delete.

  6. To confirm that you acknowledge that this action cannot be undone and will delete the table from all clusters in the instance, type the table ID in the text box.

  7. Click Delete.

cbt

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

cbt deletetable [TABLE_NAME]