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)
setgcpolicy Set the garbage-collection policy (age, versions) for a column family
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
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 all Bigtable customers, they might be changed in ways that are backward-incompatible, and we don't recommend them 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>]
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 zone in which to create the cluster
num-nodes The number of nodes to create
storage-type SSD or HDD
Example: cbt createcluster my-instance-c2 europe-west1-b 3 SSD
Create a column family
cbt createfamily <table-id> <family>
Example: cbt createfamily mobile-time-series stats_summary
Create an instance with an initial cluster
cbt createinstance <instance-id> <display-name> <cluster-id> <zone> <num-nodes> <storage-type>
instance-id Permanent, unique ID for the instance
display-name Description of the instance
cluster-id Permanent, unique ID for the cluster in the instance
zone The zone in which to create the cluster
num-nodes The number of nodes to create
storage-type SSD or HDD
Example: cbt createinstance my-instance "My instance" my-instance-c1 us-central1-b 3 SSD
Create a table
cbt createtable <table-id> [families=<family>:<gcpolicy-expression>:<type-expression>,...]
[splits=<split-row-key-1>,<split-row-key-2>,...]
families Column families and their associated garbage collection (gc) policies and types.
Put gc policies in quotes when they include shell operators && and ||. For gcpolicy,
see "setgcpolicy".
Types "intsum", "intmin", "intmax", and "inthll" are supported.
splits Row key(s) where the table should initially be split
Example: cbt createtable mobile-time-series "families=stats_summary:maxage=10d||maxversions=1,stats_detail:maxage=10d||maxversions=1" splits=tablet,phone
Delete all rows
cbt deleteallrows <table-id>
Example: cbt deleteallrows mobile-time-series
Delete app profile for an instance
cbt deleteappprofile <instance-id> <profile-id>
Example: cbt deleteappprofile my-instance single-cluster
Delete a cluster from the configured instance
cbt deletecluster <cluster-id>
Example: cbt deletecluster my-instance-c2
Delete all cells in a column
cbt deletecolumn <table-id> <row-key> <family> <column> [app-profile=<app-profile-id>]
app-profile=<app-profile-id> The app profile ID to use for the request
Example: cbt deletecolumn mobile-time-series phone#4c410523#20190501 stats_summary os_name
Delete a column family
cbt deletefamily <table-id> <family>
Example: cbt deletefamily mobile-time-series stats_summary
Delete an instance
cbt deleteinstance <instance-id>
Example: cbt deleteinstance my-instance
Delete a row
cbt deleterow <table-id> <row-key> [app-profile=<app-profile-id>]
app-profile=<app-profile-id> The app profile ID to use for the request
Example: cbt deleterow mobile-time-series phone#4c410523#20190501
Delete a table
cbt deletetable <table-id>
Example: cbt deletetable mobile-time-series
Print godoc-suitable documentation for cbt
cbt doc
Read app profile for an instance
cbt getappprofile <instance-id> <profile-id>
Print help text
cbt help <command>
Example: cbt help createtable
Batch write many rows based on the input file
cbt import <table-id> <input-file> [app-profile=<app-profile-id>] [column-family=<family-name>] [batch-size=<500>] [workers=<1>] [timestamp=<now|value-encoded>]
app-profile=<app-profile-id> The app profile ID to use for the request
column-family=<family-name> The column family label to use
batch-size=<500> The max number of rows per batch write request
workers=<1> The number of worker threads
timestamp=<now|value-encoded> Whether to use current time for all cells or interpret the timestamp from cell value. Defaults to 'now'.
Import data from a CSV file into an existing Cloud Bigtable table that already has the column families your data requires.
The CSV file can support two rows of headers:
- (Optional) column families
- Column qualifiers
Because the first column is reserved for row keys, leave it empty in the header rows.
In the column family header, provide each column family once; it applies to the column it is in and every column to the right until another column family is found.
Each row after the header rows should contain a row key in the first column, followed by the data cells for the row.
See the example. If you don't provide a column family header row, the column header is your first row and your import command must include the `column-family` flag to specify an existing column family.
The timestamp for each cell will default to current time (timestamp=now), to explicitly set the timestamp for cells, set timestamp=value-encoded use <val>[@<timestamp>] as the value for the cell.
If no timestamp is delimited for a cell, current time will be used. 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.
,column-family-1,,column-family-2, // Optional column family row (1st cell empty)
,column-1,column-2,column-3,column-4 // Column qualifiers row (1st cell empty)
a,TRUE,,,FALSE // Rowkey 'a' followed by data
b,,,TRUE,FALSE // Rowkey 'b' followed by data
c,,TRUE,,TRUE // Rowkey 'c' followed by data
d,TRUE@1577862000000000,,,FALSE // Rowkey 'd' followed by data
Examples:
cbt import csv-import-table data.csv
cbt import csv-import-table data-no-families.csv app-profile=batch-write-profile column-family=my-family workers=5
Lists app profile for an instance
cbt listappprofile <instance-id>
List clusters in an instance
cbt listclusters
List instances in a project
cbt listinstances
Read from a single row
cbt lookup <table-id> <row-key> [columns=<family>:<qualifier>,...] [cells-per-column=<n>] [app-profile=<app profile id>]
row-key String or raw bytes. Raw bytes must be enclosed in single quotes and have a dollar-sign prefix
columns=<family>:<qualifier>,... Read only these columns, comma-separated
cells-per-column=<n> Read only this number of cells per column
app-profile=<app-profile-id> The app profile ID to use for the request
format-file=<path-to-format-file> The path to a format-configuration file to use for the request
keys-only=<true|false> Whether to print only row keys
include-stats=full Include a summary of request stats at the end of the request
Example: cbt lookup mobile-time-series phone#4c410523#20190501 columns=stats_summary:os_build,os_name cells-per-column=1
Example: cbt lookup mobile-time-series $'\x41\x42'
List tables and column families
cbt ls List tables
cbt ls <table-id> List a table's column families and garbage collection policies
Example: cbt ls mobile-time-series
Print documentation for cbt in Markdown format
cbt mddoc
Display licence information for any third-party dependencies
cbt notices
Read rows
cbt read <table-id> [authorized-view=<authorized-view-id>] [start=<row-key>] [end=<row-key>] [prefix=<row-key-prefix>] [regex=<regex>] [columns=<family>:<qualifier>,...] [count=<n>] [cells-per-column=<n>] [app-profile=<app-profile-id>]
authorized-view=<authorized-view-id> Read from the specified authorized view of the table
start=<row-key> Start reading at this row
end=<row-key> Stop reading before this row
prefix=<row-key-prefix> Read rows with this prefix
regex=<regex> Read rows with keys matching this regex
reversed=<true|false> Read rows in reverse order
columns=<family>:<qualifier>,... Read only these columns, comma-separated
count=<n> Read only this many rows
cells-per-column=<n> Read only this many cells per column
app-profile=<app-profile-id> The app profile ID to use for the request
format-file=<path-to-format-file> The path to a format-configuration file to use for the request
keys-only=<true|false> Whether to print only row keys
include-stats=full Include a summary of request stats at the end of the request
Examples: (see 'set' examples to create data to read)
cbt read mobile-time-series prefix=phone columns=stats_summary:os_build,os_name count=10
cbt read mobile-time-series start=phone#4c410523#20190501 end=phone#4c410523#20190601
cbt read mobile-time-series regex="phone.*" cells-per-column=1
cbt read mobile-time-series start=phone#4c410523#20190501 end=phone#4c410523#20190601 reversed=true count=10
Note: Using a regex without also specifying start, end, prefix, or count results in a full
table scan, which can be slow.
Set value of a cell (write)
cbt set <table-id> <row-key> [authorized-view=<authorized-view-id>] [app-profile=<app-profile-id>] <family>:<column>=<val>[@<timestamp>] ...
authorized-view=<authorized-view-id> Write to the specified authorized view of the table
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.
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 set mobile-time-series phone#4c410523#20190501 stats_summary:connected_cell=1@12345 stats_summary:connected_cell=0@1570041766
cbt set mobile-time-series phone#4c410523#20190501 stats_summary:os_build=PQ2A.190405.003 stats_summary:os_name=android
Set the garbage-collection policy (age, versions) for a column family
cbt setgcpolicy <table> <family> ((maxage=<d> | maxversions=<n>) [(and|or) (maxage=<d> | maxversions=<n>),...] | never) [force]
force: Optional flag to override warnings when relaxing the garbage-collection policy on replicated clusters.
This may cause your clusters to be temporarily inconsistent, make sure you understand the risks
listed at https://cloud.google.com/bigtable/docs/garbage-collection#increasing
maxage=<d> Maximum timestamp age to preserve. Acceptable units: ms, s, m, h, d
maxversions=<n> Maximum number of versions to preserve
Put garbage collection policies in quotes when they include shell operators && and ||.
Examples:
cbt setgcpolicy mobile-time-series stats_detail maxage=10d
cbt setgcpolicy mobile-time-series stats_summary maxage=10d or maxversions=1 force
Update app profile for an instance
cbt updateappprofile <instance-id> <profile-id> <description>(route-any | [ route-to=<cluster-id> : transactional-writes]) [-force]
force: Optional flag to override any warnings causing the command to fail
Example: cbt updateappprofile my-instance multi-cluster-app-profile-1 "Use this one." route-any
Update a cluster in the configured instance
cbt updatecluster <cluster-id> [num-nodes=<num-nodes>]
cluster-id Permanent, unique ID for the cluster in the instance
num-nodes The new number of nodes
Example: cbt updatecluster my-instance-c1 num-nodes=5
Print the current cbt version
cbt version
Block until all the completed writes have been replicated to all the clusters
cbt waitforreplication <table-id>