com.google.cloud.spanner

Interface BatchReadOnlyTransaction

All Superinterfaces:

AutoCloseable, ReadContext, ReadOnlyTransaction

public interface BatchReadOnlyTransaction
extends ReadOnlyTransaction

BatchReadOnlyTransaction can be configured to read at timestamps in the past and allows for exporting arbitrarily large amounts of data from Cloud Spanner databases. This is a read only transaction which additionally allows to partition a read or query request. Read/query request can then be executed independently over each partition while observing the same snapshot of the database. BatchReadOnlyTransaction can also be shared across multiple processes/machines by passing around the BatchTransactionId and then recreating the transaction using BatchClient.batchReadOnlyTransaction(BatchTransactionId).

Unlike locking read-write transactions, BatchReadOnlyTransaction never abort. They can fail if the chosen read timestamp is garbage collected; however any read or query activity within an hour on the transaction avoids garbage collection and most applications do not need to worry about this in practice.

To execute a BatchReadOnlyTransaction, specify a TimestampBound, which tells Cloud Spanner how to choose a read timestamp.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.cloud.spanner.ReadContext

ReadContext.QueryAnalyzeMode

Method Summary

Modifier and Type	Method and Description
default void	cleanup() Closes the session as part of the cleanup.
ResultSet	execute(Partition partition) Execute the partition to return ResultSet.
BatchTransactionId	getBatchTransactionId() Returns a BatchTransactionId to be re-used across several machines/processes.
List<Partition>	partitionQuery(PartitionOptions partitionOptions, Statement statement, Options.QueryOption... options) Returns a list of Partition to execute a query against the database.
List<Partition>	partitionRead(PartitionOptions partitionOptions, String table, KeySet keys, Iterable<String> columns, Options.ReadOption... options) Returns a list of Partition to read zero or more rows from a database.
List<Partition>	partitionReadUsingIndex(PartitionOptions partitionOptions, String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption... options) Returns a list of Partition to read zero or more rows from a database using an index.

Methods inherited from interface com.google.cloud.spanner.ReadOnlyTransaction

getReadTimestamp

Methods inherited from interface com.google.cloud.spanner.ReadContext

analyzeQuery, close, executeQuery, executeQueryAsync, read, readAsync, readRow, readRowAsync, readRowUsingIndex, readRowUsingIndexAsync, readUsingIndex, readUsingIndexAsync

Method Detail

partitionRead

List<Partition> partitionRead(PartitionOptions partitionOptions,
                              String table,
                              KeySet keys,
                              Iterable<String> columns,
                              Options.ReadOption... options)
                       throws SpannerException

Returns a list of Partition to read zero or more rows from a database.

These partitions can be executed across multiple processes, even across different machines. The partition size and count hints can be configured using PartitionOptions.

Parameters:

partitionOptions - configuration for size and count of partitions returned

table - the name of the table to read

keys - the keys and ranges of rows to read. Regardless of ordering in keys, rows are returned in their natural key order.

columns - the columns to read

options - the options to configure the read, supported values are Options.prefetchChunks()

 final BatchReadOnlyTransaction txn =
     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
 List<Partition> partitions =
     txn.partitionRead(
         PartitionOptions.getDefaultInstance(),
         "Singers",
         KeySet.all(),
         Arrays.asList("SingerId", "FirstName", "LastName"));
 for (final Partition p : partitions) {
   try (ResultSet results = txn.execute(p)) {
     while (results.next()) {
       long singerId = results.getLong(0);
       String firstName = results.getString(1);
       String lastName = results.getString(2);
       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
     }
   }
 }
 

Throws:

SpannerException

partitionReadUsingIndex

List<Partition> partitionReadUsingIndex(PartitionOptions partitionOptions,
                                        String table,
                                        String index,
                                        KeySet keys,
                                        Iterable<String> columns,
                                        Options.ReadOption... options)
                                 throws SpannerException

Returns a list of Partition to read zero or more rows from a database using an index.

These partitions can be executed across multiple processes, even across different machines. The partition size and count can be configured using PartitionOptions. Though it may not necessarily be honored depending on the parameters in the request.

Parameters:

partitionOptions - configuration for size and count of partitions returned

table - the name of the table to read

index - the name of the index on table to use

keys - the keys and ranges of index rows to read. Regardless of ordering in keys, rows are returned in the natural key order of the index.

columns - the columns to read

options - the options to configure the read

 final BatchReadOnlyTransaction txn =
     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
 List<Partition> partitions =
     txn.partitionReadUsingIndex(
         PartitionOptions.getDefaultInstance(),
         "Singers",
         "SingerId",
         KeySet.all(),
         Arrays.asList("SingerId", "FirstName", "LastName"));

 for (Partition p : partitions) {
   try (ResultSet results = txn.execute(p)) {
     while (results.next()) {
       long singerId = results.getLong(0);
       String firstName = results.getString(1);
       String lastName = results.getString(2);
       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
     }
   }
 }
 

Throws:

SpannerException

partitionQuery

List<Partition> partitionQuery(PartitionOptions partitionOptions,
                               Statement statement,
                               Options.QueryOption... options)
                        throws SpannerException

Returns a list of Partition to execute a query against the database.

These partitions can be executed across multiple processes, even across different machines. The partition size and count can be configured using PartitionOptions. Though it may not necessarily be honored depending on the query and options in the request.

Parameters:

partitionOptions - configuration for size and count of partitions returned

statement - the query statement to execute

options - the options to configure the query

 final BatchReadOnlyTransaction txn =
     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
 List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
     Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));

 for (final Partition p : partitions) {
   try (ResultSet results = txn.execute(p)) {
     while (results.next()) {
       long singerId = results.getLong(0);
       String firstName = results.getString(1);
       String lastName = results.getString(2);
       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
     }
   }
 }
 

Throws:

SpannerException

execute

ResultSet execute(Partition partition)
           throws SpannerException

Execute the partition to return ResultSet. The result returned could be zero or more rows. The row metadata may be absent if no rows are returned.

 final BatchReadOnlyTransaction txn =
     batchClient.batchReadOnlyTransaction(TimestampBound.strong());
 List<Partition> partitions = txn.partitionQuery(PartitionOptions.getDefaultInstance(),
     Statement.of("SELECT SingerId, FirstName, LastName FROM Singers"));

 for (final Partition p : partitions) {
   try (ResultSet results = txn.execute(p)) {
     while (results.next()) {
       long singerId = results.getLong(0);
       String firstName = results.getString(1);
       String lastName = results.getString(2);
       System.out.println("[" + singerId + "] " + firstName + " " + lastName);
     }
   }
 }
 

Throws:

SpannerException

getBatchTransactionId

BatchTransactionId getBatchTransactionId()

Returns a BatchTransactionId to be re-used across several machines/processes. This BatchTransactionId guarantees the subsequent read/query to be executed at the same timestamp.

cleanup

default void cleanup()

Closes the session as part of the cleanup. It is the responsibility of the caller to make a call to this method once the transaction completes execution across all the channels (which is understandably hard to identify). It is okay if the caller does not call the method because the backend will anyways clean up the unused session.