Interface ReadContext (6.55.0)

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 and frees up the underlying resources.

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.


 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`