Clean up the "hello world" code sample (#328)

Changes to code: + Add region tags for including code in docs + Change `require()` call for consistency with the API docs; the sample now requires the library as `Bigtable` and creates an instance of it by calling `new Bigtable()` + Add comments about shortcuts that would cause performance issues in production + Fix misspelled variable Changes to `README`: + Fix branding issues + Update auth instructions to use the current best practice; `gcloud auth application-default login` is no longer recommended + Update links to the GCP Console + Remove embedded screenshot from the docs, to prevent a broken image if that screenshot goes away + Miscellaneous changes for clarity and consistency
googleapis · Oct 21, 2018 · 13e3d76 · 13e3d76
1 parent 42b3517
commit 13e3d76
Show file tree

Hide file tree

Showing 3 changed files with 81 additions and 61 deletions.
diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -7,6 +7,7 @@ Alexander Fenster <[email protected]>
 Dave Gramlich <[email protected]>
 Eric Uldall <[email protected]>
 Jason Dobry <[email protected]>
+Jeff Williams <[email protected]>
 Jiren Patel <[email protected]>
 Jun Mukai <[email protected]>
 Luke Sneeringer <[email protected]>

diff --git a/samples/hello-world/README.md b/samples/hello-world/README.md
@@ -1,7 +1,7 @@
 # Cloud Bigtable Hello World
 
-This is a simple application that demonstrates using the Nodejs Google Cloud
-API to connect to and interact with Cloud Bigtable.
+This is a simple application that demonstrates using the Google Cloud Client
+Library for Node.js to connect to and interact with Cloud Bigtable.
 
 **Table of Contents**
 
@@ -13,12 +13,12 @@ API to connect to and interact with Cloud Bigtable.
 - [Costs](#costs)
 - [Before you begin](#before-you-begin)
   - [Installing Node dependencies](#installing-node-dependencies)
-  - [Creating a Project in the Google Cloud Platform Console](#creating-a-project-in-the-google-cloud-platform-console)
-  - [Enabling billing for your project.](#enabling-billing-for-your-project)
-  - [Enable the Cloud Bigtable APIs.](#enable-the-cloud-bigtable-apis)
-  - [Install the Google Cloud SDK.](#install-the-google-cloud-sdk)
-  - [Setting Google Application Default Credentials](#setting-google-application-default-credentials)
-- [Provisioning an instance](#provisioning-an-instance)
+  - [Creating a project in the GCP Console](#creating-a-project-in-the-gcp-console)
+  - [Enabling billing for your project](#enabling-billing-for-your-project)
+  - [Enable the Cloud Bigtable APIs](#enable-the-cloud-bigtable-apis)
+  - [Install the Google Cloud SDK](#install-the-google-cloud-sdk)
+  - [Get credentials](#get-credentials)
+- [Creating an instance](#creating-an-instance)
 - [Running the application](#running-the-application)
 - [Cleaning up](#cleaning-up)
 
@@ -29,15 +29,14 @@ API to connect to and interact with Cloud Bigtable.
 
 Download the sample app and navigate into the app directory:
 
-1.  Clone the [Cloud Bigtable Node.js repository][github-repo], to your local
-    machine:
+1.  Clone the [Cloud Bigtable Node.js repository][github-repo] to your machine:
 
         git clone https://github.com/googleapis/nodejs-bigtable.git
 
     Alternatively, you can [download the sample][github-zip] as a zip file and
     extract it.
 
-1.  Change to the Hello World code sample directory.
+1.  Change to the Hello World code sample directory:
 
         cd nodejs-bigtable/samples/hello-world
 
@@ -47,101 +46,93 @@ Download the sample app and navigate into the app directory:
 
 ## Costs
 
-This sample uses billable components of Cloud Platform, including:
+This sample uses billable components of Google Cloud Platform, including:
 
-+   Google Cloud Bigtable
++   Cloud Bigtable
 
 Use the [Pricing Calculator][bigtable-pricing] to generate a cost estimate
-based on your projected usage.  New Cloud Platform users might be eligible for
-a [free trial][free-trial].
+based on your projected usage.  New GCP users might be eligible for a [free
+trial][free-trial].
 
 [bigtable-pricing]: https://cloud.google.com/products/calculator/#id=1eb47664-13a2-4be1-9d16-6722902a7572
 [free-trial]: https://cloud.google.com/free-trial
 
 
 ## Before you begin
 
-This sample assumes you have [Node][node] with a minimum version of 8.0
-installed.
+This sample requires [Node.js][node] 8.0 or later.
 
 [node]: https://nodejs.org
 
 ### Installing Node dependencies
 
-Run the following command to download the bigtable library dependency:
+Run the following command to download the sample's dependencies:
 
     npm install
 
-### Creating a Project in the Google Cloud Platform Console
+### Creating a project in the GCP Console
 
 If you haven't already created a project, create one now. Projects enable you
-to manage all Google Cloud Platform resources for your app, including
+to manage all GCP resources for your app, including
 deployment, access control, billing, and services.
 
-1. Open the [Cloud Platform Console][cloud-console].
+1. Open the [GCP Console][cloud-console].
 1. In the drop-down menu at the top, select **Create a project**.
 1. Give your project a name.
 1. Make a note of the project ID, which might be different from the project
    name. The project ID is used in commands and in configurations.
 
 [cloud-console]: https://console.cloud.google.com/
 
-### Enabling billing for your project.
+### Enabling billing for your project
 
 If you haven't already enabled billing for your project, [enable
-billing][enable-billing] now.  Enabling billing allows is required to use
-Cloud Bigtable and to create VM instances.
+billing][enable-billing] now. You must enable billing to use Cloud Bigtable.
 
-[enable-billing]: https://console.cloud.google.com/project/_/settings
+[enable-billing]: https://console.cloud.google.com/projectselector/settings
 
-### Enable the Cloud Bigtable APIs.
+### Enable the Cloud Bigtable APIs
 
-Make sure to [enable the Bigtable APIs][enable-bigtable-api].
+Make sure to [enable the Cloud Bigtable APIs][enable-bigtable-api].
 
-[enable-bigtable-api]: https://console.cloud.google.com/apis/library?q=bigtable
+[enable-bigtable-api]: https://console.cloud.google.com/flows/enableapi?apiid=bigtable,bigtableadmin.googleapis.com
 
-### Install the Google Cloud SDK.
+### Install the Google Cloud SDK
 
-If you haven't already installed the Google Cloud SDK, [install the Google
-Cloud SDK][cloud-sdk] now. The SDK contains tools and libraries that enable you
-to create and manage resources on Google Cloud Platform.
+If you haven't already installed the Google Cloud SDK, [install it
+now][cloud-sdk], and be sure to run `gcloud init` to [initialize the Cloud
+SDK][cloud-sdk-init]. The SDK contains tools and libraries that enable you to
+create and manage resources on GCP.
 
 [cloud-sdk]: https://cloud.google.com/sdk/
+[cloud-sdk-init]: https://cloud.google.com/sdk/docs/initializing
 
-### Setting Google Application Default Credentials
-
-Set your [Google Application Default
-Credentials][application-default-credentials] by [initializing the Google Cloud
-SDK][cloud-sdk-init] with the command:
-
-    gcloud init
-
-Generate a credentials file by running the [application-default login](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/login) command:
+### Get credentials
 
-    gcloud auth application-default login
+To handle authentication, [create a service account][service-account], and set
+the `GOOGLE_AUTHENTICATION_CREDENTIALS` environment variable to point to your
+service account key.
 
-[cloud-sdk-init]: https://cloud.google.com/sdk/docs/initializing
-[application-default-credentials]: https://developers.google.com/identity/protocols/application-default-credentials
+[service-account]: https://cloud.google.com/docs/authentication/getting-started
 
 
-## Provisioning an instance
+## Creating an instance
 
 Follow the instructions in the [user
 documentation](https://cloud.google.com/bigtable/docs/creating-instance) to
-create a Google Cloud Platform project and Cloud Bigtable instance if necessary.
-You'll need to reference your project id and instance id to run the
-application.
+create a GCP project and Cloud Bigtable instance if necessary. You'll need to
+use your Cloud Bigtable instance ID to run the application.
 
 
 ## Running the application
 
-Run the sample using node. Replace `BIGTABLEINSTANCE` with what you called
-it when provisioning the instance.
+Run the sample using Node.js. Replace `BIGTABLEINSTANCE` with the instance ID
+you chose.
 
     INSTANCE_ID=BIGTABLEINSTANCE node index.js
 
-You will see output resembling the following, interspersed with informational logging
-from the underlying libraries:
+The sample logs the following output to the console, along with informational
+logs from the client library:
 
     Creating table Hello-Bigtable
     Write some greetings to the table
@@ -156,15 +147,15 @@ from the underlying libraries:
 
 ## Cleaning up
 
-To avoid incurring extra charges to your Google Cloud Platform account, remove
-the resources created for this sample.
+To avoid incurring extra charges to your GCP account, remove the resources
+created for this sample.
 
-1.  Go to the [Cloud Bigtable instance page](https://console.cloud.google.com/project/_/bigtable/instances) in the Cloud Console.
+1.  Go to the [Cloud Bigtable instance
+    page](https://console.cloud.google.com//projectselector/bigtable/instances)
+    in the GCP Console.
 
-1.  Click on the instance name.
+1.  Click the instance name.
 
 1.  Click **Delete instance**.
 
-    ![Delete](https://cloud.google.com/bigtable/img/delete-quickstart-instance.png)
-
 1. Type the instance ID, then click **Delete** to delete the instance.
diff --git a/samples/hello-world/index.js b/samples/hello-world/index.js
@@ -10,7 +10,9 @@
 
 /*eslint node/no-unsupported-features: ["error", {version: 8}]*/
 
-const bigtable = require('@google-cloud/bigtable');
+// [START dependencies]
+const Bigtable = require('@google-cloud/bigtable');
+// [END dependencies]
 
 const TABLE_ID = 'Hello-Bigtable';
 const COLUMN_FAMILY_ID = 'cf1';
@@ -36,9 +38,13 @@ const getRowGreeting = row => {
 
 (async () => {
   try {
+    // [START connecting_to_bigtable]
+    const bigtable = new Bigtable();
     const bigtableClient = bigtable(bigtableOptions);
     const instance = bigtableClient.instance(INSTANCE_ID);
+    // [END connecting_to_bigtable]
 
+    // [START creating_a_table]
     const table = instance.table(TABLE_ID);
     const [tableExists] = await table.exists();
     if (!tableExists) {
@@ -55,10 +61,20 @@ const getRowGreeting = row => {
       };
       await table.create(options);
     }
+    // [END creating_a_table]
 
+    // [START writing_rows]
     console.log('Write some greetings to the table');
     const greetings = ['Hello World!', 'Hello Bigtable!', 'Hello Node!'];
     const rowsToInsert = greetings.map((greeting, index) => ({
+      // Note: This example uses sequential numeric IDs for simplicity, but this
+      // pattern can result in poor performance in a production application.
+      // Rows are stored in sorted order by key, so sequential keys can result
+      // in poor distribution of operations across nodes.
+      //
+      // For more information about how to design an effective schema for Cloud
+      // Bigtable, see the documentation:
+      // https://cloud.google.com/bigtable/docs/schema-design
       key: `greeting${index}`,
       data: {
         [COLUMN_FAMILY_ID]: {
@@ -73,27 +89,39 @@ const getRowGreeting = row => {
       },
     }));
     await table.insert(rowsToInsert);
+    // [END writing_rows]
 
+    // [START creating_a_filter]
     const filter = [
       {
         column: {
           cellLimit: 1, // Only retrieve the most recent version of the cell.
         },
       },
     ];
+    // [END creating_a_filter]
 
+    // [START getting_a_row]
     console.log('Reading a single row by row key');
-    const [singeRow] = await table.row('greeting0').get({filter});
-    console.log(`\tRead: ${getRowGreeting(singeRow)}`);
+    const [singleRow] = await table.row('greeting0').get({filter});
+    console.log(`\tRead: ${getRowGreeting(singleRow)}`);
+    // [END getting_a_row]
 
+    // [START scanning_all_rows]
     console.log('Reading the entire table');
+    // Note: For improved performance in production applications, call
+    // `Table#readStream` to get a stream of rows. See the API documentation:
+    // https://cloud.google.com/nodejs/docs/reference/bigtable/latest/Table#createReadStream
     const [allRows] = await table.getRows({filter});
     for (const row of allRows) {
       console.log(`\tRead: ${getRowGreeting(row)}`);
     }
+    // [END scanning_all_rows]
 
+    // [START deleting_a_table]
     console.log('Delete the table');
     await table.delete();
+    // [END deleting_a_table]
   } catch (error) {
     console.error('Something went wrong:', error);
   }