Package com.google.cloud.bigtable.data.v2 (2.30.0)

A client for the Cloud Bigtable data API. See Also: com.google.cloud.bigtable.data.v2.BigtableDataClientfor usage.

Classes

BigtableDataClient

Client for reading from and writing to existing Bigtable tables.

This class provides the ability to make remote calls to the backing service. Sample code to get started:


 // One instance per application.
 BigtableDataClient client = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")

 for(Row row : client.readRows(Query.create("[TABLE]"))) {
   // Do something with row
 }

 // Cleanup during application shutdown.
 client.close();

Creating a new client is a very expensive operation and should only be done once and shared in an application. However, close() needs to be called on the client object to clean up resources such as threads during application shutdown.

This client can be safely shared across multiple threads except for the Batcher instances returned from bulk operations, eg. newBulkMutationBatcher(), newBulkReadRowsBatcher().

The surface of this class includes several types of Java methods for each of the API's methods:

  1. A "flattened" method, like readRows(). With this type of method, the fields of the request type have been converted into function parameters. It may be the case that not all fields are available as parameters, and not every API method will have a flattened method entry point.
  2. A "callable" method, like readRowsCallable(). This type of method takes no parameters and returns an immutable API callable object, which can be used to initiate calls to the service.

Taking ReadRows as an example for callable:


 // These two invocation are equivalent
 ServerStream<Row> stream1 = client.readRows(query);
 ServerStream<Row> stream2 = client.readRowsCallable().call(query);

 // These two invocation are also equivalent
 client.readRowsAsync(query, observer);
 client.readRowsCallable().call(query, observer);

All RPC related errors are represented as subclasses of com.google.api.gax.rpc.ApiException. For example, a nonexistent table will trigger a com.google.api.gax.rpc.NotFoundException. Async methods will wrap the error inside the future. Synchronous methods will re-throw the async error but will try to preserve the caller's stacktrace by attaching a suppressed exception at the callsite. This allows callers to use typesafe exceptions, without losing their callsite. Streaming methods (ie. readRows) will re-throw the async exception (like sync methods) when starting iteration.

See the individual methods for example code.

This class can be customized by passing in a custom instance of BigtableDataSettings to create(). For example:

To customize credentials:


 BigtableDataSettings settings =
     BigtableDataSettings.newBuilder()
         .setProjectId("[PROJECT]")
         .setInstanceId("[INSTANCE]")
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 BigtableDataClient client = BigtableDataClient.create(settings);

To customize the endpoint:


 BigtableDataSettings.Builder settingsBuilder =
     BigtableDataSettings.newBuilder()
       .setProjectId("[PROJECT]")
       .setInstanceId("[INSTANCE]");

 settingsBuilder.stubSettings()
     .setEndpoint(myEndpoint).build();

 BigtableDataClient client = BigtableDataClient.create(settings.build());

BigtableDataClientFactory

A factory to create multiple BigtableDataClient instances that all share the same channel pool.

This allows multiple client instances to share the same gRPC channel pool, which makes client creation very cheap. The intended use case is for applications that need to access multiple Bigtable Instances from the same process.

Example Usage:


 BigtableDataSettings defaultSettings = BigtableDataSettings.newBuilder()
   .setProject("my-default-project")
   .setInstance("my-default-instance")
   .build();

 BigtableDataClientFactory clientFactory = BigtableDataClientFactory.create(defaultSettings);

 // Create a new client for "my-default-instance" in "my-default-project";
 BigtableDataClient defaultInstanceClient = clientFactory.createDefault();

 // Create a new client for a different application profile
 BigtableDataClient otherAppProfileClient = clientFactory.createForAppProfile("other-app-profile");

 // Create a new client for a completely different instance and application profile.
 BigtableDataClient otherInstanceClient = clientFactory
   .createForInstance("my-other-project", "my-other-instance", "my-other-app-profile");

 // Clean up: make sure close the clients AND the factory.
 defaultInstanceClient.close();
 otherAppProfileClient.close();
 otherInstanceClient.close();

 clientFactory.close();

 
Please note that this is an experimental feature and might be changed or removed in future.

BigtableDataSettings

Settings class to configure an instance of BigtableDataClient.

Sane defaults are provided for most settings:

  • The default service address (bigtable.googleapis.com) and default port (443) are used.
  • The transport provider is configured with a channel pool that contains twice as many connections as CPUs.
  • Credentials are acquired automatically through Application Default Credentials.
  • Retries are configured for idempotent methods but not for non-idempotent methods.

The only required setting is the instance name.

The builder of this class is recursive, so contained classes are themselves builders. When build() is called, the tree of builders is called to create the complete settings object.


 BigtableDataSettings.Builder settingsBuilder = BigtableDataSettings.newBuilder()
   .setProjectId("my-project")
   .setInstanceId("my-instance-id")
   .setAppProfileId("default");

 BigtableDataSettings settings = builder.build();

For fine grained control of individual RPCs, please refer to EnhancedBigtableStubSettings, which is exposed as Builder#stubSettings().

BigtableDataSettings.Builder

Builder for BigtableDataSettings.