Class BigtableDataClient (2.7.0)

Version 2.7.0

• 2.49.0 (latest)
• 2.46.0
• 2.45.1
• 2.44.1
• 2.43.0
• 2.42.0
• 2.40.0
• 2.39.5
• 2.37.0
• 2.35.1
• 2.34.0
• 2.33.0
• 2.32.0
• 2.31.0
• 2.30.0
• 2.29.1
• 2.28.0

public class BigtableDataClient 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:

 // 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());
 

Inheritance

java.lang.Object > BigtableDataClient

Implements

AutoCloseable

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Methods

create(BigtableDataSettings settings)

public static BigtableDataClient create(BigtableDataSettings settings)

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.

Parameter

Name	Description
settings	BigtableDataSettings

Returns

Type	Description
BigtableDataClient

Exceptions

Type	Description
IOException

create(String projectId, String instanceId)

public static BigtableDataClient create(String projectId, String instanceId)

Constructs an instance of BigtableDataClient with default settings.

Parameters

Name	Description
projectId	String The project id of the instance to connect to.
instanceId	String The id of the instance to connect to.

Returns

Type	Description
BigtableDataClient	A new client.

Exceptions

Type	Description
IOException	If any.

Methods

<RowT>readRowCallable(RowAdapter<RowT> rowAdapter)

public UnaryCallable<Query,RowT> <RowT>readRowCallable(RowAdapter<RowT> rowAdapter)

Reads a single row. This callable allows for customization of the logical representation of a row. It's meant for advanced use cases.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   // Synchronous invocation
   CustomRow row = bigtableDataClient.readRowCallable(new CustomRowAdapter()).call(query));
   // Do something with row
 }
 

See Also: com.google.cloud.bigtable.data.v2.models.FiltersFor the filter building DSL., ServerStreamingCallableFor call styles., QueryFor query options.

Parameter

Name	Description
rowAdapter	RowAdapter<RowT>

Returns

Type	Description
UnaryCallable<Query,RowT>

<RowT>readRowsCallable(RowAdapter<RowT> rowAdapter)

public ServerStreamingCallable<Query,RowT> <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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   // Iterator style
   try {
     for(CustomRow row : bigtableDataClient.readRowsCallable(new CustomRowAdapter()).call(query)) {
       // Do something with row
     }
   } catch (NotFoundException e) {
     System.out.println("Tried to read a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }
 }
 

See Also: com.google.cloud.bigtable.data.v2.models.FiltersFor the filter building DSL., ServerStreamingCallableFor call styles., QueryFor query options.

Parameter

Name	Description
rowAdapter	RowAdapter<RowT>

Returns

Type	Description
ServerStreamingCallable<Query,RowT>

bulkMutateRows(BulkMutation mutation)

public void bulkMutateRows(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. This method expects the mutations to be pre-batched.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   BulkMutation batch = BulkMutation.create("[TABLE]");
   for (String someValue : someCollection) {
     batch.add("[ROW KEY]", Mutation.create().setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]"));
   }
   bigtableDataClient.bulkMutateRows(batch);
 } catch(ApiException e) {
   e.printStackTrace();
 } catch(MutateRowsException e) {
   e.printStackTrace();
 }
 

Parameter

Name	Description
mutation	BulkMutation

bulkMutateRowsAsync(BulkMutation mutation)

public 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. This method expects the mutations to be pre-batched.

Sample code:

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

   ApiFutures.addCallback(resultFuture, new ApiFutureCallback<Void>() {
     public void onFailure(Throwable t) {
       if (t instanceof BulkMutationFailure) {
         System.out.println("Some entries failed to apply");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Void ignored) {
       System.out.println("Successfully applied all mutation");
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameter

Name	Description
mutation	BulkMutation

Returns

Type	Description
ApiFuture<Void>

bulkMutationCallable()

public 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. This method expects the mutations to be pre-batched.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   BulkMutation batch = BulkMutation.create("[TABLE]");
   for (String someValue : someCollection) {
     ApiFuture<Void> entryFuture = batch.add("[ROW KEY]",
       Mutation.create().setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");
   }
   bigtableDataClient.bulkMutationCallable().call(batch);
 }
 

Returns

Type	Description
UnaryCallable<BulkMutation,Void>

checkAndMutateRow(ConditionalRowMutation mutation)

public Boolean checkAndMutateRow(ConditionalRowMutation mutation)

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

Sample code:

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

   Boolean result = bigtableDataClient.checkAndMutateRow(mutation);
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameter

Name	Description
mutation	ConditionalRowMutation

Returns

Type	Description
Boolean

checkAndMutateRowAsync(ConditionalRowMutation mutation)

public ApiFuture<Boolean> checkAndMutateRowAsync(ConditionalRowMutation mutation)

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

Sample code:

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

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

   ApiFutures.addCallback(future, new ApiFutureCallback<Boolean>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to mutate a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Boolean wasApplied) {
       System.out.println("Row was modified: " + wasApplied);
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameter

Name	Description
mutation	ConditionalRowMutation

Returns

Type	Description
ApiFuture<Boolean>

checkAndMutateRowCallable()

public UnaryCallable<ConditionalRowMutation,Boolean> checkAndMutateRowCallable()

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

Sample code:

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

   // Sync style
   try {
     boolean success = bigtableDataClient.checkAndMutateRowCallable().call(mutation);
     if (!success) {
       System.out.println("Row did not match conditions");
     }
   } catch (NotFoundException e) {
     System.out.println("Tried to mutate a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }
 }
 

Returns

Type	Description
UnaryCallable<ConditionalRowMutation,Boolean>

close()

public void close()

Close the clients and releases all associated resources.

exists(String tableId, ByteString rowKey)

public boolean exists(String tableId, ByteString rowKey)

Confirms synchronously if given row key exists or not.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";
   ByteString key = ByteString.copyFromUtf8("key");

   boolean isRowPresent = bigtableDataClient.exists(tableId, key);

   // Do something with result, for example, display a message
   if(isRowPresent) {
     System.out.println(key.toStringUtf8() + " is present");
   }
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameters

Name	Description
tableId	String
rowKey	ByteString

Returns

Type	Description
boolean

exists(String tableId, String rowKey)

public boolean exists(String tableId, String rowKey)

Confirms synchronously if given row key exists or not.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";
   String key = "key";

   boolean isRowPresent = bigtableDataClient.exists(tableId, key);

   // Do something with result, for example, display a message
   if(isRowPresent) {
     System.out.println(key + " is present");
   }
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameters

Name	Description
tableId	String
rowKey	String

Returns

Type	Description
boolean

existsAsync(String tableId, ByteString rowKey)

public ApiFuture<Boolean> existsAsync(String tableId, ByteString rowKey)

Confirms asynchronously if given row key exists or not.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";
   final ByteString key = ByteString.copyFromUtf8("key");

   ApiFuture<Boolean> futureResult = bigtableDataClient.existsAsync(tableId, key);

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Boolean>() {
     public void onFailure(Throwable t) {
       t.printStackTrace();
     }
     public void onSuccess(Boolean isRowPresent) {
       if(isRowPresent) {
         System.out.println(key.toStringUtf8() + " is present");
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	ByteString

Returns

Type	Description
ApiFuture<Boolean>

existsAsync(String tableId, String rowKey)

public ApiFuture<Boolean> existsAsync(String tableId, String rowKey)

Confirms asynchronously if given row key exists or not.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";
   final String key = "key";

   ApiFuture<Boolean> futureResult = bigtableDataClient.existsAsync(tableId, key);

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Boolean>() {
     public void onFailure(Throwable t) {
       t.printStackTrace();
     }
     public void onSuccess(Boolean isRowPresent) {
       if(isRowPresent) {
         System.out.println(key + " is present");
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	String

Returns

Type	Description
ApiFuture<Boolean>

mutateRow(RowMutation rowMutation)

public void mutateRow(RowMutation rowMutation)

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

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
     .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

   bigtableDataClient.mutateRow(mutation);
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameter

Name	Description
rowMutation	RowMutation

mutateRowAsync(RowMutation rowMutation)

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
     .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

   ApiFuture<Void> future = bigtableDataClient.mutateRowAsync(mutation);

   ApiFutures.addCallback(future, new ApiFutureCallback<Void>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to mutate a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Void ignored) {
       System.out.println("Successfully applied mutation");
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameter

Name	Description
rowMutation	RowMutation

Returns

Type	Description
ApiFuture<Void>

mutateRowCallable()

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   RowMutation mutation = RowMutation.create("[TABLE]", "[ROW KEY]")
     .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]");

   // Sync style
   try {
     bigtableDataClient.mutateRowCallable().call(mutation);
   } catch (NotFoundException e) {
     System.out.println("Tried to mutate a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }
 }
 

Returns

Type	Description
UnaryCallable<RowMutation,Void>

newBulkMutationBatcher(String tableId)

public Batcher<RowMutationEntry,Void> newBulkMutationBatcher(String tableId)

Mutates multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically. The returned Batcher instance is not threadsafe, it can only be used from single thread.

Sample Code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   try (Batcher<RowMutationEntry, Void> batcher = bigtableDataClient.newBulkMutationBatcher("[TABLE]")) {
     for (String someValue : someCollection) {
       ApiFuture<Void> entryFuture =
           batcher.add(
               RowMutationEntry.create("[ROW KEY]")
                   .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]"));
     }

     // Blocks until mutations are applied on all submitted row entries.
     batcher.flush();
   }
   // Before batcher is closed, all remaining(If any) mutations are applied.
 }
 

Parameter

Name	Description
tableId	String

Returns

Type	Description
Batcher<RowMutationEntry,Void>

newBulkMutationBatcher(String tableId, GrpcCallContext ctx)

public Batcher<RowMutationEntry,Void> newBulkMutationBatcher(String tableId, GrpcCallContext ctx)

Mutates multiple rows in a batch. Each individual row is mutated atomically as in MutateRow, but the entire batch is not executed atomically. The returned Batcher instance is not threadsafe, it can only be used from single thread. This method allows customization of the underlying RPCs by passing in a com.google.api.gax.grpc.GrpcCallContext. The same context will be reused for all batches. This can be used to customize things like per attempt timeouts.

Sample Code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   try (Batcher<RowMutationEntry, Void> batcher = bigtableDataClient.newBulkMutationBatcher("[TABLE]", GrpcCallContext.createDefault().withTimeout(Duration.ofSeconds(10)))) {
     for (String someValue : someCollection) {
       ApiFuture<Void> entryFuture =
           batcher.add(
               RowMutationEntry.create("[ROW KEY]")
                   .setCell("[FAMILY NAME]", "[QUALIFIER]", "[VALUE]"));
     }

     // Blocks until mutations are applied on all submitted row entries.
     batcher.flush();
   }
   // Before batcher is closed, all remaining(If any) mutations are applied.
 }
 

Parameters

Name	Description
tableId	String
ctx	GrpcCallContext

Returns

Type	Description
Batcher<RowMutationEntry,Void>

newBulkReadRowsBatcher(String tableId)

public Batcher<ByteString,Row> newBulkReadRowsBatcher(String tableId)

Reads rows for given tableId in a batch. If the row does not exist, the value will be null. The returned Batcher instance is not threadsafe, it can only be used from a single thread.

Performance notice: The ReadRows protocol requires that rows are sent in ascending key order, which means that the keys are processed sequentially on the server-side, so batching allows improving throughput but not latency. Lower latencies can be achieved by sending smaller requests concurrently.

Sample Code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   List<ApiFuture<Row>> rows = new ArrayList<>();

   try (Batcher<ByteString, Row> batcher = bigtableDataClient.newBulkReadRowsBatcher("[TABLE]")) {
     for (String someValue : someCollection) {
       ApiFuture<Row> rowFuture =
           batcher.add(ByteString.copyFromUtf8("[ROW KEY]"));
       rows.add(rowFuture);
     }

     // [Optional] Sends collected elements for batching asynchronously.
     batcher.sendOutstanding();

     // [Optional] Invokes sendOutstanding() and awaits until all pending entries are resolved.
     batcher.flush();
   }
   // batcher.close() invokes flush() which will in turn invoke sendOutstanding() with await for
   pending batches until its resolved.

   List<Row> actualRows = ApiFutures.allAsList(rows).get();
 }
 

Parameter

Name	Description
tableId	String

Returns

Type	Description
Batcher<ByteString,Row>

newBulkReadRowsBatcher(String tableId, Filters.Filter filter)

public Batcher<ByteString,Row> newBulkReadRowsBatcher(String tableId, Filters.Filter filter)

Reads rows for given tableId and filter criteria in a batch. If the row does not exist, the value will be null. The returned Batcher instance is not threadsafe, it can only be used from a single thread.

Performance notice: The ReadRows protocol requires that rows are sent in ascending key order, which means that the keys are processed sequentially on the server-side, so batching allows improving throughput but not latency. Lower latencies can be achieved by sending smaller requests concurrently.

Sample Code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {

  // Build the filter expression
  Filter filter = FILTERS.chain()
         .filter(FILTERS.key().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   List<ApiFuture<Row>> rows = new ArrayList<>();

   try (Batcher<ByteString, Row> batcher = bigtableDataClient.newBulkReadRowsBatcher("[TABLE]", filter)) {
     for (String someValue : someCollection) {
       ApiFuture<Row> rowFuture =
           batcher.add(ByteString.copyFromUtf8("[ROW KEY]"));
       rows.add(rowFuture);
     }

     // [Optional] Sends collected elements for batching asynchronously.
     batcher.sendOutstanding();

     // [Optional] Invokes sendOutstanding() and awaits until all pending entries are resolved.
     batcher.flush();
   }
   // batcher.close() invokes flush() which will in turn invoke sendOutstanding() with await for
   pending batches until its resolved.

   List<Row> actualRows = ApiFutures.allAsList(rows).get();
 }
 

Parameters

Name	Description
tableId	String
filter	Filters.Filter

Returns

Type	Description
Batcher<ByteString,Row>

newBulkReadRowsBatcher(String tableId, Filters.Filter filter, GrpcCallContext ctx)

public Batcher<ByteString,Row> newBulkReadRowsBatcher(String tableId, Filters.Filter filter, GrpcCallContext ctx)

Reads rows for given tableId and filter criteria in a batch. If the row does not exist, the value will be null. The returned Batcher instance is not threadsafe, it can only be used from a single thread. This method allows customization of the underlying RPCs by passing in a com.google.api.gax.grpc.GrpcCallContext. The same context will be reused for all batches. This can be used to customize things like per attempt timeouts.

Performance notice: The ReadRows protocol requires that rows are sent in ascending key order, which means that the keys are processed sequentially on the server-side, so batching allows improving throughput but not latency. Lower latencies can be achieved by sending smaller requests concurrently.

Sample Code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {

  // Build the filter expression
  Filter filter = FILTERS.chain()
         .filter(FILTERS.key().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   List<ApiFuture<Row>> rows = new ArrayList<>();

   try (Batcher<ByteString, Row> batcher = bigtableDataClient.newBulkReadRowsBatcher(
    "[TABLE]", filter, GrpcCallContext.createDefault().withTimeout(Duration.ofSeconds(10)))) {
     for (String someValue : someCollection) {
       ApiFuture<Row> rowFuture =
           batcher.add(ByteString.copyFromUtf8("[ROW KEY]"));
       rows.add(rowFuture);
     }

     // [Optional] Sends collected elements for batching asynchronously.
     batcher.sendOutstanding();

     // [Optional] Invokes sendOutstanding() and awaits until all pending entries are resolved.
     batcher.flush();
   }
   // batcher.close() invokes flush() which will in turn invoke sendOutstanding() with await for
   pending batches until its resolved.

   List<Row> actualRows = ApiFutures.allAsList(rows).get();
 }
 

Parameters

Name	Description
tableId	String
filter	Filters.Filter
ctx	GrpcCallContext

Returns

Type	Description
Batcher<ByteString,Row>

readModifyWriteRow(ReadModifyWriteRow mutation)

public Row readModifyWriteRow(ReadModifyWriteRow mutation)

Convenience method that synchronously 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   ReadModifyWriteRow mutation = ReadModifyWriteRow.create("[TABLE]", "[KEY]")
     .increment("[FAMILY]", "[QUALIFIER]", 1)
     .append("[FAMILY2]", "[QUALIFIER2]", "suffix");

   Row success = bigtableDataClient.readModifyWriteRow(mutation);
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameter

Name	Description
mutation	ReadModifyWriteRow

Returns

Type	Description
Row

readModifyWriteRowAsync(ReadModifyWriteRow mutation)

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   ReadModifyWriteRow mutation = ReadModifyWriteRow.create("[TABLE]", "[KEY]")
     .increment("[FAMILY]", "[QUALIFIER]", 1)
     .append("[FAMILY2]", "[QUALIFIER2]", "suffix");

   ApiFuture<Row> rowFuture = bigtableDataClient.readModifyWriteRowAsync(mutation);

   ApiFutures.addCallback(rowFuture, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to mutate a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row resultingRow) {
       System.out.println("Resulting row: " + resultingRow);
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameter

Name	Description
mutation	ReadModifyWriteRow

Returns

Type	Description
ApiFuture<Row>

readModifyWriteRowCallable()

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   ReadModifyWriteRow mutation = ReadModifyWriteRow.create("[TABLE]", "[KEY]")
     .increment("[FAMILY]", "[QUALIFIER]", 1)
     .append("[FAMILY2]", "[QUALIFIER2]", "suffix");

   try {
     Row row = bigtableDataClient.readModifyWriteRowCallable().call(mutation);
   } catch (NotFoundException e) {
     System.out.println("Tried to mutate a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }
 }
 

Returns

Type	Description
UnaryCallable<ReadModifyWriteRow,Row>

readRow(String tableId, ByteString rowKey)

public Row readRow(String tableId, ByteString rowKey)

Convenience method for synchronously reading a single row. If the row does not exist, the value will be null.

Sample code:

{code try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) { String tableId = "[TABLE]";

Row row = bigtableDataClient.readRow(tableId, ByteString.copyFromUtf8("key")); // Do something with row, for example, display all cells if(row != null) { System.out.println(row.getKey().toStringUtf8()); for(RowCell cell : row.getCells()) { System.out.printf("Family: %s Qualifier: %s Value: %s", cell.getFamily(), cell.getQualifier().toStringUtf8(), cell.getValue().toStringUtf8()); } } } catch(ApiException e) { e.printStackTrace(); } }

Parameters

Name	Description
tableId	String
rowKey	ByteString

Returns

Type	Description
Row

readRow(String tableId, ByteString rowKey, Filters.Filter filter)

public Row readRow(String tableId, ByteString rowKey, Filters.Filter filter)

Convenience method for synchronously reading a single row. If the row does not exist, the value will be null.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

  // Build the filter expression
  Filter filter = FILTERS.chain()
         .filter(FILTERS.qualifier().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   Row row = bigtableDataClient.readRow(tableId, ByteString.copyFromUtf8("key"), filter);
   // Do something with row, for example, display all cells
   if(row != null) {
     System.out.println(row.getKey().toStringUtf8());
      for(RowCell cell : row.getCells()) {
        System.out.printf("Family: %s   Qualifier: %s   Value: %s", cell.getFamily(),
           cell.getQualifier().toStringUtf8(), cell.getValue().toStringUtf8());
      }
   }
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameters

Name	Description
tableId	String
rowKey	ByteString
filter	Filters.Filter

Returns

Type	Description
Row

readRow(String tableId, String rowKey)

public Row readRow(String tableId, String rowKey)

Convenience method for synchronously reading a single row. If the row does not exist, the value will be null.

Sample code:

{code try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) { String tableId = "[TABLE]";

Row row = bigtableDataClient.readRow(tableId, "key"); // Do something with row, for example, display all cells if(row != null) { System.out.println(row.getKey().toStringUtf8()); for(RowCell cell : row.getCells()) { System.out.printf("Family: %s Qualifier: %s Value: %s", cell.getFamily(), cell.getQualifier().toStringUtf8(), cell.getValue().toStringUtf8()); } } } catch(ApiException e) { e.printStackTrace(); } }

Parameters

Name	Description
tableId	String
rowKey	String

Returns

Type	Description
Row

readRow(String tableId, String rowKey, Filters.Filter filter)

public Row readRow(String tableId, String rowKey, Filters.Filter filter)

Convenience method for synchronously reading a single row. If the row does not exist, the value will be null.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

  // Build the filter expression
  Filter filter = FILTERS.chain()
         .filter(FILTERS.qualifier().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   Row row = bigtableDataClient.readRow(tableId, "key", filter);
   // Do something with row, for example, display all cells
   if(row != null) {
     System.out.println(row.getKey().toStringUtf8());
      for(RowCell cell : row.getCells()) {
        System.out.printf("Family: %s   Qualifier: %s   Value: %s", cell.getFamily(),
           cell.getQualifier().toStringUtf8(), cell.getValue().toStringUtf8());
      }
   }
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameters

Name	Description
tableId	String
rowKey	String
filter	Filters.Filter

Returns

Type	Description
Row

readRowAsync(String tableId, ByteString rowKey)

public ApiFuture<Row> readRowAsync(String tableId, 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

   ApiFuture<Row> futureResult = bigtableDataClient.readRowAsync(tableId,  ByteString.copyFromUtf8("key"));

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row row) {
       if (result != null) {
          System.out.println("Got row: " + result);
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	ByteString

Returns

Type	Description
ApiFuture<Row>

readRowAsync(String tableId, ByteString rowKey, Filters.Filter filter)

public ApiFuture<Row> readRowAsync(String tableId, ByteString rowKey, Filters.Filter filter)

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

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

  // Build the filter expression
  Filters.Filter filter = FILTERS.chain()
         .filter(FILTERS.qualifier().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   ApiFuture<Row> futureResult = bigtableDataClient.readRowAsync(tableId, ByteString.copyFromUtf8("key"), filter);

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row row) {
       if (result != null) {
          System.out.println("Got row: " + result);
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	ByteString
filter	Filters.Filter

Returns

Type	Description
ApiFuture<Row>

readRowAsync(String tableId, String rowKey)

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

   ApiFuture<Row> futureResult = bigtableDataClient.readRowAsync(tableId,  "key");

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row result) {
       if (result != null) {
          System.out.println("Got row: " + result);
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	String

Returns

Type	Description
ApiFuture<Row>

readRowAsync(String tableId, String rowKey, Filters.Filter filter)

public ApiFuture<Row> readRowAsync(String tableId, String rowKey, Filters.Filter filter)

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

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

  // Build the filter expression
   Filters.Filter filter = FILTERS.chain()
         .filter(FILTERS.qualifier().regex("prefix.*"))
         .filter(FILTERS.limit().cellsPerRow(10));

   ApiFuture<Row> futureResult = bigtableDataClient.readRowAsync(tableId, "key", filter);

   ApiFutures.addCallback(futureResult, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row row) {
       if (result != null) {
          System.out.println("Got row: " + result);
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameters

Name	Description
tableId	String
rowKey	String
filter	Filters.Filter

Returns

Type	Description
ApiFuture<Row>

readRowCallable()

public UnaryCallable<Query,Row> readRowCallable()

Reads a single row. The returned callable object allows for customization of api invocation.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   // Synchronous invocation
   try {
     Row row = bigtableDataClient.readRowCallable().call(query);
     if (row == null) {
       System.out.println("Row not found");
     }
   } catch (RuntimeException e) {
     e.printStackTrace();
   }

   // Asynchronous invocation
   ApiFuture<Row> rowFuture = bigtableDataClient.readRowCallable().futureCall(query);

   ApiFutures.addCallback(rowFuture, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row row) {
       if (row == null) {
         System.out.println("Row not found");
       }
     }
   }, MoreExecutors.directExecutor());
 }
 

See Also: UnaryCallableFor call styles., com.google.cloud.bigtable.data.v2.models.FiltersFor the filter building DSL., QueryFor query options.

Returns

Type	Description
UnaryCallable<Query,Row>

readRows(Query query)

public ServerStream<Row> readRows(Query query)

Convenience method for synchronously streaming the results of a Query. The returned ServerStream instance is not threadsafe, it can only be used from single thread.

Sample code:

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

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   try {
     ServerStream<Row> stream = bigtableDataClient.readRows(query);
     int count = 0;

     // Iterator style
     for (Row row : stream) {
       if (++count > 10) {
         stream.cancel();
         break;
       }
       // Do something with row
     }
   } catch (NotFoundException e) {
     System.out.println("Tried to read a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }
 }
 

See Also: com.google.cloud.bigtable.data.v2.models.FiltersFor the filter building DSL., ServerStreamingCallableFor call styles., QueryFor query options.

Parameter

Name	Description
query	Query

Returns

Type	Description
ServerStream<Row>

readRowsAsync(Query query, ResponseObserver<Row> observer)

public void readRowsAsync(Query query, ResponseObserver<Row> observer)

Convenience method for asynchronously streaming the results of a Query.

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   bigtableDataClient.readRowsAsync(query, new ResponseObserver<Row>() {
     StreamController controller;
     int count = 0;

     public void onStart(StreamController controller) {
       this.controller = controller;
     }
     public void onResponse(Row row) {
       if (++count > 10) {
         controller.cancel();
         return;
       }
       // Do something with Row
     }
     public void onError(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onComplete() {
       // Handle stream completion
     }
   });
 }
 

Parameters

Name	Description
query	Query
observer	ResponseObserver<Row>

readRowsCallable()

public ServerStreamingCallable<Query,Row> readRowsCallable()

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

Sample code:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE]";

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

   // Iterator style
   try {
     for(Row row : bigtableDataClient.readRowsCallable().call(query)) {
       // Do something with row
     }
   } catch (NotFoundException e) {
     System.out.println("Tried to read a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }

   // Sync style
   try {
     List<Row> rows = bigtableDataClient.readRowsCallable().all().call(query);
   } catch (NotFoundException e) {
     System.out.println("Tried to read a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }

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

   ApiFutures.addCallback(rowFuture, new ApiFutureCallback<Row>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to read a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(Row result) {
       System.out.println("Got row: " + result);
     }
   }, MoreExecutors.directExecutor());

   // etc
 }
 

See Also: com.google.cloud.bigtable.data.v2.models.FiltersFor the filter building DSL., ServerStreamingCallableFor call styles., QueryFor query options.

Returns

Type	Description
ServerStreamingCallable<Query,Row>

sampleRowKeys(String tableId)

public List<KeyOffset> sampleRowKeys(String tableId)

Convenience method to synchronously 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   String tableId = "[TABLE_ID]";

   List<KeyOffset> keyOffsets = bigtableDataClient.sampleRowKeys(tableId);
   for(KeyOffset keyOffset : keyOffsets) {
   // Do something with keyOffset
   }
 } catch(ApiException e) {
   e.printStackTrace();
 }
 

Parameter

Name	Description
tableId	String

Returns

Type	Description
List<KeyOffset>

sampleRowKeysAsync(String tableId)

public 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:

 try (BigtableClient bigtableDataClient = BigtableClient.create("[PROJECT]", "[INSTANCE]")) {
   ApiFuture<List<KeyOffset>> keyOffsetsFuture = bigtableClient.sampleRowKeysAsync("[TABLE]");

   ApiFutures.addCallback(keyOffsetsFuture, new ApiFutureCallback<List<KeyOffset>>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to sample keys of a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(List<KeyOffset> keyOffsets) {
       System.out.println("Got key offsets: " + keyOffsets);
     }
   }, MoreExecutors.directExecutor());
 }
 

Parameter

Name	Description
tableId	String

Returns

Type	Description
ApiFuture<List<KeyOffset>>

sampleRowKeysCallable()

public 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:

 try (BigtableDataClient bigtableDataClient = BigtableDataClient.create("[PROJECT]", "[INSTANCE]")) {
   // Synchronous invocation
   try {
     List<KeyOffset> keyOffsets = bigtableDataClient.sampleRowKeysCallable().call("[TABLE]");
   } catch (NotFoundException e) {
     System.out.println("Tried to sample keys of a non-existent table");
   } catch (RuntimeException e) {
     e.printStackTrace();
   }

   // Asynchronous invocation
   ApiFuture<List<KeyOffset>> keyOffsetsFuture = bigtableDataClient.sampleRowKeysCallable().futureCall("[TABLE]");

   ApiFutures.addCallback(keyOffsetsFuture, new ApiFutureCallback<List<KeyOffset>>() {
     public void onFailure(Throwable t) {
       if (t instanceof NotFoundException) {
         System.out.println("Tried to sample keys of a non-existent table");
       } else {
         t.printStackTrace();
       }
     }
     public void onSuccess(List<KeyOffset> keyOffsets) {
       System.out.println("Got key offsets: " + keyOffsets);
     }
   }, MoreExecutors.directExecutor());
 }
 

Returns

Type	Description
UnaryCallable<String,List<KeyOffset>>