Interface ReadContext (6.124.0)

6.124.0 (latest) 6.120.0 6.119.0 6.118.0 6.116.0 6.111.1 6.108.0 6.107.0 6.103.0 6.102.1 6.101.1 6.100.0 6.99.0 6.98.1 6.97.1 6.96.1 6.95.1 6.94.0 6.93.0 6.89.0 6.88.0 6.87.0 6.86.0 6.85.0 6.83.0 6.82.0 6.80.1 6.79.0 6.77.0 6.74.1 6.72.0 6.71.0 6.69.0 6.68.0 6.66.0 6.65.1 6.62.0 6.60.0 6.58.0 6.57.0 6.56.0 6.55.0 6.54.0 6.53.0 6.52.1 6.51.0 6.50.1 6.49.0 6.25.1 6.24.0 6.23.4 6.22.0 6.21.2 6.20.0 6.19.1 6.18.0 6.17.4 6.14.1

public interface ReadContext extends AutoCloseable

A concurrency context in which to run a read or SQL statement. All ReadContexts are implicitly bound to a Session and therefore a particular Database.

Implements

AutoCloseable

Methods

analyzeQuery(Statement statement, ReadContext.QueryAnalyzeMode queryMode)

public abstract ResultSet analyzeQuery(Statement statement, ReadContext.QueryAnalyzeMode queryMode)

Analyzes a query and returns query plan and/or query execution statistics information.

The query plan and query statistics information is contained in com.google.spanner.v1.ResultSetStats that can be accessed by calling ResultSet#getStats() on the returned ResultSet.

 ReadContext rc = dbClient.singleUse();
 ResultSet resultSet =
     rc.analyzeQuery(
         Statement.of("SELECT SingerId, AlbumId, MarketingBudget FROM Albums"),
         ReadContext.QueryAnalyzeMode.PROFILE);
 while (resultSet.next()) {
   // Discard the results. We're only processing because getStats() below requires it.
   resultSet.getCurrentRowAsStruct();
 }
 ResultSetStats stats = resultSet.getStats();
 

Parameters
Name	Description
statement	Statement the query statement to execute
queryMode	ReadContext.QueryAnalyzeMode the mode in which to execute the query

Returns
Type	Description
ResultSet

close()

public abstract void close()

Closes this read context.

closeAsync()

public default ApiFuture<Void> closeAsync()

Closes this read context asynchronously.

For read contexts with pending asynchronous operations (such as multi-use read-only transactions with background queries initializing), the returned future will complete once all pending starts have completed and the read context has been closed.

Callers must either consume or close all AsyncResultSet instances created on this read context; otherwise, unconsumed and unclosed result sets may prevent closeAsync() from completing.

Returns
Type	Description
ApiFuture<Void>	an ApiFuture that is done when the read context has been closed.

executeQuery(Statement statement, Options.QueryOption[] options)

public abstract ResultSet executeQuery(Statement statement, Options.QueryOption[] options)

Executes a query against the database. Can also execute a DML statement with returning clause in a read/write transaction.

Implementations may or may not block in the initial executeQuery(...) call; for those that do not, the remote call will be initiated immediately but blocking on the response is deferred to the first ResultSet#next() call. Regardless of blocking behavior, any SpannerException is deferred to the first or subsequent ResultSet#next() call.

 // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
 // null.
 ReadContext readContext = dbClient.singleUse();
 ResultSet resultSet =
     readContext.executeQuery(
         Statement.of(
             "SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime FROM Albums"));
 

Parameters
Name	Description
statement	Statement the query statement to execute
options	QueryOption[] the options to configure the query

Returns
Type	Description
ResultSet

executeQueryAsync(Statement statement, Options.QueryOption[] options)

public abstract AsyncResultSet executeQueryAsync(Statement statement, Options.QueryOption[] options)

Same as #executeQuery(Statement, QueryOption...), but is guaranteed to be non-blocking and returns its results as an AsyncResultSet.

Parameters
Name	Description
statement	Statement
options	QueryOption[]

Returns
Type	Description
AsyncResultSet

read(String table, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

public abstract ResultSet read(String table, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

Reads zero or more rows from a database.

Implementations may or may not block in the initial read(...) call; for those that do not, the remote call will be initiated immediately but blocking on the response is deferred to the first ResultSet#next() call. Regardless of blocking behavior, any SpannerException is deferred to the first or subsequent ResultSet#next() call.

 ReadContext readContext = dbClient.singleUse();
 ResultSet resultSet =
     readContext.read(
         "Albums",
         // KeySet.all() can be used to read all rows in a table. KeySet exposes other
         // methods to read only a subset of the table.
         KeySet.all(),
         Arrays.asList("SingerId", "AlbumId", "AlbumTitle"));
 

Parameters
Name	Description
table	String the name of the table to read
keys	KeySet the keys and ranges of rows to read. Regardless of ordering in keys, rows are returned in their natural key order.
columns	Iterable<String> the columns to read
options	ReadOption[] the options to configure the read

Returns
Type	Description
ResultSet

readAsync(String table, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

public abstract AsyncResultSet readAsync(String table, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

Same as #read(String, KeySet, Iterable, ReadOption...), but is guaranteed to be non-blocking and will return the results as an AsyncResultSet.

Parameters
Name	Description
table	String
keys	KeySet
columns	Iterable<String>
options	ReadOption[]

Returns
Type	Description
AsyncResultSet

readRow(String table, Key key, Iterable<String> columns)

public abstract Struct readRow(String table, Key key, Iterable<String> columns)

Reads a single row from a database, returning null if the row does not exist.

 ReadContext readContext = dbClient.singleUse();
 Struct row =
     readContext.readRow("Albums", Key.of(2, 1), Arrays.asList("MarketingBudget"));
 

Parameters
Name	Description
table	String the name of the table to read
key	Key the row to read
columns	Iterable<String> the columns to return

Returns
Type	Description
Struct

readRowAsync(String table, Key key, Iterable<String> columns)

public abstract ApiFuture<Struct> readRowAsync(String table, Key key, Iterable<String> columns)

Same as #readRow(String, Key, Iterable), but is guaranteed to be non-blocking.

Parameters
Name	Description
table	String
key	Key
columns	Iterable<String>

Returns
Type	Description
ApiFuture<Struct>

readRowUsingIndex(String table, String index, Key key, Iterable<String> columns)

public abstract Struct readRowUsingIndex(String table, String index, Key key, Iterable<String> columns)

Reads a single row from a database using an index, returning null if the row does not exist.

 ReadContext readContext = dbClient.singleUse();
 Struct row =
     readContext.readRowUsingIndex("Albums", "AlbumsByAlbumId", Key.of(1, "Green"),
         Arrays.asList("AlbumId", "AlbumTitle"));
 

Parameters
Name	Description
table	String the name of the table to read
index	String the name of the index on table to use
key	Key the index row to read
columns	Iterable<String> the columns to return

Returns
Type	Description
Struct

readRowUsingIndexAsync(String table, String index, Key key, Iterable<String> columns)

public abstract ApiFuture<Struct> readRowUsingIndexAsync(String table, String index, Key key, Iterable<String> columns)

Same as #readRowUsingIndex(String, String, Key, Iterable), but is guaranteed to be non-blocking.

Parameters
Name	Description
table	String
index	String
key	Key
columns	Iterable<String>

Returns
Type	Description
ApiFuture<Struct>

readUsingIndex(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

public abstract ResultSet readUsingIndex(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

Reads zero or more rows from a database using an index.

Implementations may or may not block in the initial read(...) call; for those that do not, the remote call will be initiated immediately but blocking on the response is deferred to the first ResultSet#next() call. Regardless of blocking behavior, any SpannerException is deferred to the first or subsequent ResultSet#next() call.

 ReadContext readContext = dbClient.singleUse();
 Struct row =
     readContext.readRowUsingIndex("Albums", "AlbumsByAlbumId", Key.of(1, "Green"),
         Arrays.asList("AlbumId", "AlbumTitle"));
 

Parameters
Name	Description
table	String the name of the table to read
index	String the name of the index on table to use
keys	KeySet 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	Iterable<String> the columns to read
options	ReadOption[] the options to configure the read

Returns
Type	Description
ResultSet

readUsingIndexAsync(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

public abstract AsyncResultSet readUsingIndexAsync(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption[] options)

Same as #readUsingIndex(String, String, KeySet, Iterable, ReadOption...), but is guaranteed to be non-blocking and will return its results as an AsyncResultSet.

Parameters
Name	Description
table	String
index	String
keys	KeySet
columns	Iterable<String>
options	ReadOption[]

Returns
Type	Description
AsyncResultSet