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.

Note: You can perform Bigtable operations at the command line using either the HBase shell or the cbt tool. Use the HBase shell if you are accustomed to it and prefer to use it. Otherwise, we recommend that you use the

cbt
  command-line tool

, which has fewer dependencies and installation steps. The cbt tool is a component of the Google Cloud SDK.

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.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Enable the Cloud Bigtable, Cloud Bigtable Admin APIs.

Enable the APIs

Create a service account:

In the Cloud Console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
To provide access to your project, grant the following role(s) to your service account: Bigtable Administrator .

Click the Select a role field, then select the first (or only) role.

For additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

Do not close your browser window. You will use it in the next step.

Create a service account key:

In the Cloud Console, click the email address for the service account that you created.
Click Keys.
Click Add key, then click Create new key.
Click Create. A JSON key file is downloaded to your computer.
Click Close.

Install and initialize the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Enable the Cloud Bigtable, Cloud Bigtable Admin APIs.

Enable the APIs

Create a service account:

In the Cloud Console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
To provide access to your project, grant the following role(s) to your service account: Bigtable Administrator .

Click the Select a role field, then select the first (or only) role.

For additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
Click Continue.
Click Done to finish creating the service account.

Do not close your browser window. You will use it in the next step.

Create a service account key:

In the Cloud Console, click the email address for the service account that you created.
Click Keys.
Click Add key, then click Create new key.
Click Create. A JSON key file is downloaded to your computer.
Click Close.

Install and initialize the Google Cloud CLI.

Note: If you installed the gcloud CLI previously, make sure you have the latest version by running

gcloud components
      update

Create a Bigtable instance

Open the Create instance page in the Google Cloud Console.

Create an instance
For Instance name, enter Quickstart instance.
For Instance ID, enter quickstart-instance.
For Storage type, select SSD.
For Cluster ID, enter quickstart-instance-c1.
For Region, select a region near you.
For Zone, select a zone in the region you selected.
Click Create to create the instance.

Connect to your instance

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
```
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.

Create a table named my-table.
```
   cbt createtable my-table
```
List your tables:
```
   cbt ls
```
The command displays output similar to the following:
```
    my-table
```
Add one column family named cf1:
```
   cbt createfamily my-table cf1
```

List your column families:

   cbt ls my-table

The command displays output similar to the following:

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

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
```
Note: In this quickstart you only set one cell, but Bigtable lets you set up to ten thousand cells in a single write request.
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:
```
    ----------------------------------------
    r1
      cf1:c1                                   @ 2019/11/26-15:05:38.840000
        "test-value"
```
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.

Delete the table my-table:
```
   cbt deletetable my-table
```

Delete the instance:

   cbt deleteinstance quickstart-instance

Delete the .cbtrc file:
```
   rm ~/.cbtrc
```

What's next

Work through a Bigtable codelab.
View the cbt tool reference documentation.
Write a Hello World application in C#, C++, Go, Java, Node.js, PHP, Python, Ruby, or using the HBase client for Java.