Bigtable client libraries

This page shows how to get started with the Cloud Client Libraries for the Cloud Bigtable API. Client libraries make it easier to access Google Cloud APIs from a supported language. Although you can use Google Cloud APIs directly by making raw requests to the server, client libraries provide simplifications that significantly reduce the amount of code you need to write.

Read more about the Cloud Client Libraries and the older Google API Client Libraries in Client libraries explained.

Install the client library

C++

To install the C++ Bigtable client library, for example, with vcpkg, run the following:

vcpkg install google-cloud-cpp[core,bigtable]

See the Setting up a C++ development environment guide for more details about this client library's requirements and install dependencies.

C#

Install-Package Google.Cloud.Bigtable.V2 -Pre
Install-Package Google.Cloud.Bigtable.Admin.V2 -Pre

For more information, see Setting Up a C# Development Environment.

Go

go get cloud.google.com/go/bigtable

For more information, see Setting Up a Go Development Environment.

Java

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.google.cloud</groupId>
<artifactId>libraries-bom</artifactId>
<version>26.69.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
 </dependencies>
</dependencyManagement>
<dependencies>
 <dependency>
 <groupId>com.google.cloud</groupId>
<artifactId>google-cloud-bigtable</artifactId>
</dependency>

If you are using Gradle, add the following to your dependencies:

implementationplatform('com.google.cloud:libraries-bom:26.70.0')
implementation'com.google.cloud:google-cloud-bigtable'

If you are using sbt, add the following to your dependencies:

libraryDependencies+="com.google.cloud"%"google-cloud-bigtable"%"2.68.0"

For more information, see Setting Up a Java Development Environment.

HBase

The Cloud Bigtable HBase client for Java includes the following Maven artifacts that you can choose to use in your project, depending on your use case. The 2.x versions include an HBase async client that the 1.xversions do not have.

  • bigtable-hbase-1.x or bigtable-hbase-2.x: Use one of these artifacts for standalone applications where you control your dependencies.
  • bigtable-hbase-1.x-hadoop or bigtable-hbase-2.x-hadoop: Use one of these artifacts for Hadoop environments.
  • bigtable-hbase-1.x-shaded or bigtable-hbase-2.x-shaded: Use one of these artifacts for environments other than Hadoop that require older versions of the HBase client for Java's dependencies, such as protobuf and Guava.

The Bigtable Maven artifacts include the netty-tcnative-boringssl-static library, which requires that you use Linux, macOS, or Windows on an x86 64-bit processor.

If your application runs in the App Engine standard environment, you must use a current version of the Java runtime. The Java 7 runtime is deprecated and does not support the HBase client for Java.

The following examples assume that you are using the bigtable-hbase-1.x artifact.

If you are using Maven, add the following to your pom.xml file. For more information about BOMs, see The Google Cloud Platform Libraries BOM.

<dependency>
<groupId>com.google.cloud.bigtable</groupId>
<artifactId>bigtable-hbase-1.x</artifactId>
<version>2.6.5</version>
</dependency>

If you are using Gradle, add the following to your dependencies:

compile'com.google.cloud.bigtable:bigtable-hbase-1.x:2.6.5'

If you are using sbt, add the following to your dependencies:

libraryDependencies+="com.google.cloud.bigtable"%"bigtable-hbase-1.x"%"2.6.5"

Node.js

npm install @google-cloud/bigtable

For more information, see Setting Up a Node.js Development Environment.

PHP

Install and enable the gRPC extension for PHP, then run the following command:
composer require google/cloud-bigtable

For more information, see Using PHP on Google Cloud.

Python

pip install --upgrade google-cloud-bigtable

For more information, see Setting Up a Python Development Environment.

Ruby

gem install google-cloud-bigtable

For more information, see Setting Up a Ruby Development Environment.

Set up authentication

To authenticate calls to Google Cloud APIs, client libraries support Application Default Credentials (ADC); the libraries look for credentials in a set of defined locations and use those credentials to authenticate requests to the API. With ADC, you can make credentials available to your application in a variety of environments, such as local development or production, without needing to modify your application code.

For production environments, the way you set up ADC depends on the service and context. For more information, see Set up Application Default Credentials.

For a local development environment, you can set up ADC with the credentials that are associated with your Google Account:

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

    gcloudinit

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. If you're using a local shell, then create local authentication credentials for your user account:

    gcloudauthapplication-defaultlogin

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

Use the client library

The following example shows how to use the client library. The example connects to a Bigtable instance and reads a row from a table.

If you haven't stored any data in Bigtable yet, you can use the cbt CLI to create a table and add some data. See the quickstart using the cbt CLI for instructions.

C++

#include"google/cloud/bigtable/table.h"
intmain(intargc,char*argv[])try{
if(argc!=4){
std::stringconstcmd=argv[0];
autolast_slash=std::string(cmd).find_last_of('/');
std::cerr << "Usage: " << cmd.substr(last_slash+1)
 << " <project_id> <instance_id> <table_id>\n";
return1;
}
std::stringconstproject_id=argv[1];
std::stringconstinstance_id=argv[2];
std::stringconsttable_id=argv[3];
// Create a namespace alias to make the code easier to read.
namespacecbt=::google::cloud::bigtable;
cbt::Tabletable(cbt::MakeDataConnection(),
cbt::TableResource(project_id,instance_id,table_id));
std::stringrow_key="r1";
std::stringcolumn_family="cf1";
std::cout << "Getting a single row by row key:" << std::flush;
google::cloud::StatusOr<std::pair<bool,cbt::Row>>result=
table.ReadRow(row_key,cbt::Filter::FamilyRegex(column_family));
if(!result)throwstd::move(result).status();
if(!result->first){
std::cout << "Cannot find row " << row_key << " in the table: " << table_id
 << "\n";
return0;
}
cbt::Cellconst&cell=result->second.cells().front();
std::cout << cell.family_name() << ":" << cell.column_qualifier() << " @ "
 << cell.timestamp().count() << "us\n"
 << '"' << cell.value() << '"' << "\n";
return0;
}catch(google::cloud::Statusconst&status){
std::cerr << "google::cloud::Status thrown: " << status << "\n";
return1;
}

C#


usingSystem;
usingGoogle.Cloud.Bigtable.Common.V2 ;
// Imports the Google Cloud client library
usingGoogle.Cloud.Bigtable.V2 ;
namespaceGoogleCloudSamples.Bigtable
{
publicclassQuickStart
{
publicstaticintMain(string[]args)
{
// Your Google Cloud Platform project ID
conststringprojectId="YOUR-PROJECT-ID";
// The name of the Cloud Bigtable instance
conststringinstanceId="YOUR-INSTANCE-ID";
// The name of the Cloud Bigtable table
conststringtableId="my-table";
try
{
// Creates a Bigtable client
BigtableClient bigtableClient=BigtableClient .Create ();
// Read a row from my-table using a row key
Row row=bigtableClient.ReadRow (
newTableName (projectId,instanceId,tableId),"r1",RowFilters .CellsPerRowLimit (1));
// Print the row key and data (column value, labels, timestamp)
Console.WriteLine($"{"Rowkey:",-30}{row.Key.ToStringUtf8()}\n"+
$"{"ColumnFamily:",-30}{row.Families[0].Name}\n"+
$"{"ColumnQualifyer:",-30}{row.Families[0].Columns[0].Qualifier.ToStringUtf8()}\n"+
$"{"Value:",-30}{row.Families[0].Columns[0].Cells[0].Value.ToStringUtf8()}\n"+
$"{"Labels:",-30}{row.Families[0].Columns[0].Cells[0].Labels}\n"+
$"{"Timestamp:",-30}{row.Families[0].Columns[0].Cells[0].TimestampMicros}\n");
}
catch(Exceptionex)
{
// Handle error performing the read operation
Console.WriteLine($"Error reading row r1: {ex.Message}");
}
return0;
}
}
}

Go


// Quickstart is a sample program demonstrating use of the Cloud Bigtable client
// library to read a row from an existing table.
packagemain
import(
"context"
"flag"
"log"
"cloud.google.com/go/bigtable"
)
funcmain(){
projectID:="my-project-id"// The Google Cloud Platform project ID
instanceID:="my-instance-id"// The Google Cloud Bigtable instance ID
tableID:="my-table"// The Google Cloud Bigtable table
ctx:=context.Background()
// Set up Bigtable data operations client.
client,err:=bigtable.NewClient (ctx,projectID,instanceID)
iferr!=nil{
log.Fatalf("Could not create data operations client: %v",err)
}
tbl:=client.Open (tableID)
// Read data in a row using a row key
rowKey:="r1"
columnFamilyName:="cf1"
log.Printf("Getting a single row by row key:")
row,err:=tbl.ReadRow (ctx,rowKey)
iferr!=nil{
log.Fatalf("Could not read row with key %s: %v",rowKey,err)
}
log.Printf("Row key: %s\n",rowKey)
log.Printf("Data: %s\n",string(row[columnFamilyName][0].Value ))
iferr=client.Close();err!=nil{
log.Fatalf("Could not close data operations client: %v",err)
}
}

Java


importcom.google.api.gax.rpc.NotFoundException ;
importcom.google.cloud.bigtable.data.v2.BigtableDataClient ;
importcom.google.cloud.bigtable.data.v2.BigtableDataSettings ;
importcom.google.cloud.bigtable.data.v2.models.Row ;
importcom.google.cloud.bigtable.data.v2.models.RowCell ;
importcom.google.cloud.bigtable.data.v2.models.TableId ;
publicclass Quickstart{
publicstaticvoidmain(String...args){
StringprojectId=args[0];// my-gcp-project-id
StringinstanceId=args[1];// my-bigtable-instance-id
StringtableId=args[2];// my-bigtable-table-id
quickstart(projectId,instanceId,tableId);
}
publicstaticvoidquickstart(StringprojectId,StringinstanceId,StringtableId){
BigtableDataSettings settings=
BigtableDataSettings .newBuilder().setProjectId (projectId).setInstanceId (instanceId).build();
// Initialize client that will be used to send requests. This client only needs to be created
// once, and can be reused for multiple requests. After completing all of your requests, call
// the "close" method on the client to safely clean up any remaining background resources.
try(BigtableDataClient dataClient=BigtableDataClient .create(settings)){
System.out.println("\nReading a single row by row key");
Row row=dataClient.readRow (TableId .of(tableId),"r1");
System.out.println("Row: "+row.getKey ().toStringUtf8());
for(RowCell cell:row.getCells ()){
System.out.printf(
"Family: %s Qualifier: %s Value: %s%n",
cell.getFamily(),cell.getQualifier().toStringUtf8(),cell.getValue().toStringUtf8());
}
}catch(NotFoundException e){
System.err.println("Failed to read from a non-existent table: "+e.getMessage());
}catch(Exceptione){
System.out.println("Error during quickstart: \n"+e.toString());
}
}
}

HBase


packagecom.example.cloud.bigtable.quickstart;
importcom.google.cloud.bigtable.hbase.BigtableConfiguration;
importjava.io.IOException;
importorg.apache.hadoop.hbase.TableName;
importorg.apache.hadoop.hbase.client.Connection;
importorg.apache.hadoop.hbase.client.Get;
importorg.apache.hadoop.hbase.client.Result;
importorg.apache.hadoop.hbase.client.Table;
importorg.apache.hadoop.hbase.util.Bytes;
/**
 * A quickstart application that shows connecting to a Cloud Bigtable instance
 * using the native HBase API to read a row from a table.
 */
publicclassQuickstart{
publicstaticvoidmain(String...args){
StringprojectId=args[0];// my-gcp-project-id
StringinstanceId=args[1];// my-bigtable-instance-id
StringtableId=args[2];// my-bigtable-table-id
// Create a connection to the Cloud Bigtable instance.
// Use try-with-resources to make sure the connection is closed correctly
try(Connectionconnection=BigtableConfiguration.connect(projectId,instanceId)){
System.out.println("--- Connection established with Bigtable Instance ---");
// Create a connection to the table that already exists
// Use try-with-resources to make sure the connection to the table is closed correctly
try(Tabletable=connection.getTable(TableName.valueOf(tableId))){
// Read a row
StringrowKey="r1";
System.out.printf("--- Reading for row-key: %s for provided table: %s ---\n",
rowKey,tableId);
// Retrieve the result
Resultresult=table.get(newGet(Bytes.toBytes(rowKey)));
// Convert row data to string
StringrowValue=Bytes.toString(result.value());
System.out.printf("Scanned value for Row r1: %s \n",rowValue);
System.out.println(" --- Finished reading row --- ");
}catch(IOExceptione){
// handle exception while connecting to a table
throwe;
}
}catch(IOExceptione){
System.err.println("Exception while running quickstart: "+e.getMessage());
e.printStackTrace();
}
}
}

Node.js

// Imports the Google Cloud client library
const{Bigtable}=require('@google-cloud/bigtable');
constbigtable=newBigtable ();
asyncfunctionquickstart(){
// Connect to an existing instance:my-bigtable-instance
constinstance=bigtable.instance(INSTANCE_ID);
// Connect to an existing table:my-table
consttable=instance.table(TABLE_ID);
// Read a row from my-table using a row key
const[singleRow]=awaittable.row('r1').get();
// Print the row key and data (column value, labels, timestamp)
constrowData=JSON.stringify(singleRow.data,null,4);
console.log(`Row key: ${singleRow.id}\nData: ${rowData}`);
}
quickstart();

PHP

use Google\Cloud\Bigtable\BigtableClient;
/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $instanceId = 'The Bigtable instance ID';
// $tableId = 'The Bigtable table ID';
// Connect to an existing table with an existing instance.
$dataClient = new BigtableClient([
 'projectId' => $projectId,
]);
$table = $dataClient->table($instanceId, $tableId);
$key = 'r1';
// Read a row from my-table using a row key
$row = $table->readRow($key);
$columnFamilyId = 'cf1';
$columnId = 'c1';
// Get the Value from the Row, using the column_family_id and column_id
$value = $row[$columnFamilyId][$columnId][0]['value'];
printf("Row key: %s\nData: %s\n", $key, $value);

Python

The Python client library for Bigtable offers two APIs, asyncio and a synchronous API. If your application is asynchronous, use asyncio.

importargparse
fromgoogle.cloudimport bigtable
defmain(project_id="project-id", instance_id="instance-id", table_id="my-table"):
 # Create a Cloud Bigtable client.
 client = bigtable .Client (project=project_id)
 # Connect to an existing Cloud Bigtable instance.
 instance = client .instance (instance_id)
 # Open an existing table.
 table = instance.table(table_id)
 row_key = "r1"
 row = table.read_row(row_key.encode("utf-8"))
 column_family_id = "cf1"
 column_id = "c1".encode("utf-8")
 value = row.cells [column_family_id][column_id][0].value.decode("utf-8")
 print("Row key: {}\nData: {}".format(row_key, value))
if __name__ == "__main__":
 parser = argparse.ArgumentParser(
 description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter
 )
 parser.add_argument("project_id", help="Your Cloud Platform project ID.")
 parser.add_argument(
 "instance_id", help="ID of the Cloud Bigtable instance to connect to."
 )
 parser.add_argument(
 "--table", help="Existing table used in the quickstart.", default="my-table"
 )
 args = parser.parse_args()
 main(args.project_id, args.instance_id, args.table)

Python asyncio

The Python client library for Bigtable offers two APIs, asyncio and a synchronous API. If your application is asynchronous, use asyncio.

importargparse
importasyncio
fromgoogle.cloud.bigtable.dataimport BigtableDataClientAsync
async defmain(project_id="project-id", instance_id="instance-id", table_id="my-table"):
 # Create a Cloud Bigtable client.
 client = BigtableDataClientAsync(project=project_id)
 # Open an existing table.
 table = client.get_table(instance_id, table_id)
 row_key = "r1"
 row = await table.read_row(row_key)
 column_family_id = "cf1"
 column_id = b"c1"
 value = row .get_cells (column_family_id, column_id)[0].value.decode("utf-8")
 await table.close()
 await client.close()
 print("Row key: {}\nData: {}".format(row_key, value))
if __name__ == "__main__":
 parser = argparse.ArgumentParser(
 description=__doc__, formatter_class=argparse.ArgumentDefaultsHelpFormatter
 )
 parser.add_argument("project_id", help="Your Cloud Platform project ID.")
 parser.add_argument(
 "instance_id", help="ID of the Cloud Bigtable instance to connect to."
 )
 parser.add_argument(
 "--table", help="Existing table used in the quickstart.", default="my-table"
 )
 args = parser.parse_args()
 asyncio.get_event_loop().run_until_complete(
 main(args.project_id, args.instance_id, args.table)
 )

Ruby

# Import google bigtable client lib
require"google/cloud/bigtable"
# Instantiates a client
bigtable=Google::Cloud::Bigtable .new
# Your Cloud Bigtable instance ID
# instance_id = "my-instance"
# Your Cloud Bigtable table ID
# table_id = "my-table"
# Get table client
table=bigtable.tableinstance_id,table_id
# Read and print row
ptable.read_row "user0000001"

Additional resources

C++

The following list contains links to more resources related to the client library for C++:

C#

The following list contains links to more resources related to the client library for C#:

Go

The following list contains links to more resources related to the client library for Go:

Java

The following list contains links to more resources related to the client library for Java:

HBase

Node.js

The following list contains links to more resources related to the client library for Node.js:

PHP

The following list contains links to more resources related to the client library for PHP:

Python

The following list contains links to more resources related to the client library for Python:

Ruby

The following list contains links to more resources related to the client library for Ruby:

Third-party Cloud Bigtable API client libraries

Scio

The Scio client library provides a Scala API for Dataflow, which can read from and write to Bigtable. The Scio repository provides sample code for a Dataflow pipeline that uses Bigtable.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月30日 UTC.