com.google.cloud.bigtable.data.v2

Class BigtableDataClient

java.lang.Object

com.google.cloud.bigtable.data.v2.BigtableDataClient

All Implemented Interfaces:

AutoCloseable

public class BigtableDataClient
extends Object
implements AutoCloseable

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:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create(instanceName)) {
   for(Row row : bigtableDataClient.readRows(Query.create("[TABLE]")) {
     // Do something with row
   }
 }
 

Note: close() needs to be called on the bigtableDataClient object to clean up resources such as threads. In the example above, try-with-resources is used, which automatically calls close().

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.

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 bigtableDataSettings =
     BigtableDataSettings.newBuilder()
         .setInstanceName(InstanceName.of("[PROJECT]", "[INSTANCE]"))
         .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
         .build();
 try(BigtableDataClient bigtableDataClient = BigtableDataClient.create(bigtableDataSettings)) {
   // ..
 }
 

To customize the endpoint:

 BigtableDataSettings bigtableDataSettings =
     BigtableDataSettings.newBuilder()
       .setInstanceName(InstanceName.of("[PROJECT]", "[INSTANCE]"))
       .setEndpoint(myEndpoint).build();
 try(BigtableDataClient bigtableDataClient = BigtableDataClient.create(bigtableDataSettings)) {
   // ..
 }
 

Method Summary

Modifier and Type	Method and Description
com.google.api.core.ApiFuture<Void>	bulkMutateRowsAsync(BulkMutation mutation) Convenience method to mutate multiple rows in a batch.
com.google.api.gax.rpc.UnaryCallable<BulkMutation,Void>	bulkMutationCallable() Mutates multiple rows in a batch.
com.google.api.core.ApiFuture<Boolean>	checkAndMutateRowAsync(ConditionalRowMutation mutation) Convenience method to asynchronously mutate a row atomically based on the output of a filter.
com.google.api.gax.rpc.UnaryCallable<ConditionalRowMutation,Boolean>	checkAndMutateRowCallable() Mutates a row atomically based on the output of a filter.
void	close() Close the clients and releases all associated resources.
static BigtableDataClient	create(BigtableDataSettings settings) Constructs an instance of BigtableDataClient, using the given settings.
static BigtableDataClient	create(InstanceName instanceName) Constructs an instance of BigtableClient with default settings.
com.google.api.core.ApiFuture<Void>	mutateRowAsync(RowMutation rowMutation) Convenience method to asynchronously mutate a single row atomically.
com.google.api.gax.rpc.UnaryCallable<RowMutation,Void>	mutateRowCallable() Mutates a single row atomically.
BulkMutationBatcher	newBulkMutationBatcher() Mutates multiple rows in a batch.
com.google.api.core.ApiFuture<Row>	readModifyWriteRowAsync(ReadModifyWriteRow mutation) Convenience method that asynchronously modifies a row atomically on the server.
com.google.api.gax.rpc.UnaryCallable<ReadModifyWriteRow,Row>	readModifyWriteRowCallable() Modifies a row atomically on the server.
com.google.api.core.ApiFuture<Row>	readRowAsync(String tableId, com.google.protobuf.ByteString rowKey) Convenience method for asynchronously reading a single row.
com.google.api.core.ApiFuture<Row>	readRowAsync(String tableId, String rowKey) Convenience method for asynchronously reading a single row.
com.google.api.gax.rpc.ServerStream<Row>	readRows(Query query) Convenience method for synchronous streaming the results of a Query.
void	readRowsAsync(Query query, com.google.api.gax.rpc.ResponseObserver<Row> observer) Convenience method for asynchronous streaming the results of a Query.
com.google.api.gax.rpc.ServerStreamingCallable<Query,Row>	readRowsCallable() Streams back the results of the query.
<RowT> com.google.api.gax.rpc.ServerStreamingCallable<Query,RowT>	readRowsCallable(RowAdapter<RowT> rowAdapter) Streams back the results of the query.
com.google.api.core.ApiFuture<List<KeyOffset>>	sampleRowKeysAsync(String tableId) Convenience method to asynchronously return a sample of row keys in the table.
com.google.api.gax.rpc.UnaryCallable<String,List<KeyOffset>>	sampleRowKeysCallable() Returns a sample of row keys in the table.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static BigtableDataClient create(InstanceName instanceName)
                                 throws IOException

Constructs an instance of BigtableClient with default settings.

Parameters:

instanceName - The instance to connect to.

Returns:

A new client.

Throws:

IOException - If any.

create

public static BigtableDataClient create(BigtableDataSettings settings)
                                 throws IOException

Constructs an instance of BigtableDataClient, using the given settings. The channels are created based on the settings passed in, or defaults for any settings that are not set.

Throws:

IOException

readRowAsync

public com.google.api.core.ApiFuture<Row> readRowAsync(String tableId,
                                                       String rowKey)

Convenience method for asynchronously reading a single row. If the row does not exist, the future's value will be null.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   ApiFuture<Row> result = bigtableClient.readRow(tableId,  "key");
 }
 

readRowAsync

public com.google.api.core.ApiFuture<Row> readRowAsync(String tableId,
                                                       com.google.protobuf.ByteString rowKey)

Convenience method for asynchronously reading a single row. If the row does not exist, the future's value will be null.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   ApiFuture<Row> result = bigtableClient.readRow(tableId,  ByteString.copyFromUtf8("key"));
 }
 

readRows

public com.google.api.gax.rpc.ServerStream<Row> readRows(Query query)

Convenience method for synchronous streaming the results of a Query.

Sample code:

 // Import the filter DSL
 import static com.google.cloud.bigtable.data.v2.models.Filters.FILTERS;

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   Query query = Query.create(tableId)
          .range("[START KEY]", "[END KEY]")
          .filter(FILTERS.qualifier().regex("[COLUMN PREFIX].*"));

   // Iterator style
   for(Row row : bigtableClient.readRows(query)) {
     // Do something with row
   }
 }
 

See Also:

For call styles., For query options., For the filter building DSL.

readRowsAsync

public void readRowsAsync(Query query,
                          com.google.api.gax.rpc.ResponseObserver<Row> observer)

Convenience method for asynchronous streaming the results of a Query.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   Query query = Query.create(tableId)
          .range("[START KEY]", "[END KEY]")
          .filter(FILTERS.qualifier().regex("[COLUMN PREFIX].*"));

   client.readRowsAsync(query, new ResponseObserver<Row>() {
     public void onStart(StreamController controller) { }
     public void onResponse(Row response) {
       // Do something with Row
     }
     public void onError(Throwable t) {
       // Handle error before the stream completes
     }
     public void onComplete() {
       // Handle stream completion
     }
   });
 }
 

readRowsCallable

public com.google.api.gax.rpc.ServerStreamingCallable<Query,Row> readRowsCallable()

Streams back the results of the query. The returned callable object allows for customization of api invocation.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   Query query = Query.create(tableId)
          .range("[START KEY]", "[END KEY]")
          .filter(FILTERS.qualifier().regex("[COLUMN PREFIX].*"));

   // Iterator style
   for(Row row : bigtableClient.readRowsCallable().call(query)) {
     // Do something with row
   }

   // Point look up
   ApiFuture<Row> rowFuture = bigtableClient.readRowsCallable().first().futureCall(query);

   // etc
 }
 

See Also:

For call styles., For query options., For the filter building DSL.

readRowsCallable

public <RowT> com.google.api.gax.rpc.ServerStreamingCallable<Query,RowT> readRowsCallable(RowAdapter<RowT> rowAdapter)

Streams back the results of the query. This callable allows for customization of the logical representation of a row. It's meant for advanced use cases.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   String tableId = "[TABLE]";

   Query query = Query.create(tableId)
          .range("[START KEY]", "[END KEY]")
          .filter(FILTERS.qualifier().regex("[COLUMN PREFIX].*"));

   // Iterator style
   for(CustomRow row : bigtableClient.readRowsCallable(new CustomRowAdapter()).call(query)) {
     // Do something with row
   }
 }
 

See Also:

For call styles., For query options., For the filter building DSL.

sampleRowKeysAsync

public com.google.api.core.ApiFuture<List<KeyOffset>> sampleRowKeysAsync(String tableId)

Convenience method to asynchronously return a sample of row keys in the table. The returned row keys will delimit contiguous sections of the table of approximately equal size, which can be used to break up the data for distributed tasks like mapreduces.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   ApiFuture<List<KeyOffset>> keyOffsets = bigtableClient.sampleRowKeysAsync("[TABLE]");
 }
 

sampleRowKeysCallable

public com.google.api.gax.rpc.UnaryCallable<String,List<KeyOffset>> sampleRowKeysCallable()

Returns a sample of row keys in the table. The returned row keys will delimit contiguous sections of the table of approximately equal size, which can be used to break up the data for distributed tasks like mapreduces. The returned callable object allows for customization of api invocation.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   // Synchronous invocation
   List<KeyOffset> keyOffsets = bigtableClient.sampleRowKeysCallable().call("[TABLE]");

   // Asynchronous invocation
   ApiFuture<List<KeyOffset>> keyOffsets = bigtableClient.sampleRowKeysCallable().futureCall("[TABLE]");
 }
 

mutateRowAsync

public com.google.api.core.ApiFuture<Void> mutateRowAsync(RowMutation rowMutation)

Convenience method to asynchronously mutate a single row atomically. Cells already present in the row are left unchanged unless explicitly changed by the RowMutation.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
     .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

   ApitFuture<Void> future = bigtableClient.mutateRowAsync(mutation);
 }
 

mutateRowCallable

public com.google.api.gax.rpc.UnaryCallable<RowMutation,Void> mutateRowCallable()

Mutates a single row atomically. Cells already present in the row are left unchanged unless explicitly changed by the RowMutation.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
     .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

   bigtableClient.mutateRowCallable().call(mutation);
 }
 

newBulkMutationBatcher

@BetaApi(value="This surface is likely to change as the batching surface evolves.")
public BulkMutationBatcher newBulkMutationBatcher()

Mutates multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   try (BulkMutationBatcher batcher = bigtableClient.newBulkMutationBatcher()) {
     for (String someValue : someCollection) {
       RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
         .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

       batcher.add(mutation);
     }
   } catch (BulkMutationFailure failure) {
     // Handle error
   }
   // After `batcher` is closed, all mutations have been applied
 }
 

bulkMutateRowsAsync

public com.google.api.core.ApiFuture<Void> bulkMutateRowsAsync(BulkMutation mutation)

Convenience method to mutate multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically. Unlike newBulkMutationBatcher(), this method expects the mutations to be pre-batched.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   BulkMutation batch = BulkMutation.create("[TABLE]");
   for (String someValue : someCollection) {
     batch.add("[ROW KEY]", Mutation.create().setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");
   }
   ApiFuture<Void> result = bigtableClient.bulkMutateRowsAsync(batch);
 }
 

bulkMutationCallable

public com.google.api.gax.rpc.UnaryCallable<BulkMutation,Void> bulkMutationCallable()

Mutates multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically. Unlike newBulkMutationBatcher(), this method expects the mutations to be pre-batched.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   BulkMutation batch = BulkMutation.create("[TABLE]");
   for (String someValue : someCollection) {
     batch.add("[ROW KEY]", Mutation.create().setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");
   }
   bigtableClient.bulkMutateRowsCallable().call(batch);
 }
 

checkAndMutateRowAsync

public com.google.api.core.ApiFuture<Boolean> checkAndMutateRowAsync(ConditionalRowMutation mutation)

Convenience method to asynchronously mutate a row atomically based on the output of a filter.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   ConditionalRowMutation mutation = ConditionalRowMutation.create("[TABLE]", "[KEY]")
     .condition(FILTERS.value().regex("old-value"))
     .then(
       Mutation.create()
         .setCell("[FAMILY]", "[QUALIFIER]", "[VALUE]")
       );

   ApiFuture<Boolean> future = bigtableClient.checkAndMutateRowAsync(mutation);
 }
 

checkAndMutateRowCallable

public com.google.api.gax.rpc.UnaryCallable<ConditionalRowMutation,Boolean> checkAndMutateRowCallable()

Mutates a row atomically based on the output of a filter.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   ConditionalRowMutation mutation = ConditionalRowMutation.create("[TABLE]", "[KEY]")
     .condition(FILTERS.value().regex("old-value"))
     .then(
       Mutation.create()
         .setCell("[FAMILY]", "[QUALIFIER]", "[VALUE]")
       );

   boolean success = bigtableClient.checkAndMutateRowCallable().call(mutation);
 }
 

readModifyWriteRowAsync

public com.google.api.core.ApiFuture<Row> readModifyWriteRowAsync(ReadModifyWriteRow mutation)

Convenience method that asynchronously modifies a row atomically on the server. The method reads the latest existing timestamp and value from the specified columns and writes a new entry. The new value for the timestamp is the greater of the existing timestamp or the current server time. The method returns the new contents of all modified cells.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   ReadModifyWriteRow mutation = ReadModifyWriteRow.create("[TABLE]", "[KEY]")
     .increment("[FAMILY]", "[QUALIFIER]", 1)
     .append("[FAMILY2]", "[QUALIFIER2]", "suffix");

   ApiFuture<Row> success = bigtableClient.readModifyWriteRowAsync(mutation);
 }
 

readModifyWriteRowCallable

public com.google.api.gax.rpc.UnaryCallable<ReadModifyWriteRow,Row> readModifyWriteRowCallable()

Modifies a row atomically on the server. The method reads the latest existing timestamp and value from the specified columns and writes a new entry. The new value for the timestamp is the greater of the existing timestamp or the current server time. The method returns the new contents of all modified cells.

Sample code:

 InstanceName instanceName = InstanceName.of("[PROJECT]", "[INSTANCE]");
 try (BigtableClient bigtableClient = BigtableClient.create(instanceName)) {
   ReadModifyWriteRow mutation = ReadModifyWriteRow.create("[TABLE]", "[KEY]")
     .increment("[FAMILY]", "[QUALIFIER]", 1)
     .append("[FAMILY2]", "[QUALIFIER2]", "suffix");

   Row row = bigtableClient.readModifyWriteRowCallable().call(mutation);
 }
 

close

public void close()
           throws Exception

Close the clients and releases all associated resources.

Specified by:

close in interface AutoCloseable

Throws:

Exception