Bigtable: clean up documentation, formatting, and help text
Changes to address docs bugs 120855255, 122635510, 31671073, 74213421,
112533440, 119277645, and 119277663.
Change-Id: I55834776c0b4c7274c45e2e653c2473549a643d9
Reviewed-on: https://code-review.googlesource.com/c/gocloud/+/44370
Reviewed-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Tyler Bui-Palsulich <tbp@google.com>
diff --git a/bigtable/bigtable.go b/bigtable/bigtable.go
index acf7d6d..7c8ea33 100644
--- a/bigtable/bigtable.go
+++ b/bigtable/bigtable.go
@@ -603,6 +603,9 @@
// If the filter matches any cell in the row, mtrue is applied;
// otherwise, mfalse is applied.
// Either given mutation may be nil.
+//
+// The application of a ReadModifyWrite is atomic; concurrent ReadModifyWrites will
+// be executed serially by the server.
func NewCondMutation(cond Filter, mtrue, mfalse *Mutation) *Mutation {
return &Mutation{cond: cond, mtrue: mtrue, mfalse: mfalse}
}
diff --git a/bigtable/cmd/cbt/cbt.go b/bigtable/cmd/cbt/cbt.go
index b0d0983..458b9df 100644
--- a/bigtable/cmd/cbt/cbt.go
+++ b/bigtable/cmd/cbt/cbt.go
@@ -223,12 +223,13 @@
Desc: "Create an instance with an initial cluster",
do: doCreateInstance,
Usage: "cbt createinstance <instance-id> <display-name> <cluster-id> <zone> <num-nodes> <storage type>\n" +
- " instance-id Permanent, unique id for the instance\n" +
+ " instance-id Permanent, unique id for the instance\n" +
" display-name Description of the instance\n" +
- " cluster-id Permanent, unique id for the cluster in the instance\n" +
- " zone The zone in which to create the cluster\n" +
- " num-nodes The number of nodes to create\n" +
- " storage-type SSD or HDD\n",
+ " cluster-id Permanent, unique id for the cluster in the instance\n" +
+ " zone The zone in which to create the cluster\n" +
+ " num-nodes The number of nodes to create\n" +
+ " storage-type SSD or HDD\n" +
+ " Example: ",
Required: cbtconfig.ProjectRequired,
},
{
@@ -237,9 +238,9 @@
do: doCreateCluster,
Usage: "cbt createcluster <cluster-id> <zone> <num-nodes> <storage type>\n" +
" cluster-id Permanent, unique id for the cluster in the instance\n" +
- " zone The zone in which to create the cluster\n" +
- " num-nodes The number of nodes to create\n" +
- " storage-type SSD or HDD\n",
+ " zone The zone in which to create the cluster\n" +
+ " num-nodes The number of nodes to create\n" +
+ " storage-type SSD or HDD\n",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
@@ -254,10 +255,10 @@
Desc: "Create a table",
do: doCreateTable,
Usage: "cbt createtable <table> [families=family[:gcpolicy],...] [splits=split,...]\n" +
- " families: Column families and their associated GC policies. For gcpolicy,\n" +
- " see \"setgcpolicy\".\n" +
- " Example: families=family1:maxage=1w,family2:maxversions=1\n" +
- " splits: Row key to be used to initially split the table",
+ " families Column families and their associated GC policies. For gcpolicy,\n" +
+ " see \"setgcpolicy\".\n" +
+ " Example: families=family1:maxage=30s,family2:maxversions=1\n" +
+ " splits Row key to be used to initially split the table",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
@@ -265,8 +266,8 @@
Desc: "Update a cluster in the configured instance",
do: doUpdateCluster,
Usage: "cbt updatecluster <cluster-id> [num-nodes=num-nodes]\n" +
- " cluster-id Permanent, unique id for the cluster in the instance\n" +
- " num-nodes The number of nodes to update to",
+ " cluster-id Permanent, unique id for the cluster in the instance\n" +
+ " num-nodes The number of nodes to update to",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
@@ -346,17 +347,18 @@
Desc: "Read from a single row",
do: doLookup,
Usage: "cbt lookup <table> <row> [columns=[family]:[qualifier],...] [cells-per-column=<n>] " +
- "[app-profile=<app profile id>]\n" +
+ " [app-profile=<app profile id>]\n" +
" columns=[family]:[qualifier],... Read only these columns, comma-separated\n" +
" cells-per-column=<n> Read only this many cells per column\n" +
- " app-profile=<app profile id> The app profile id to use for the request\n",
+ " app-profile=<app profile id> The app profile id to use for the request\n" +
+ " Example: cbt -instance=<instance> lookup mytable myrow columns=cf:mycolumn1,mycolumn2 cells-per-column-1",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
Name: "ls",
Desc: "List tables and column families",
do: doLS,
- Usage: "cbt ls List tables\n" +
+ Usage: "cbt ls List tables\n" +
"cbt ls <table> List column families in <table>",
Required: cbtconfig.ProjectAndInstanceRequired,
},
@@ -374,19 +376,22 @@
Usage: "cbt read <table> [start=<row>] [end=<row>] [prefix=<prefix>]" +
" [regex=<regex>] [columns=[family]:[qualifier],...] [count=<n>] [cells-per-column=<n>]" +
" [app-profile=<app profile id>]\n" +
- " start=<row> Start reading at this row\n" +
- " end=<row> Stop reading before this row\n" +
- " prefix=<prefix> Read rows with this prefix\n" +
- " regex=<regex> Read rows with keys matching this regex\n" +
+ " start=<row> Start reading at this row\n" +
+ " end=<row> Stop reading before this row\n" +
+ " prefix=<prefix> Read rows with this prefix\n" +
+ " regex=<regex> Read rows with keys matching this regex\n" +
" columns=[family]:[qualifier],... Read only these columns, comma-separated\n" +
- " count=<n> Read only this many rows\n" +
+ " count=<n> Read only this many rows\n" +
" cells-per-column=<n> Read only this many cells per column\n" +
- " app-profile=<app profile id> The app profile id to use for the request\n",
+ " app-profile=<app profile id> The app profile id to use for the request\n" +
+ " Example of writing a row, then reading it by using a regex to find the suffix:\n" +
+ " cbt -instance $bt_instance set $bt_table greeting1 cf1:greeting=Hello Mercury\n" +
+ " cbt -instance $bt_instance read $bt_table regex=\".*1\"",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
Name: "set",
- Desc: "Set value of a cell",
+ Desc: "Set value of a cell (write)",
do: doSet,
Usage: "cbt set <table> <row> [app-profile=<app profile id>] family:column=val[@ts] ...\n" +
" app-profile=<app profile id> The app profile id to use for the request\n" +
@@ -399,7 +404,7 @@
},
{
Name: "setgcpolicy",
- Desc: "Set the GC policy for a column family",
+ Desc: "Set the garbage-collection policy (age, versions) for a column family",
do: doSetGCPolicy,
Usage: "cbt setgcpolicy <table> <family> ((maxage=<d> | maxversions=<n>) [(and|or) (maxage=<d> | maxversions=<n>),...] | never)\n" +
"\n" +
@@ -419,9 +424,9 @@
Desc: "Create a table from a snapshot (snapshots alpha)",
do: doCreateTableFromSnapshot,
Usage: "cbt createtablefromsnapshot <table> <cluster> <snapshot>\n" +
- " table The name of the table to create\n" +
- " cluster The cluster where the snapshot is located\n" +
- " snapshot The snapshot to restore",
+ " table The name of the table to create\n" +
+ " cluster The cluster where the snapshot is located\n" +
+ " snapshot The snapshot to restore",
Required: cbtconfig.ProjectAndInstanceRequired,
},
{
@@ -826,7 +831,7 @@
{{range .Commands}}
{{printf "%-25s %s" .Name .Desc}}{{end}}
-Use "cbt help <command>" for more information about a command.
+Use "cbt help \<command>" for more information about a command.
The options are:
{{range .Flags}}
