cbt CLI reference

The cbt CLI is a command-line interface that lets you interact with Bigtable. See the cbt CLI overview to learn how to install the cbt CLI. Before you use the cbt CLI, you should be familiar with the Bigtable overview.

The examples on this page use sample data similar to data that you might store in Bigtable.

Usage:

cbt [-<option> <option-argument>] <command> <required-argument> [optional-argument]

The commands are:

addtocell                 Add a value to an aggregate cell (write)
count                     Count rows in a table
createappprofile          Create app profile for an instance
createcluster             Create a cluster in the configured instance
createfamily              Create a column family
createinstance            Create an instance with an initial cluster
createtable               Create a table
deleteallrows             Delete all rows
deleteappprofile          Delete app profile for an instance
deletecluster             Delete a cluster from the configured instance
deletecolumn              Delete all cells in a column
deletefamily              Delete a column family
deleteinstance            Delete an instance
deleterow                 Delete a row
deletetable               Delete a table
doc                       Print godoc-suitable documentation for cbt
getappprofile             Read app profile for an instance
help                      Print help text
import                    Batch write many rows based on the input file
listappprofile            Lists app profile for an instance
listclusters              List clusters in an instance
listinstances             List instances in a project
lookup                    Read from a single row
ls                        List tables and column families
mddoc                     Print documentation for cbt in Markdown format
notices                   Display licence information for any third-party dependencies
read                      Read rows
set                       Set value of a cell (write)
checkandmutate            Set the value of a row if the filter matched any cell
readmodifywrite           Update a cell with incremental operations based on the latest value of the cell
setgcpolicy               Set the garbage-collection policy (age, versions) for a column family
setvaluetype              Update column family's value type.
updateappprofile          Update app profile for an instance
updatecluster             Update a cluster in the configured instance
version                   Print the current cbt version
waitforreplication        Block until all the completed writes have been replicated to all the clusters
samplerowkeys             Sample the row keys in a table
sql                       Execute a SQL query on an instance

The options are:

-project string
    project ID. If unset uses gcloud configured project
-instance string
    Cloud Bigtable instance
-creds string
    Path to the credentials file. If set, uses the application credentials in this file
-timeout string
    Timeout (e.g. 10s, 100ms, 5m )

Example: cbt -instance=my-instance ls

Use "cbt help <command>" for more information about a command.

Preview features are not available to most Bigtable customers, they might be changed in backward-incompatible ways and are not recommended for production use. They are not subject to any SLA or deprecation policy.

Syntax rules for the Bash shell apply to the cbt CLI. This means, for example, that you must put quotes around values that contain spaces or operators. It also means that if a value is arbitrary bytes, you need to prefix it with a dollar sign and use single quotes.

Example:

cbt -project my-project -instance my-instance lookup my-table $'\224\257\312W\365:\205d\333\2471\315\'

For convenience, you can add values for the -project, -instance, -creds, -admin-endpoint and -data-endpoint options to your ~/.cbtrc file in the following format:

project = my-project-123
instance = my-instance
creds = path-to-account-key.json
admin-endpoint = hostname:port
data-endpoint = hostname:port
auth-token = AJAvW039NO1nDcijk_J6_rFXG_...
timeout = 30s

All values are optional and can be overridden at the command prompt.

Add a value to an aggregate cell (write)

cbt addtocell <table-id> <row-key> [app-profile=<app-profile-id>] <family>:<column>=<val>[@<timestamp>] ...

  app-profile=<app profile id>          The app profile ID to use for the request
  <family>:<column>=<val>[@<timestamp>] may be repeated to set multiple cells.

    If <val> can be parsed as an integer it will be used as one, otherwise the call will fail.
    timestamp is an optional integer.
    If the timestamp cannot be parsed, '@<timestamp>' will be interpreted as part of the value.
    For most uses, a timestamp is the number of microseconds since 1970-01-01 00:00:00 UTC.

    Examples:
      cbt addtocell table1 user1 sum_cf:col1=1@12345

Count rows in a table

cbt count <table-id> [prefix=<row-key-prefix>] [app-profile=<app-profile-id>]

Create app profile for an instance

cbt createappprofile <instance-id> <app-profile-id> <description> (route-any | [ route-to=<cluster-id> : transactional-writes]) [-force]
  force:  Optional flag to override any warnings causing the command to fail

    Examples:
      cbt createappprofile my-instance multi-cluster-app-profile-1 "Routes to nearest available cluster" route-any
      cbt createappprofile my-instance single-cluster-app-profile-1 "Europe routing" route-to=my-instance-cluster-2

Create a cluster in the configured instance

cbt createcluster <cluster-id> <zone> <num-nodes> <storage-type>

  cluster-id       Permanent, unique ID for the cluster in the instance
  zone             The