Repository files navigation

Java idiomatic client forCloud Bigtable.

• Product Documentation
• Client Library Documentation

If you are using Maven withBOM, add this to your pom.xml file:

<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 Maven without the BOM, add this to your dependencies:

<dependency>  <groupId>com.google.cloud</groupId>  <artifactId>google-cloud-bigtable</artifactId>  <version>2.67.0</version></dependency>

If you are using Gradle 5.x or later, add this to your dependencies:

implementation platform('com.google.cloud:libraries-bom:26.71.0')implementation'com.google.cloud:google-cloud-bigtable'

If you are using Gradle without BOM, add this to your dependencies:

implementation'com.google.cloud:google-cloud-bigtable:2.70.1'

If you are using SBT, add this to your dependencies:

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

See theAuthentication section in the base directory's README.

The client application making API calls must be grantedauthorization scopes required for the desired Cloud Bigtable APIs, and the authenticated principal must have theIAM role(s) required to access GCP resources using the Cloud Bigtable API calls.

You will need aGoogle Cloud Platform Console project with the Cloud BigtableAPI enabled.You will need toenable billing to use Google Cloud Bigtable.Follow these instructions to get your project set up. You will also need to set up the local development environment byinstalling the Google Cloud Command Line Interface and running the following commands in command line:gcloud auth login andgcloud config set project [YOUR PROJECT ID].

You'll need to obtain thegoogle-cloud-bigtable library. See theQuickstart sectionto addgoogle-cloud-bigtable as a dependency in your code.

Cloud Bigtable API for reading and writing the contents of Bigtables associated with a cloud project.

See theCloud Bigtable client library docs to learn how touse this Cloud Bigtable Client Library.

Cloud Bigtable is Google's NoSQL Big Data database service. It'sthe same database that powers many core Google services, including Search, Analytics, Maps, andGmail.

Be sure to activate the Cloud Bigtable API and the Cloud Bigtable Admin API under APIs & Services in the GCP Console to use Cloud Bigtable from your project.

See the Bigtable client library documentation (Admin API andData API) to learn how tointeract with Cloud Bigtable using this Client Library.

Cloud Bigtable is composed of instances, clusters, nodes and tables.

Instances are containers for clusters.

Clusters represent the actual Cloud Bigtable service. Each cluster belongs to a single Cloud Bigtable instance, and an instance can have up to 4 clusters. When your applicationsends requests to a Cloud Bigtable instance, those requests are actually handled by one of the clusters in the instance.

Each cluster in a production instance has 3 or more nodes, which are compute resources that Cloud Bigtable uses to manage your data.

Tables contain the actual data and are replicated across all of the clusters in an instance.

The Cloud Bigtable API consists of:

Allows callers to persist and query data in a table. It's exposed byBigtableDataClient.

Allows callers to create and manage instances, clusters, tables, and access permissions. This API is exposed by:BigtableInstanceAdminClient for Instance and Cluster level resources.

SeeBigtableTableAdminClient for table management.

SeeBigtableDataClient for the data client.

SeeBigtableInstanceAdminClient for the instance admin client.

SeeBigtableTableAdminClient for the table admin client.

The Cloud Bigtable API is split into 3 parts: Data API, Instance Admin API and Table Admin API.

Here is a code snippet showing simple usage of the Data API. Add the following importsat the top of your file:

importcom.google.cloud.bigtable.data.v2.BigtableDataClient;importcom.google.cloud.bigtable.data.v2.models.Query;importcom.google.cloud.bigtable.data.v2.models.Row;

Then, to make a query to Bigtable, use the following code:

// Instantiates a clientStringprojectId ="my-project";StringinstanceId ="my-instance";StringtableId ="my-table";// Create the client.// Please note that creating the client is a very expensive operation// and should only be done once and shared in an application.BigtableDataClientdataClient =BigtableDataClient.create(projectId,instanceId);try {// Query a tableQueryquery =Query.create(tableId)      .range("a","z")      .limit(26);for (Rowrow :dataClient.readRows(query)) {System.out.println(row.getKey());  }}finally {dataClient.close();}

The Admin APIs are similar. Here is a code snippet showing how to create a table. Add the followingimports at the top of your file:

importstaticcom.google.cloud.bigtable.admin.v2.models.GCRules.GCRULES;importcom.google.cloud.bigtable.admin.v2.BigtableTableAdminClient;importcom.google.cloud.bigtable.admin.v2.models.CreateTableRequest;importcom.google.cloud.bigtable.admin.v2.models.Table;

Then, to create a table, use the following code:

StringprojectId ="my-instance";StringinstanceId ="my-database";BigtableTableAdminClienttableAdminClient =BigtableTableAdminClient  .create(projectId,instanceId);try {tableAdminClient.createTable(CreateTableRequest.of("my-table")        .addFamily("my-family")  );}finally {tableAdminClient.close();}

TIP: If you are experiencing version conflicts with gRPC, seeVersion Conflicts.

Cloud Bigtable client supports publishing client side metrics toCloud Monitoring under thebigtable.googleapis.com/client namespace.

This feature is available once you upgrade to version 2.16.0 and above.Follow the guide onhttps://cloud.google.com/bigtable/docs/client-side-metrics-setup to enable.

Since version 2.38.0,client side metricsis enabled by default. This feature collects useful telemetry data in the client and is recommended touse in conjunction with server-side metrics to get a complete, actionable view of your Bigtableperformance. There is no additional cost to publish and view client-side metricsin Cloud Monitoring.

You can opt-out client side metrics with the following settings:

BigtableDataSettingssettings =BigtableDataSettings.newBuilder()        .setProjectId("my-project")        .setInstanceId("my-instance")        .setMetricsProvider(NoopMetricsProvider.INSTANCE)        .build();

If your application already has OpenTelemetry integration, you can register client side metrics onyour OpenTelemetry instance. You can refer toCustomOpenTelemetryMetricsProvideron how to set it up.

If your application already has tracing integration and you want to disable Bigtabletraces, you can do the following:

publicstaticclassMySamplerextendsSampler {privatefinalSamplerchildSampler;MySampler(Samplerchild) {this.childSampler =child;    }@OverridepublicbooleanshouldSample(@NullableSpanContextparentContext,@NullableBooleanhasRemoteParent,TraceIdtraceId,SpanIdspanId,Stringname,List<Span>parentLinks) {if (name.contains("Bigtable")) {returnfalse;        }returnchildSampler.shouldSample(parentContext,hasRemoteParent,traceId,spanId,name,parentLinks);    }@OverridepublicStringgetDescription() {return"from my sampler";    }}

And use this sampler in your trace config:

Tracing.getTraceConfig().updateActiveTraceParams(Tracing.getTraceConfig().getActiveTraceParams().toBuilder()                .setSampler(newMySampler(Samplers.probabilitySampler(0.1)))                .build());

google-cloud-bigtable depends on gRPC directly which may conflict with the versions broughtin by other libraries, for example Apache Beam. This happens because internal dependenciesbetween gRPC libraries are pinned to an exact version of grpc-core(seehere).If both google-cloud-bigtable and the other library bring in two gRPC libraries that dependon the different versions of grpc-core, then dependency resolution will fail.The easiest way to fix this is to depend on the gRPC bom, which will force all the gRPCtransitive libraries to use the same version.

Add the following to your project's pom.xml.

    <dependencyManagement>      <dependencies>        <dependency>          <groupId>io.grpc</groupId>          <artifactId>grpc-bom</artifactId>          <version>1.28.0</version>          <type>pom</type>          <scope>import</scope>        </dependency>      </dependencies>    </dependencyManagement>

While deploying this client inGoogle Kubernetes Engine(GKE) withCoS. Please make sure to provide CPU configuration in your deployment file. With default configuration JVM detects only 1 CPU, which affects the number of channels with the client, resulting in performance repercussion.

Also, The number ofgrpc-nio-worker-ELG-1-# thread is same as number of CPUs. These are managed by a singlegrpc-default-executor-# thread, which is shared among multiple client instances.

For example:

appVersion:v1...spec:...container:resources:requests:cpu:"1"# Here 1 represents 100% of single node CPUs whereas other than 1 represents the number of CPU it would use from a node.

seeAssign CPU Resources to Containers for more information.

Samples are in thesamples/ directory.

Sample	Source Code	Try it
Authorized View Example	source code
Configure Connection Pool	source code
Filters	source code
Hello World	source code
Instance Admin Example	source code
Key Salting	source code
Quickstart	source code
Reads	source code
Schema Bundle Example	source code
Table Admin Example	source code
Write Aggregate	source code
Write Batch	source code
Write Conditionally	source code
Write Increment	source code
Write Simple	source code
Batch Delete Example	source code
Conditional Delete Example	source code
Delete Column Family Example	source code
Delete From Column Example	source code
Delete From Column Family Example	source code
Delete From Row Example	source code
Delete Table Example	source code
Drop Row Range Example	source code

To get help, follow the instructions in theshared Troubleshooting document.

Cloud Bigtable uses gRPC for the transport layer.

Java 8 or above is required for using this client.

Google's Java client libraries,Google Cloud Client LibrariesandGoogle Cloud API Libraries,follow theOracle Java SE support roadmap(see the Oracle Java SE Product Releases section).

In general, new feature development occurs with support for the lowest JavaLTS version covered by Oracle's Premier Support (which typically lasts 5 yearsfrom initial General Availability). If the minimum required JVM for a givenlibrary is changed, it is accompanied by asemver major release.

Java 11 and (in September 2021) Java 17 are the best choices for newdevelopment.

Google tests its client libraries with all current LTS versions covered byOracle's Extended Support (which typically lasts 8 years from initialGeneral Availability).

Google's client libraries support legacy versions of Java runtimes with longterm stable libraries that don't receive feature updates on a best efforts basisas it may not be possible to backport all patches.

Google provides updates on a best efforts basis to apps that continue to useJava 7, though apps might need to upgrade to current versions of the librarythat supports their JVM.

The latest versions and the supported Java versions are identified onthe individual GitHub repositorygithub.com/GoogleAPIs/java-SERVICENAMEand ongoogle-cloud-java.

This library followsSemantic Versioning.

Contributions to this library are always welcome and highly encouraged.

SeeCONTRIBUTING for more information how to get started.

Please note that this project is released with a Contributor Code of Conduct. By participating inthis project you agree to abide by its terms. SeeCode of Conduct for moreinformation.

Apache 2.0 - SeeLICENSE for more information.

Java Version	Status
Java 8
Java 8 OSX
Java 8 Windows
Java 11

Java is a registered trademark of Oracle and/or its affiliates.