Quickstart using the cbt tool

If you're learning about Cloud Bigtable, you can work through a quickstart to get a taste of the fundamentals that you would use at scale in a production environment.

This quickstart uses the cbt command-line tool. If you prefer to use the HBase shell, follow the quickstart using the HBase shell instead.

In this quickstart, you perform the following actions:

  • Connect to a Cloud Bigtable instance.
  • Perform basic administrative tasks.
  • Write data to a table.
  • Read data from a table.

You can do this quickstart using the Cloud Shell or in your local terminal window.

  1. Select or create a GCP project. If you don't plan to keep the resources you create in this quickstart, create a new project. After you've completed the quickstart, delete the project.

    Go to the project selector page

  2. Make sure billing is enabled for your Google Cloud project. Learn how to confirm that billing is enabled for your project.

  3. Enable the Bigtable and Bigtable Admin APIs.

    Enable the APIs

  4. After you enable the APIs, click Go to credentials.

  5. On the Credentials page, answer the required questions:

    1. In response to "Which API are you using?", choose Cloud Bigtable API.
    2. In response to "What data will you be accessing?", choose Application data.
    3. Answer the question about App Engine or Compute Engine. For this quickstart, you are not using them.
    4. Click What credentials do I need?
    5. If you are prompted to create a service account, provide the following information:
      1. Choose a name for your service account.
      2. For Role, choose Cloud Bigtable > Bigtable Administrator.
      3. Click Done to finish creating the service account.
      4. Click the email address for the service account that you created.
      5. Click Keys.
      6. Click Add key, then click Create new key.
      7. For Key type, select JSON.
      8. Click Create.
      9. Click Close.
      10. Save the newly created service account key JSON file to your local HOME directory or your preferred location. You can skip this step if you plan to complete the quickstart in the Cloud Shell.
    6. If you are not prompted to create a new service account, click Done.
  6. Open a terminal window, either locally or with Cloud Shell:

    Open Cloud Shell

  7. If you are using your local terminal window, set the environment variable GOOGLE_APPLICATION_CREDENTIALS. Replace [PATH] with the file path of the JSON file that contains your service account key.


    For example:

       export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"

  8. If you are using your local terminal window and you have not previously installed the Cloud SDK and the cbt tool, do so now. If you are using the Cloud Shell, these tools are preinstalled and you can skip these steps.

    1. Install the Cloud SDK.

    2. Install the cbt command-line tool:

      gcloud components update
      gcloud components install cbt

Create a Bigtable instance

  1. Open the Create instance page in the Google Cloud Console.

    Create an instance

  2. For Instance name, enter Quickstart instance.

  3. For Instance ID, enter quickstart-instance.

  4. For Storage type, select SSD.

  5. For Cluster ID, enter quickstart-instance-c1.

  6. For Region, select a region near you.

  7. For Zone, select a zone in the region you selected.

  8. Click Create to create the instance.

Connect to your instance

  1. Configure cbt to use your project and instance by creating a .cbtrc file, replacing project-id with the ID for the project where you created your Bigtable instance:

       echo project = project-id > ~/.cbtrc
       echo instance = quickstart-instance >> ~/.cbtrc

  2. Verify that you set up the .cbtrc file correctly:

       cat ~/.cbtrc

    The terminal displays the contents of the .cbtrc file, which looks similar to the following:

    project = project-id
    instance = quickstart-instance

    Now you can use the cbt tool with your instance.

Read and write data

Bigtable stores data in tables, which contain rows. Each row is identified by a row key.

Data in a row is organized into column families, which are groups of columns. A column qualifier identifies a single column within a column family.

There can be multiple time-stamped versions of the value at the intersection of a row and column. Each version is referred to as a cell.

  1. Create a table named my-table.

       cbt createtable my-table

  2. List your tables:

       cbt ls

    The command displays output similar to the following:


  3. Add one column family named cf1:

       cbt createfamily my-table cf1

  4. List your column families:

       cbt ls my-table

    The command displays output similar to the following:

        Family Name     GC Policy
        -----------     ---------
        cf1             <never>

  5. Put the value test-value in the row r1, using the column family cf1 and the column qualifier c1:

       cbt set my-table r1 cf1:c1=test-value

  6. Use the cbt read command to read the data you added to the table:

       cbt read my-table

    The shell displays output similar to the following:

          cf1:c1                                   @ 2019/11/26-15:05:38.840000

    A timestamp is added automatically because you did not specify one.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, delete the instance. Deleting the .cbtrc file leaves you ready to work on a different project.

  1. Delete the table my-table:

       cbt deletetable my-table

  2. Delete the instance:

       cbt deleteinstance quickstart-instance
  3. Delete the .cbtrc file:

       rm ~/.cbtrc