Managing Tables

The easiest way to manage your Cloud Bigtable tables is to use the Apache HBase shell. This page explains how to use the HBase shell to create, modify, and delete tables, and to get information about existing tables.

Before you start

Before you start, you'll need to install the HBase shell for Cloud Bigtable, which includes the Cloud Bigtable HBase client and supporting files.

Running the HBase shell

To run the HBase shell, change to the hbase-1.2.1 directory in your terminal, then run the following command:

$ ./bin/hbase shell

The shell prompt appears:

hbase(main):001:0>

While the HBase shell is running, you can type help to get usage instructions. See the HBase documentation for additional information. Keep in mind that Cloud Bigtable handles many administrative functions automatically, so some commands and options are not supported.

Creating a table

When you create a table in the HBase shell, you must also specify the column families that the table will use. You can add or delete column families later.

To create a table, use the following command:

create 'TABLE_NAME', 'COLUMN_FAMILY_1', 'COLUMN_FAMILY_2', ... 'COLUMN_FAMILY_N'

For example, to create a table named my-table with two column families named cf1 and cf2:

create 'my-table', 'cf1', 'cf2'

The following sections describe additional options you can use with the create command. You can combine multiple options into a single command.

Retaining multiple versions of each value

By default, tables created with the HBase shell will 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 syntax:

create 'TABLE_NAME', {NAME => 'COLUMN_FAMILY_NAME', VERSIONS => 'N'}

For example, to create a table named my-table with two column families named cf1 and cf2, each of which retains five versions of each value:

create 'my-table', {NAME => 'cf1', VERSIONS => '5'}, {NAME => 'cf2', VERSIONS => '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 syntax, where 'N' is the number of seconds that a value will be stored before it is deleted:

create 'TABLE_NAME', {NAME => 'COLUMN_FAMILY_NAME', TTL => 'N'}

Note that the deletion happens opportunistically in the background, so you might still be able to read the data for several days after it has expired.

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

create 'my-table', {NAME => 'cf1', TTL => '86400'}

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 use this option if you are about to write a very large number of rows to your table. Using this option is not essential, because Cloud Bigtable automatically splits your tables 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:

create 'TABLE_NAME', 'COLUMN_FAMILY_NAMES', SPLITS => ['PREFIX_1', 'PREFIX_2', ... 'PREFIX_N']

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

create 'my-table', 'cf1', SPLITS => ['10', '20']

Viewing information about a table

The HBase shell's describe command shows details about each column family in an existing table. Because Cloud Bigtable manages tables automatically, you can ignore all of these details other than the following fields:

  • NAME: The column family's name.
  • TTL: The time to live, in seconds, for values stored in the column family. Values are deleted after this time. The value FOREVER prevents values from expiring.
  • VERSIONS: The number of versions that the column family retains for each value.

To view information about a table, use the following command:

describe 'TABLE_NAME'

The describe command displays information similar to the following. In this example, the table my-table has two columns, cf1 and cf2, each of which retains five versions of each value:

Table my-table is ENABLED
my-table
COLUMN FAMILIES DESCRIPTION
{NAME => 'cf1', DATA_BLOCK_ENCODING => 'NONE', BLOOMFILTER => 'ROW', REPLICATION_SCOPE => '0',
COMPRESSION => 'NONE', VERSIONS => '5', TTL => 'FOREVER', MIN_VERSIONS => '0',
KEEP_DELETED_CELLS => 'FALSE', BLOCKSIZE => '65536', IN_MEMORY => 'false', BLOCKCACHE => 'true'}
{NAME => 'cf2', DATA_BLOCK_ENCODING => 'NONE', BLOOMFILTER => 'ROW', REPLICATION_SCOPE => '0',
COMPRESSION => 'NONE', VERSIONS => '5', TTL => 'FOREVER', MIN_VERSIONS => '0',
KEEP_DELETED_CELLS => 'FALSE', BLOCKSIZE => '65536', IN_MEMORY => 'false', BLOCKCACHE => 'true'}

Modifying column families in a table

The HBase shell's alter command allows you to add or delete column families in an existing table. You can also modify the number of versions of each value that a column family retains.

Adding column families

To add a column family to a table, use the following command:

alter 'TABLE_NAME', 'NEW_COLUMN_FAMILY_1'[, 'NEW_COLUMN_FAMILY_2', ... 'NEW_COLUMN_FAMILY_N']

For example, to add two column families, cf3 and cf4, to the table my-table:

alter 'my-table', 'cf3', 'cf4'

By default, column families created with the HBase shell will 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 syntax:

alter 'TABLE_NAME', {NAME => 'NEW_COLUMN_FAMILY_NAME', VERSIONS => 'N'}

For example, to update the table my-table by adding two column families, cf3 and cf4, each of which retains five versions of each value:

alter 'TABLE_NAME', {NAME => 'cf3', VERSIONS => '5'}, {NAME => 'cf4', VERSIONS => '5'}

Deleting column families

To delete a column family from a table, use the following command:

alter 'TABLE_NAME', {NAME => 'COLUMN_FAMILY_NAME', METHOD => 'delete'}

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

alter 'my-table', {NAME => 'cf3', METHOD => 'delete'}

Modifying the number of versions

To modify the number of versions of each value that a column family stores, use the following command:

alter 'TABLE_NAME', {NAME => 'COLUMN_FAMILY_NAME', VERSIONS => 'N'}

For example, to update the table my-table so that the column family cf1 stores up to three versions of each value:

alter 'my-table', {NAME => 'cf1', VERSIONS => '3'}

Setting an expiration time for values

To cause values to be deleted a specified amount of time after they are stored, use the following command, where 'N' is the number of seconds that a value will be stored before it is deleted:

alter 'TABLE_NAME', {NAME => 'COLUMN_FAMILY_NAME', TTL => 'N'}

For example, to update the table my-table so that values stored in the column family cf1 are deleted after one day:

alter 'my-table', {NAME => 'cf1', TTL => '86400'}

To prevent values from expiring, use the value FOREVER. For example, to prevent values in the column family cf1 from expiring:

alter 'my-table', {NAME => 'cf1', TTL => 'FOREVER'}

Deleting a table

Deleting a table is a two-step process. First, use the HBase shell's disable command to disable the table. Then use the drop command to drop the table.

To delete a table, use the following commands:

disable 'TABLE_NAME'
drop 'TABLE_NAME'

Exiting the HBase shell

To exit the HBase shell, type exit and press Enter.

Send feedback about...

Cloud Bigtable Documentation