Interface ReadContext
-
- All Superinterfaces:
AutoCloseable
- All Known Subinterfaces:
BatchReadOnlyTransaction
,ReadOnlyTransaction
,TransactionContext
public interface ReadContext extends AutoCloseable
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
ReadContext.QueryAnalyzeMode
Used to specify the mode in which the query should be analyzed byanalyzeQuery(Statement,QueryAnalyzeMode)
.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ResultSet
analyzeQuery(Statement statement, ReadContext.QueryAnalyzeMode queryMode)
Analyzes a query and returns query plan and/or query execution statistics information.void
close()
Closes this read context and frees up the underlying resources.ResultSet
executeQuery(Statement statement, Options.QueryOption... options)
Executes a query against the database.AsyncResultSet
executeQueryAsync(Statement statement, Options.QueryOption... options)
Same asexecuteQuery(Statement, QueryOption...)
, but is guaranteed to be non-blocking and returns its results as anAsyncResultSet
.ResultSet
read(String table, KeySet keys, Iterable<String> columns, Options.ReadOption... options)
Reads zero or more rows from a database.AsyncResultSet
readAsync(String table, KeySet keys, Iterable<String> columns, Options.ReadOption... options)
Same asread(String, KeySet, Iterable, ReadOption...)
, but is guaranteed to be non-blocking and will return the results as anAsyncResultSet
.Struct
readRow(String table, Key key, Iterable<String> columns)
Reads a single row from a database, returningnull
if the row does not exist.com.google.api.core.ApiFuture<Struct>
readRowAsync(String table, Key key, Iterable<String> columns)
Same asreadRow(String, Key, Iterable)
, but is guaranteed to be non-blocking.Struct
readRowUsingIndex(String table, String index, Key key, Iterable<String> columns)
Reads a single row from a database using an index, returningnull
if the row does not exist.com.google.api.core.ApiFuture<Struct>
readRowUsingIndexAsync(String table, String index, Key key, Iterable<String> columns)
Same asreadRowUsingIndex(String, String, Key, Iterable)
, but is guaranteed to be non-blocking.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.AsyncResultSet
readUsingIndexAsync(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption... options)
Same asreadUsingIndex(String, String, KeySet, Iterable, ReadOption...)
, but is guaranteed to be non-blocking and will return its results as anAsyncResultSet
.
-
-
-
Method Detail
-
read
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 firstResultSet.next()
call. Regardless of blocking behavior, anySpannerException
is deferred to the first or subsequentResultSet.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:
table
- the name of the table to readkeys
- the keys and ranges of rows to read. Regardless of ordering inkeys
, rows are returned in their natural key order.columns
- the columns to readoptions
- the options to configure the read
-
readAsync
AsyncResultSet readAsync(String table, KeySet keys, Iterable<String> columns, Options.ReadOption... options)
Same asread(String, KeySet, Iterable, ReadOption...)
, but is guaranteed to be non-blocking and will return the results as anAsyncResultSet
.
-
readUsingIndex
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 firstResultSet.next()
call. Regardless of blocking behavior, anySpannerException
is deferred to the first or subsequentResultSet.next()
call.ReadContext readContext = dbClient.singleUse(); Struct row = readContext.readRowUsingIndex("Albums", "AlbumsByAlbumId", Key.of(1, "Green"), Arrays.asList("AlbumId", "AlbumTitle"));
- Parameters:
table
- the name of the table to readindex
- the name of the index ontable
to usekeys
- the keys and ranges of index rows to read. Regardless of ordering inkeys
, rows are returned in the natural key order of the index.columns
- the columns to readoptions
- the options to configure the read
-
readUsingIndexAsync
AsyncResultSet readUsingIndexAsync(String table, String index, KeySet keys, Iterable<String> columns, Options.ReadOption... options)
Same asreadUsingIndex(String, String, KeySet, Iterable, ReadOption...)
, but is guaranteed to be non-blocking and will return its results as anAsyncResultSet
.
-
readRow
@Nullable Struct readRow(String table, Key key, Iterable<String> columns)
Reads a single row from a database, returningnull
if the row does not exist.ReadContext readContext = dbClient.singleUse(); Struct row = readContext.readRow("Albums", Key.of(2, 1), Arrays.asList("MarketingBudget"));
- Parameters:
table
- the name of the table to readkey
- the row to readcolumns
- the columns to return
-
readRowAsync
com.google.api.core.ApiFuture<Struct> readRowAsync(String table, Key key, Iterable<String> columns)
Same asreadRow(String, Key, Iterable)
, but is guaranteed to be non-blocking.
-
readRowUsingIndex
@Nullable Struct readRowUsingIndex(String table, String index, Key key, Iterable<String> columns)
Reads a single row from a database using an index, returningnull
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:
table
- the name of the table to readindex
- the name of the index ontable
to usekey
- the index row to readcolumns
- the columns to return
-
readRowUsingIndexAsync
com.google.api.core.ApiFuture<Struct> readRowUsingIndexAsync(String table, String index, Key key, Iterable<String> columns)
Same asreadRowUsingIndex(String, String, Key, Iterable)
, but is guaranteed to be non-blocking.
-
executeQuery
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 firstResultSet.next()
call. Regardless of blocking behavior, anySpannerException
is deferred to the first or subsequentResultSet.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:
statement
- the query statement to executeoptions
- the options to configure the query
-
executeQueryAsync
AsyncResultSet executeQueryAsync(Statement statement, Options.QueryOption... options)
Same asexecuteQuery(Statement, QueryOption...)
, but is guaranteed to be non-blocking and returns its results as anAsyncResultSet
.
-
analyzeQuery
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
ResultSetStats
that can be accessed by callingResultSet.getStats()
on the returnedResultSet
.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:
statement
- the query statement to executequeryMode
- the mode in which to execute the query
-
close
void close()
Closes this read context and frees up the underlying resources.- Specified by:
close
in interfaceAutoCloseable
-
-