Skip to content

Commit f6e4b11

Browse files
dbolducdbolduc
authored
doc(bigtable): revamp examples README (#6839)
1 parent bc730c8 commit f6e4b11

2 files changed

Lines changed: 95 additions & 150 deletions

File tree

‎google/cloud/bigtable/examples/README.md‎

Lines changed: 95 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,208 +1,157 @@
1-
# Cloud Bigtable C++ Client Quick Start Code Samples
2-
3-
This directory contains minimal examples to get started quickly, and are
4-
referenced from the Doxygen landing page as "Hello World".
1+
# Google Cloud Bigtable Code Samples
52

63
## Table of Contents
74

85
- [Before you begin](#before-you-begin)
9-
- [Compile the Examples](#compile-the-examples)
10-
- [Run the Examples](#run-the-examples)
6+
- [Set Up Project](#set-up-project)
7+
- [Compile Examples](#compile-examples)
8+
- [Configure Environment](#configure-environment)
119
- [Samples](#samples)
1210
- [Hello World](#hello-world)
1311
- [Administer Instances](#administer-instances)
1412
- [Administer Tables](#administer-tables)
1513
- [Reading and Writing Operations](#reading-and-writing-operations)
14+
- [Credentials](#credentials)
1615

1716
## Before you begin
1817

19-
### Compile the Examples
18+
### Set Up Project
19+
20+
You will need a Google Cloud Platform (GCP) Project with billing and the
21+
Bigtable Admin API enabled. The
22+
[Cloud Bigtable quickstart][cbt-doc-quickstart]
23+
covers the necessary steps in detail. Make a note of the GCP Project ID,
24+
Instance ID, and Table ID as you will need them below.
2025

21-
<!-- START bigtable_hw_install -->
26+
### Compile Examples
2227

2328
These examples are compiled as part of the build for the Cloud Bigtable C++
2429
Client. The instructions on how to compile the code are in the
25-
[top-level README](../../README.md) file.
26-
27-
<!-- END bigtable_hw_install -->
28-
29-
### Run the Examples
30-
31-
You first need to create a production instance, the easiest way is to
32-
follow the
33-
[instructions](https://cloud.google.com/bigtable/docs/creating-instance)
34-
on the Cloud Bigtable site.
35-
36-
#### Configure gRPC Root Certificates
30+
[top-level README](/README.md) file. The Bigtable client library
31+
[quickstart](../quickstart/README.md) may also be relevant.
3732

38-
On some platforms (notably macOS and Windows) you may need to configure gRPC to
39-
accept the Google server certificates. gRPC expects to find a
40-
[PEM](https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail) file
41-
with the list of trusted root certificates in `/usr/share/grpc/roots.pem`
42-
(or `${PREFIX}/share/grpc/roots.pem` if you installed gRPC with a different
43-
`PREFIX`, e.g. `/usr/local`). If your system does not have this file installed
44-
you need to set the `GRPC_DEFAULT_SSL_ROOTS_FILE_PATH` to the location of this
45-
file.
33+
### Configure Environment
4634

47-
This file is included with the gRPC source. You can download it using:
35+
On Windows and macOS, gRPC [requires][grpc-roots-pem-bug] an environment variable
36+
to find the root of trust for SSL. On macOS use:
4837

4938
```console
50-
$ wget https://pki.google.com/roots.pem
51-
$ GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=$PWD/roots.pem
52-
$ export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH
39+
curl -Lo roots.pem https://pki.google.com/roots.pem
40+
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH="$PWD/roots.pem"
5341
```
5442

55-
#### Authenticate with Google Cloud Platform
56-
57-
You may need to authenticate with Google Cloud Platform. The Google Cloud SDK
58-
offers a simple way to do so:
43+
While on Windows use:
5944

6045
```console
61-
$ gcloud auth login
46+
@powershell -NoProfile -ExecutionPolicy unrestricted -Command ^
47+
(new-object System.Net.WebClient).Downloadfile( ^
48+
'https://pki.google.com/roots.pem', 'roots.pem')
49+
set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
6250
```
6351

64-
## Samples
52+
# Samples
6553

66-
### Hello world
54+
## Hello World
6755

68-
View the [Hello World][hello_world_code] example to see sample usage of the
69-
Bigtable client library.
56+
View the [Hello World][hello-world-code] example to see sample usage of the
57+
Bigtable client library. More details on this sample code can be found
58+
[here][doxygen-hello-world].
7059

71-
#### Usage
60+
### Running Hello World
7261

7362
```console
74-
$ ./bigtable_hello_world
75-
Usage: bigtable_hello_world <project_id> <instance_id> <table_id>
63+
$ ./bigtable_hello_world hello-world <project_id> <instance_id> <table_id>
7664
```
7765

78-
#### Run Hello world
66+
## Administer Instances
7967

80-
After configuring gRPC, you can run the examples using:
68+
### Hello World - `InstanceAdmin`
8169

82-
```console
83-
$ export PROJECT_ID=... # Your Google Cloud Platform project ID
84-
$ export INSTANCE_ID=... # Your Cloud Bigtable instance ID
85-
$ ./bigtable_hello_world ${PROJECT_ID} ${INSTANCE_ID} example-table
86-
```
70+
View the [Hello Instance Admin][instance-admin-code] example to see sample usage of instance
71+
administration of the Bigtable client library. More details on this sample code can be found
72+
[here][doxygen-instance-admin].
8773

88-
### Administer Instances
74+
### Running `InstanceAdmin` Samples
8975

90-
View the [example][instance_admin_code] to see sample usage of instance
91-
administration of the Bigtable client library.
76+
| Target | Description |
77+
| ------------------------------------ | ----------------------------------- |
78+
| `./bigtable_hello_instance_admin` | Demonstration of basic operations |
79+
| `./bigtable_hello_app_profile` | Demonstration of basic operations using [App Profile][cbt-doc-app-profiles] |
80+
| `./bigtable_instance_admin_snippets` | Collection of individual operations |
9281

93-
#### Usage
82+
Run the above targets with the `--help` flag to display the available commands and their usage.
83+
Here is an example of one such command which will create an instance.
9484

9585
```console
96-
$ ./bigtable_samples_instance_admin
86+
$ ./bigtable_instance_admin_snippets create-instance <project-id> <instance-id> <zone-id>
87+
```
9788

98-
Usage: bigtable_samples_instance_admin <command> <project_id> [arguments]
89+
## Administer Tables
9990

100-
Examples:
101-
bigtable_samples_instance_admin run my-project my-instance my-cluster us-central1-f
102-
bigtable_samples_instance_admin create-dev-instance my-project my-instance us-central1-f
103-
bigtable_samples_instance_admin delete-instance my-project my-instance
104-
bigtable_samples_instance_admin create-cluster my-project my-instance my-cluster us-central1-a
105-
bigtable_samples_instance_admin delete-cluster my-project my-instance my-cluster
106-
```
91+
### Hello World - `TableAdmin`
10792

108-
**Note:** In the `create-cluster` line, a different zone is chosen as an instance's clusters must be placed in unique zones that are within the same region. See the [documentation](https://cloud.google.com/bigtable/docs/replication-overview#how-it-works) for more details.
93+
View the [Hello Table Admin][table-admin-code] example to see sample usage of table
94+
administration of the Bigtable client library. More details on this sample code can be found [here][doxygen-table-admin].
10995

110-
#### Run instance admin samples
96+
### Running `TableAdmin` Samples
11197

112-
After configuring gRPC, you can run the examples using:
98+
| Target | Description |
99+
| ---------------------------------------- | ----------------------------------- |
100+
| `./bigtable_hello_table_admin` | Demonstration of basic operations |
101+
| `./table_admin_snippets` | Collection of individual operations |
102+
| `./bigtable_table_admin_backup_snippets` | Collection of [Backup][cbt-doc-backups] operations |
113103

104+
Run the above targets with the `--help` flag to display the available commands and their usage.
105+
Here is an example of one such command which will create a table.
114106
```console
115-
$ export PROJECT_ID=... # Your Google Cloud Platform project ID
116-
$ export INSTANCE_ID=... # Your Cloud Bigtable instance ID
117-
$ export CLUSTER_ID=... # Your Cloud Bigtable cluster ID
118-
$ export ZONE=... # Name of the zone where the example will create a new instance
119-
$ ./bigtable_samples_instance_admin run ${PROJECT_ID} ${INSTANCE_ID} ${CLUSTER_ID} ${ZONE}
107+
$ ./table_admin_snippets create-table <project-id> <instance-id> <table-id>
120108
```
121109

122-
[hello_world_code]: bigtable_hello_world.cc
123-
[instance_admin_code]: bigtable_hello_instance_admin.cc
110+
## Reading and Writing Data Operations
124111

125-
### Administer Tables
112+
| Target | Description |
113+
| ------------------------ | ------------------------------------------------ |
114+
| `./read_snippets` | Collection of synchronous read operations |
115+
| `./data_snippets` | Collection of other synchronous table operations |
116+
| `./data_async_snippets` | Collection of asynchronous table operations |
117+
| `./data_filter_snippets` | Collection of operations using [Filters][cbt-doc-filters] |
126118

127-
This sample showcases the basic table / column family operations:
128-
129-
- Create a table
130-
- List tables in the current project
131-
- Retrieve table metadata
132-
- List table column families and GC rules
133-
- Update a column family GC rule
134-
- Delete all the rows
135-
- Delete a table
136-
137-
#### Usage
138-
139-
```console
140-
$ ./bigtable_samples
141-
142-
Usage: bigtable_samples <command> <project_id> <instance_id> <table_id> [arguments]
143-
144-
Examples:
145-
bigtable_samples run my-project my-instance my-table
146-
table_admin_snippets create-table my-project my-instance my-table
147-
table_admin_snippets list-tables my-project my-instance
148-
table_admin_snippets get-table my-project my-instance my-table
149-
table_admin_snippets modify-table my-project my-instance my-table
150-
table_admin_snippets drop-all-rows my-project my-instance my-table
151-
table_admin_snippets delete-table my-project my-instance my-table
152-
```
153-
#### Run admin table samples
154-
After configuring gRPC, you can run the examples using:
119+
The above samples demonstrate individual data operations. Running the targets with
120+
the `--help` flag will display the available commands and their usage. Here is an example of one
121+
such command which will read a row from a table.
155122

156123
```console
157-
$ export PROJECT_ID=... # Your Google Cloud Platform project ID
158-
$ export INSTANCE_ID=... # Cloud Bigtable instance ID
159-
$ export TABLE_ID=... # Cloud Bigtable table ID
160-
$ ./bigtable_samples run ${PROJECT_ID} ${INSTANCE_ID} ${TABLE_ID}
124+
$ ./read_snippets read-row <project-id> <instance-id> <table-id> <row-key>
161125
```
162126

163-
### Reading and Writing Operations
127+
## Credentials
164128

165-
This sample showcases reading and writing operations:
129+
The following samples demonstrate use of [Authentication][cbt-doc-authentication]
130+
and [Access Control][cbt-doc-access-control] for Bigtable. More details on the samples
131+
can be found [here][doxygen-grpc].
166132

167-
- Use Apply to write a single row
168-
- Use BulkApply to write several rows in an operation
169-
- Use ReadRow to read a single row
170-
- Use ReadRows to read several rows in a range
171-
- Use ReadRows to read 'N' rows in a range
172-
- Use CheckAndMutate to modify value
173-
- Use ReadModifyWrite to increament a value and append a string to a value
174-
- Use SampleRows to fetch some sample rows
175-
176-
177-
#### Usage
178-
179-
```console
180-
$ ./data_snippets
181-
182-
Usage: data_snippets <command> <project_id> <instance_id> <table_id> [arguments]
183-
184-
Examples:
185-
data_snippets apply my-project my-instance my-table
186-
data_snippets bulk-apply my-project my-instance my-table
187-
data_snippets read-row my-project my-instance
188-
data_snippets read-rows my-project my-instance my-table
189-
data_snippets read-rows-with-limit my-project my-instance my-table
190-
data_snippets check-and-mutate my-project my-instance my-table
191-
data_snippets read-modify-write my-project my-instance my-table
192-
data_snippets sample-rows my-project my-instance my-table
193-
```
133+
| Target | Description |
134+
| ----------------------------------- | -------------------------------------- |
135+
| `./table_admin_iam_policy_snippets` | Examples to interact with IAM policies |
136+
| `./bigtable_grpc_credentials` | Examples of other types of credentials |
194137

195-
#### Run reading and writing samples
196-
After configuring gRPC, you can run the examples using:
138+
Running the targets with the `--help` flag will display the available commands and their usage. Here is an example of one such command which will output the IAM Policy for a given table.
197139

198140
```console
199-
$ export PROJECT_ID=... # Your Google Cloud Platform project ID
200-
$ export INSTANCE_ID=... # Cloud Bigtable instance ID
201-
$ export TABLE_ID=... # Cloud Bigtable table ID
202-
$ ./data_snippets apply ${PROJECT_ID} ${INSTANCE_ID} ${TABLE_ID}
141+
$ ./table_admin_iam_policy_snippets get-iam-policy <project-id> <instance-id> <table-id>
203142
```
204143

205-
[hello_world_code]: bigtable_hello_world.cc
206-
[instance_admin_code]: bigtable_instance_admin_snippets.cc
207-
[table_admin_code]: table_admin_snippets.cc
208-
[data_snippets]: data_snippets.cc
144+
[hello-world-code]: bigtable_hello_world.cc
145+
[instance-admin-code]: bigtable_hello_instance_admin.cc
146+
[table-admin-code]: bigtable_hello_table_admin.cc
147+
[grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
148+
[cbt-doc-quickstart]: https://cloud.google.com/bigtable/docs/quickstart-cbt
149+
[cbt-doc-app-profiles]: https://cloud.google.com/bigtable/docs/app-profiles
150+
[cbt-doc-backups]: https://cloud.google.com/bigtable/docs/backups
151+
[cbt-doc-filters]: https://cloud.google.com/bigtable/docs/filters
152+
[cbt-doc-authentication]: https://cloud.google.com/bigtable/docs/authentication
153+
[cbt-doc-access-control]: https://cloud.google.com/bigtable/docs/access-control
154+
[doxygen-hello-world]: https://googleapis.dev/cpp/google-cloud-bigtable/latest/bigtable-hello-world.html
155+
[doxygen-instance-admin]: https://googleapis.dev/cpp/google-cloud-bigtable/latest/bigtable-hello-instance-admin.html
156+
[doxygen-table-admin]: https://googleapis.dev/cpp/google-cloud-bigtable/latest/bigtable-hello-table-admin.html
157+
[doxygen-grpc]: https://googleapis.dev/cpp/google-cloud-bigtable/latest/bigtable-samples-grpc-credentials.html

‎google/cloud/bigtable/quickstart/README.md‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,6 @@ SDK](https://cloud.google.com/sdk/). For more information about *Application
5252
Default Credentials*, see
5353
https://cloud.google.com/docs/authentication/production
5454

55-
<!-- START bigtable_hw_install -->
56-
5755
## Using with Bazel
5856

5957
> :warning: If you are using Windows or macOS there are additional instructions
@@ -160,8 +158,6 @@ trust store for SSL certificates, you can download and configure this using:
160158
set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem
161159
```
162160

163-
<!-- END bigtable_hw_install -->
164-
165161
[bazel-install]: https://docs.bazel.build/versions/main/install.html
166162
[grpc-roots-pem-bug]: https://github.com/grpc/grpc/issues/16571
167163
[choco-cmake-link]: https://chocolatey.org/packages/cmake

0 commit comments

Comments
 (0)