google::cloud::spanner::Client Class Reference

Performs database client operations on Spanner. More...

#include <google/cloud/spanner/client.h>

Public Member Functions
	Client (std::shared_ptr< Connection > conn, Options opts={})
	Constructs a Client object using the specified conn and opts. More...
	Client ()=delete
	No default construction. More...
RowStream	Read (std::string table, KeySet keys, std::vector< std::string > columns, Options opts={})
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction::SingleUseOptions transaction_options, std::string table, KeySet keys, std::vector< std::string > columns, Options opts={})
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, Options opts={})
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (ReadPartition const &partition, Options opts={})
	Reads rows from a subset of rows in a database. More...
StatusOr< std::vector< ReadPartition > >	PartitionRead (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, Options opts={})
	Creates a set of partitions that can be used to execute a read operation in parallel. More...
RowStream	ExecuteQuery (SqlStatement statement, Options opts={})
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, Options opts={})
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction transaction, SqlStatement statement, Options opts={})
	Executes a SQL query. More...
RowStream	ExecuteQuery (QueryPartition const &partition, Options opts={})
	Executes a SQL query on a subset of rows in a database. More...
ProfileQueryResult	ProfileQuery (SqlStatement statement, Options opts={})
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, Options opts={})
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction transaction, SqlStatement statement, Options opts={})
	Profiles a SQL query. More...
StatusOr< std::vector< QueryPartition > >	PartitionQuery (Transaction transaction, SqlStatement statement, Options opts=Options{})
	Creates a set of partitions that can be used to execute a query operation in parallel. More...
StatusOr< DmlResult >	ExecuteDml (Transaction transaction, SqlStatement statement, Options opts={})
	Executes a SQL DML statement. More...
StatusOr< ProfileDmlResult >	ProfileDml (Transaction transaction, SqlStatement statement, Options opts={})
	Profiles a SQL DML statement. More...
StatusOr< ExecutionPlan >	AnalyzeSql (Transaction transaction, SqlStatement statement, Options opts={})
	Analyzes the execution plan of a SQL statement. More...
StatusOr< BatchDmlResult >	ExecuteBatchDml (Transaction transaction, std::vector< SqlStatement > statements, Options opts={})
	Executes a batch of SQL DML statements. More...
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, std::unique_ptr< TransactionRerunPolicy > rerun_policy, std::unique_ptr< BackoffPolicy > backoff_policy, Options opts={})
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, Options opts={})
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (Mutations mutations, Options opts={})
	Commits the mutations, using the options, atomically in order. More...
StatusOr< CommitResult >	Commit (Transaction transaction, Mutations mutations, Options opts={})
	Commits a read-write transaction. More...
StatusOr< CommitResult >	CommitAtLeastOnce (Transaction::ReadWriteOptions transaction_options, Mutations mutations, Options opts={})
	Commits a write transaction with at-least-once semantics. More...
Status	Rollback (Transaction transaction, Options opts={})
	Rolls back a read-write transaction, releasing any locks it holds. More...
StatusOr< PartitionedDmlResult >	ExecutePartitionedDml (SqlStatement statement, Options opts={})
	Executes a Partitioned DML SQL query. More...
Copy and move support
	Client (Client const &)=default
Client &	operator= (Client const &)=default
	Client (Client &&)=default
Client &	operator= (Client &&)=default
Backwards compatibility for ClientOptions.
	Client (std::shared_ptr< Connection > conn, ClientOptions const &opts)
	Client (std::shared_ptr< Connection > conn, std::initializer_list< internal::NonConstructible >)
Backwards compatibility for ReadOptions.
RowStream	Read (std::string table, KeySet keys, std::vector< std::string > columns, ReadOptions const &read_options)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (std::string table, KeySet keys, std::vector< std::string > columns, std::initializer_list< internal::NonConstructible >)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction::SingleUseOptions transaction_options, std::string table, KeySet keys, std::vector< std::string > columns, ReadOptions const &read_options)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction::SingleUseOptions transaction_options, std::string table, KeySet keys, std::vector< std::string > columns, std::initializer_list< internal::NonConstructible >)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, ReadOptions const &read_options)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
RowStream	Read (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, std::initializer_list< internal::NonConstructible >)
	Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery(). More...
Backwards compatibility for ReadOptions and PartitionOptions.
StatusOr< std::vector< ReadPartition > >	PartitionRead (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, ReadOptions const &read_options, PartitionOptions const &partition_options)
	Creates a set of partitions that can be used to execute a read operation in parallel. More...
StatusOr< std::vector< ReadPartition > >	PartitionRead (Transaction transaction, std::string table, KeySet keys, std::vector< std::string > columns, std::initializer_list< internal::NonConstructible >)
	Creates a set of partitions that can be used to execute a read operation in parallel. More...
Backwards compatibility for QueryOptions.
RowStream	ExecuteQuery (SqlStatement statement, QueryOptions const &opts)
	Executes a SQL query. More...
RowStream	ExecuteQuery (SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, QueryOptions const &opts)
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction transaction, SqlStatement statement, QueryOptions const &opts)
	Executes a SQL query. More...
RowStream	ExecuteQuery (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a SQL query. More...
RowStream	ExecuteQuery (QueryPartition const &partition, QueryOptions const &opts)
	Executes a SQL query on a subset of rows in a database. More...
RowStream	ExecuteQuery (QueryPartition const &partition, std::initializer_list< internal::NonConstructible >)
	Executes a SQL query on a subset of rows in a database. More...
ProfileQueryResult	ProfileQuery (SqlStatement statement, QueryOptions const &opts)
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, QueryOptions const &opts)
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction::SingleUseOptions transaction_options, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction transaction, SqlStatement statement, QueryOptions const &opts)
	Profiles a SQL query. More...
ProfileQueryResult	ProfileQuery (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Profiles a SQL query. More...
StatusOr< DmlResult >	ExecuteDml (Transaction transaction, SqlStatement statement, QueryOptions const &opts)
	Executes a SQL DML statement. More...
StatusOr< DmlResult >	ExecuteDml (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a SQL DML statement. More...
StatusOr< ProfileDmlResult >	ProfileDml (Transaction transaction, SqlStatement statement, QueryOptions const &opts)
	Executes a SQL query. More...
StatusOr< ProfileDmlResult >	ProfileDml (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a SQL query. More...
StatusOr< ExecutionPlan >	AnalyzeSql (Transaction transaction, SqlStatement statement, QueryOptions const &opts)
	Analyzes the execution plan of a SQL statement. More...
StatusOr< ExecutionPlan >	AnalyzeSql (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Analyzes the execution plan of a SQL statement. More...
StatusOr< PartitionedDmlResult >	ExecutePartitionedDml (SqlStatement statement, QueryOptions const &opts)
	Executes a Partitioned DML SQL query. More...
StatusOr< PartitionedDmlResult >	ExecutePartitionedDml (SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Executes a Partitioned DML SQL query. More...
Backwards compatibility for PartitionOptions.
StatusOr< std::vector< QueryPartition > >	PartitionQuery (Transaction transaction, SqlStatement statement, PartitionOptions const &partition_options)
	Creates a set of partitions that can be used to execute a query operation in parallel. More...
StatusOr< std::vector< QueryPartition > >	PartitionQuery (Transaction transaction, SqlStatement statement, std::initializer_list< internal::NonConstructible >)
	Creates a set of partitions that can be used to execute a query operation in parallel. More...
Backwards compatibility for CommitOptions.
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, std::unique_ptr< TransactionRerunPolicy > rerun_policy, std::unique_ptr< BackoffPolicy > backoff_policy, CommitOptions const &commit_options)
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, std::unique_ptr< TransactionRerunPolicy > rerun_policy, std::unique_ptr< BackoffPolicy > backoff_policy, std::initializer_list< internal::NonConstructible >)
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, CommitOptions const &commit_options)
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (std::function< StatusOr< Mutations >(Transaction)> const &mutator, std::initializer_list< internal::NonConstructible >)
StatusOr< CommitResult >	Commit (Mutations mutations, CommitOptions const &commit_options)
	Commits the mutations, using the options, atomically in order. More...
StatusOr< CommitResult >	Commit (Mutations mutations, std::initializer_list< internal::NonConstructible >)
	Commits the mutations, using the options, atomically in order. More...
StatusOr< CommitResult >	Commit (Transaction transaction, Mutations mutations, CommitOptions const &commit_options)
	Commits a read-write transaction. More...
StatusOr< CommitResult >	Commit (Transaction transaction, Mutations mutations, std::initializer_list< internal::NonConstructible >)
	Commits a read-write transaction. More...

Friends
Equality
bool	operator== (Client const &a, Client const &b)
bool	operator!= (Client const &a, Client const &b)

Detailed Description

Performs database client operations on Spanner.

Applications use this class to perform operations on Spanner Databases.

Performance

Client objects are relatively cheap to create, copy, and move. However, each Client object must be created with a std::shared_ptr<Connection>, which itself is relatively expensive to create. Therefore, connection instances should be shared when possible. See the MakeConnection() method and the Connection interface for more details.

Thread Safety

Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.

Error Handling

This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. For more information, see the Error Handling Guide.

namespace spanner = ::google::cloud::spanner;
 
auto db = spanner::Database("my_project", "my_instance", "my_db_id"));
auto conn = spanner::MakeConnection(db);
auto client = spanner::Client(conn);
 
auto rows = client.Read(...);
using RowType = std::tuple<std::int64_t, std::string>;
for (auto const& row : spanner::StreamOf<RowType>(rows)) {
  // ...
}

Query Options

Most operations that take an SqlStatement may also be modified with query Options. These options can be set at various levels, with more specific levels taking precedence over broader ones. For example, Options that are passed directly to Client::ExecuteQuery() will take precedence over the Client-level defaults (if any), which will themselves take precedence over any environment variables. The following table shows the environment variables that may optionally be set and the query Options setting that they affect.

Environment Variable	Options setting
SPANNER_OPTIMIZER_VERSION	QueryOptimizerVersionOption
SPANNER_OPTIMIZER_STATISTICS_PACKAGE	QueryOptimizerStatisticsPackageOption

See also

https://cloud.google.com/spanner/docs/reference/rest/v1/QueryOptions

http://cloud/spanner/docs/query-optimizer/manage-query-optimizer

Constructor & Destructor Documentation

Client() [1/6]

google::cloud::spanner::Client::Client ( std::shared_ptr< Connection >  conn, Options  opts = {}  )

inlineexplicit

Constructs a Client object using the specified conn and opts.

See MakeConnection() for how to create a connection to Spanner. To help with unit testing, callers may create fake/mock Connection objects that are injected into the Client.

Client() [2/6]

google::cloud::spanner::Client::Client ( )

delete

No default construction.

Client() [3/6]

google::cloud::spanner::Client::Client ( Client const &  )

default

Client() [4/6]

google::cloud::spanner::Client::Client ( Client &&  )

default

Client() [5/6]

google::cloud::spanner::Client::Client ( std::shared_ptr< Connection >  conn, ClientOptions const &  opts  )

inlineexplicit

Client() [6/6]

google::cloud::spanner::Client::Client ( std::shared_ptr< Connection >  conn, std::initializer_list< internal::NonConstructible >    )

inlineexplicit

Member Function Documentation

AnalyzeSql() [1/3]

StatusOr< ExecutionPlan > google::cloud::spanner::Client::AnalyzeSql	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = {}
	)

Analyzes the execution plan of a SQL statement.

Analyzing provides the ExecutionPlan, but does not execute the SQL statement.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Note

Single-use transactions are not supported with DML statements.

Example

  // Only SQL queries with a Distributed Union as the first operator in the
  // `ExecutionPlan` can be partitioned.
  auto is_partitionable = [](spanner::ExecutionPlan const& plan) {
    return (!plan.plan_nodes().empty() &&
            plan.plan_nodes(0).kind() ==
                google::spanner::v1::PlanNode::RELATIONAL &&
            plan.plan_nodes(0).display_name() == "Distributed Union");
  };
 
  google::cloud::StatusOr<spanner::ExecutionPlan> plan = client.AnalyzeSql(
      spanner::MakeReadOnlyTransaction(),
      spanner::SqlStatement(
          "SELECT SingerId, FirstName, LastName FROM Singers"));
  if (!plan) throw std::move(plan).status();
  if (!is_partitionable(*plan)) {
    throw std::runtime_error("Query is not partitionable");
  }

Parameters

transaction	Execute this query as part of an existing transaction.
statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

AnalyzeSql() [2/3]

StatusOr< ExecutionPlan > google::cloud::spanner::Client::AnalyzeSql ( Transaction  transaction, SqlStatement  statement, QueryOptions const &  opts  )

inline

Analyzes the execution plan of a SQL statement.

See also

AnalyzeSql(Transaction,SqlStatement,Options)

AnalyzeSql() [3/3]

StatusOr< ExecutionPlan > google::cloud::spanner::Client::AnalyzeSql ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Analyzes the execution plan of a SQL statement.

See also

AnalyzeSql(Transaction,SqlStatement,Options)

Commit() [1/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( Mutations  mutations, CommitOptions const &  commit_options  )

inline

Commits the mutations, using the options, atomically in order.

See also

Commit(Mutations,Options)

Commit() [2/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit	(	Mutations	mutations,
		Options	opts = {}
	)

Commits the mutations, using the options, atomically in order.

Example

  namespace spanner = ::google::cloud::spanner;
  auto commit_result = client.Commit(spanner::Mutations{
      spanner::UpdateMutationBuilder("Albums",
                                     {"SingerId", "AlbumId", "MarketingBudget"})
          .EmplaceRow(1, 1, 100000)
          .EmplaceRow(2, 2, 500000)
          .Build()});
  if (!commit_result) throw std::move(commit_result).status();

This function uses the re-run loop described above with the default policies.

Commit() [3/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( Mutations  mutations, std::initializer_list< internal::NonConstructible >    )

inline

Commits the mutations, using the options, atomically in order.

See also

Commit(Mutations,Options)

Commit() [4/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( std::function< StatusOr< Mutations >(Transaction)> const &  mutator, CommitOptions const &  commit_options  )

inline

Commits a read-write transaction.

Commit() [5/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit	(	std::function< StatusOr< Mutations >(Transaction)> const &	mutator,
		Options	opts = {}
	)

Commits a read-write transaction.

Same as above, but uses the default rerun and backoff policies.

Example

  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;
  auto commit_result = client.Commit(
      [&client](spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto update = client.ExecuteDml(
            std::move(txn),
            spanner::SqlStatement(
                "UPDATE Albums SET MarketingBudget = MarketingBudget * 2"
                "  WHERE SingerId = 1 AND AlbumId = 1"));
        if (!update) return std::move(update).status();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();

Parameters

mutator	the function called to create mutations
opts	(optional) The options to use for this call.

Commit() [6/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( std::function< StatusOr< Mutations >(Transaction)> const &  mutator, std::initializer_list< internal::NonConstructible >    )

inline

See also

Commit(std::function<StatusOr<Mutations>(Transaction)> const&,Options)

Commit() [7/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( std::function< StatusOr< Mutations >(Transaction)> const &  mutator, std::unique_ptr< TransactionRerunPolicy >  rerun_policy, std::unique_ptr< BackoffPolicy >  backoff_policy, CommitOptions const &  commit_options  )

inline

Commits a read-write transaction.

See also

Commit(std::function<StatusOr<Mutations>(Transaction)> const&,std::unique_ptr<TransactionRerunPolicy>,std::unique_ptr<BackoffPolicy>,Options)

Commit() [8/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit	(	std::function< StatusOr< Mutations >(Transaction)> const &	mutator,
		std::unique_ptr< TransactionRerunPolicy >	rerun_policy,
		std::unique_ptr< BackoffPolicy >	backoff_policy,
		Options	opts = {}
	)

Commits a read-write transaction.

Calls the mutator in the context of a new read-write transaction. The mutator can execute read/write operations using the transaction, and returns any additional Mutations to commit.

If the mutator succeeds and the transaction commits, then Commit() returns the CommitResult.

If the mutator returns a non-rerunnable status (according to the rerun_policy), the transaction is rolled back and that status is returned. Similarly, if the transaction fails to commit with a non- rerunnable status, that status is returned.

Otherwise the whole process repeats (subject to rerun_policy and backoff_policy), by building a new transaction and re-running the mutator. The lock priority of the operation increases after each rerun, meaning that the next attempt has a slightly better chance of success.

Note that the mutator should only return a rerunnable status when the transaction is no longer usable (e.g., it was aborted). Otherwise the transaction will be leaked.

Example

void CommitWithPolicies(google::cloud::spanner::Client client) {
  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;
  auto commit = client.Commit(
      [&client](spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto update = client.ExecuteDml(
            std::move(txn),
            spanner::SqlStatement(
                "UPDATE Albums SET MarketingBudget = MarketingBudget * 2"
                "  WHERE SingerId = 1 AND AlbumId = 1"));
        if (!update) return std::move(update).status();
        return spanner::Mutations{};
      },
      // Retry for up to 42 minutes.
      spanner::LimitedTimeTransactionRerunPolicy(std::chrono::minutes(42))
          .clone(),
      // After a failure backoff for 2 seconds (with jitter), then triple the
      // backoff time on each retry, up to 5 minutes.
      spanner::ExponentialBackoffPolicy(std::chrono::seconds(2),
                                        std::chrono::minutes(5), 3.0)
          .clone());
  if (!commit) throw std::move(commit).status();
  std::cout << "commit-with-policies was successful\n";
}

Parameters

mutator	the function called to create mutations
rerun_policy	controls for how long (or how many times) the mutator will be rerun after the transaction aborts.
backoff_policy	controls how long Commit waits between reruns.
opts	(optional) The options to use for this call. Expected options include any of the following types: google::cloud::spanner::CommitReturnStatsOption google::cloud::spanner::RequestPriorityOption google::cloud::spanner::TransactionTagOption

Exceptions

Rethrows

any exception thrown by `mutator` (after rolling back the transaction). However, a RuntimeStatusError exception is instead consumed and converted into a mutator return value of the enclosed Status.

Commit() [9/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( std::function< StatusOr< Mutations >(Transaction)> const &  mutator, std::unique_ptr< TransactionRerunPolicy >  rerun_policy, std::unique_ptr< BackoffPolicy >  backoff_policy, std::initializer_list< internal::NonConstructible >    )

inline

Commits a read-write transaction.

See also

Commit(std::function<StatusOr<Mutations>(Transaction)> const&,std::unique_ptr<TransactionRerunPolicy>,std::unique_ptr<BackoffPolicy>,Options)

Commit() [10/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( Transaction  transaction, Mutations  mutations, CommitOptions const &  commit_options  )

inline

Commits a read-write transaction.

See also

Commit(Transaction,Mutations,Options)

Commit() [11/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit	(	Transaction	transaction,
		Mutations	mutations,
		Options	opts = {}
	)

Commits a read-write transaction.

The commit might return a kAborted error. This can occur at any time. Commonly the cause is conflicts with concurrent transactions, however it can also happen for a variety of other reasons. If Commit returns kAborted, the caller may try to reapply the mutations within a new read-write transaction (which should share lock priority with the aborted transaction so that the new attempt has a slightly better chance of success).

Warning

It is an error to call Commit with a read-only transaction.

Note

Prefer the previous Commit overloads if you want to simply reapply mutations after a kAborted error.

Parameters

transaction	The transaction to commit.
mutations	The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list.
opts	(optional) The options to use for this call.

Returns

A StatusOr containing the result of the commit or error status on failure.

Commit() [12/12]

StatusOr< CommitResult > google::cloud::spanner::Client::Commit ( Transaction  transaction, Mutations  mutations, std::initializer_list< internal::NonConstructible >    )

inline

Commits a read-write transaction.

See also

Commit(Transaction,Mutations,Options)

CommitAtLeastOnce()

StatusOr< CommitResult > google::cloud::spanner::Client::CommitAtLeastOnce	(	Transaction::ReadWriteOptions	transaction_options,
		Mutations	mutations,
		Options	opts = {}
	)

Commits a write transaction with at-least-once semantics.

Apply the given mutations atomically, using a single RPC, and therefore without replay protection. That is, it is possible that the mutations will be applied more than once. If the mutations are not idempotent, this may lead to a failure (for example, an insert may fail with "already exists" even though the row did not exist before the call was made). Accordingly, this call may only be appropriate for idempotent, latency- sensitive and/or high-throughput blind writing.

Note

Prefer the Commit overloads if you want exactly-once semantics or want to reapply mutations after a kAborted error.

Example

  namespace spanner = ::google::cloud::spanner;
 
  // Delete the album with key (2,2) without automatic re-run (e.g., if the
  // transaction was aborted) or replay protection, but using a single RPC.
  auto commit_result = client.CommitAtLeastOnce(
      spanner::Transaction::ReadWriteOptions(),
      spanner::Mutations{
          spanner::DeleteMutationBuilder(
              "Albums", spanner::KeySet().AddKey(spanner::MakeKey(2, 2)))
              .Build()});
 
  if (commit_result) {
    std::cout << "Delete was successful\n";
  } else if (commit_result.status().code() ==
             google::cloud::StatusCode::kNotFound) {
    std::cout << "Delete was successful but seemingly replayed\n";
  } else if (commit_result.status().code() ==
             google::cloud::StatusCode::kAborted) {
    std::cout << "Delete was aborted\n";
  } else {
    throw std::move(commit_result).status();
  }

Parameters

transaction_options	Execute the commit in a temporary transaction with these options.
mutations	The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list.
opts	(optional) The options to use for this call.

Returns

A StatusOr containing the result of the commit or error status on failure.

ExecuteBatchDml()

StatusOr< BatchDmlResult > google::cloud::spanner::Client::ExecuteBatchDml	(	Transaction	transaction,
		std::vector< SqlStatement >	statements,
		Options	opts = {}
	)

Executes a batch of SQL DML statements.

This method allows many statements to be run with lower latency than submitting them sequentially with ExecuteDml.

Statements are executed in order, sequentially. Execution will stop at the first failed statement; the remaining statements will not run.

As with all read-write transactions, the results will not be visible outside of the transaction until it is committed. For that reason, it is advisable to run this method from a Commit mutator.

Warning

A returned status of OK from this function does not imply that all the statements were executed successfully. For that, you need to inspect the BatchDmlResult::status field.

Example

void DmlStructs(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  std::int64_t rows_modified = 0;
  auto commit_result =
      client.Commit([&client, &rows_modified](spanner::Transaction const& txn)
                        -> google::cloud::StatusOr<spanner::Mutations> {
        auto singer_info = std::make_tuple("Marc", "Richards");
        auto sql = spanner::SqlStatement(
            "UPDATE Singers SET FirstName = 'Keith' WHERE "
            "STRUCT<FirstName String, LastName String>(FirstName, LastName) "
            "= @name",
            {{"name", spanner::Value(std::move(singer_info))}});
        auto dml_result = client.ExecuteDml(txn, std::move(sql));
        if (!dml_result) return std::move(dml_result).status();
        rows_modified = dml_result->RowsModified();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << rows_modified
            << " update was successful [spanner_dml_structs]\n";
}

Parameters

transaction	The read-write transaction to execute the operation in.
statements	The list of statements to execute in this batch. Statements are executed serially, such that the effects of statement i are visible to statement i+1. Each statement must be a DML statement. Execution will stop at the first failed statement; the remaining statements will not run. Must not be empty.
opts	(optional) The options to use for this call. Expected options are any of the types in the following option lists. google::cloud::RequestOptionList

ExecuteDml() [1/3]

StatusOr< DmlResult > google::cloud::spanner::Client::ExecuteDml	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = {}
	)

Executes a SQL DML statement.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Note

Single-use transactions are not supported with DML statements.

Example

  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;
  std::int64_t rows_inserted;
  auto commit_result = client.Commit(
      [&client, &rows_inserted](
          spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto insert = client.ExecuteDml(
            std::move(txn),
            spanner::SqlStatement(
                "INSERT INTO Singers (SingerId, FirstName, LastName)"
                "  VALUES (10, 'Virginia', 'Watson')"));
        if (!insert) return std::move(insert).status();
        rows_inserted = insert->RowsModified();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Rows inserted: " << rows_inserted;

Parameters

transaction	Execute this query as part of an existing transaction.
statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

ExecuteDml() [2/3]

StatusOr< DmlResult > google::cloud::spanner::Client::ExecuteDml ( Transaction  transaction, SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a SQL DML statement.

See also

ExecuteDml(Transaction,SqlStatement,Options)

ExecuteDml() [3/3]

StatusOr< DmlResult > google::cloud::spanner::Client::ExecuteDml ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL DML statement.

See also

ExecuteDml(Transaction,SqlStatement,Options)

ExecutePartitionedDml() [1/3]

StatusOr< PartitionedDmlResult > google::cloud::spanner::Client::ExecutePartitionedDml	(	SqlStatement	statement,
		Options	opts = {}
	)

Executes a Partitioned DML SQL query.

Example

void DmlPartitionedDelete(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
  auto result = client.ExecutePartitionedDml(
      spanner::SqlStatement("DELETE FROM Singers WHERE SingerId > 10"));
  if (!result) throw std::move(result).status();
  std::cout << "Deleted at least " << result->row_count_lower_bound
            << " row(s) [spanner_dml_partitioned_delete]\n";
}

Parameters

statement	the SQL statement to execute. Please see the spanner documentation for the restrictions on the SQL statements supported by this function.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

See also

Partitioned DML Transactions for an overview of Partitioned DML transactions.

Partitioned DML for a description of which SQL statements are supported in Partitioned DML transactions.

ExecutePartitionedDml() [2/3]

StatusOr< PartitionedDmlResult > google::cloud::spanner::Client::ExecutePartitionedDml ( SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a Partitioned DML SQL query.

See also

ExecutePartitionedDml(SqlStatement,Options)

ExecutePartitionedDml() [3/3]

StatusOr< PartitionedDmlResult > google::cloud::spanner::Client::ExecutePartitionedDml ( SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a Partitioned DML SQL query.

See also

ExecutePartitionedDml(SqlStatement,Options)

ExecuteQuery() [1/12]

RowStream google::cloud::spanner::Client::ExecuteQuery	(	QueryPartition const &	partition,
		Options	opts = {}
	)

Executes a SQL query on a subset of rows in a database.

Requires a prior call to PartitionQuery to obtain the partition information; see the documentation of that method for full details.

Note

No individual row in the RowStream can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

  google::cloud::StatusOr<spanner::QueryPartition> partition =
      remote_connection.ReceiveQueryPartitionFromRemoteMachine();
  if (!partition) throw std::move(partition).status();
  for (auto& row : client.ExecuteQuery(*partition)) {
    if (row.status().code() ==                           
        google::cloud::StatusCode::kPermissionDenied) {  
      continue;                                          
    }                                                    
    if (!row) throw std::move(row).status();
    ProcessRow(*row);
  }

Parameters

partition	A QueryPartition, obtained by calling PartitionQuery.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

ExecuteQuery() [2/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( QueryPartition const &  partition, QueryOptions const &  opts  )

inline

Executes a SQL query on a subset of rows in a database.

See also

ExecuteQuery(QueryPartition const&,Options)

ExecuteQuery() [3/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( QueryPartition const &  partition, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL query on a subset of rows in a database.

See also

ExecuteQuery(QueryPartition const&,Options)

ExecuteQuery() [4/12]

RowStream google::cloud::spanner::Client::ExecuteQuery	(	SqlStatement	statement,
		Options	opts = {}
	)

Executes a SQL query.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

SELECT * ... queries are supported, but there's no guarantee about the order, nor number, of returned columns. Therefore, the caller must look up the wanted values in each row by column name. When the desired column names are known in advance, it is better to list them explicitly in the query's SELECT statement, so that unnecessary values are not returned/ignored, and the column order is known. This enables more efficient and simpler code.

Can also execute a DML statement with a returning clause in a read/write transaction.

Note

No individual row in the RowStream can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

Query with explicitly selected columns.

void QueryData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  spanner::SqlStatement select("SELECT SingerId, LastName FROM Singers");
  using RowType = std::tuple<std::int64_t, std::string>;
  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "LastName: " << std::get<1>(*row) << "\n";
  }
 
  std::cout << "Query completed for [spanner_query_data]\n";
}

Example

Using SELECT *.

void QueryDataSelectStar(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  // With a "SELECT *" query, we don't know the order in which the columns will
  // be returned (nor the number of columns). Therefore, we look up each value
  // based on the column name rather than its position.
  spanner::SqlStatement select_star("SELECT * FROM Singers");
  for (auto& row : client.ExecuteQuery(std::move(select_star))) {
    if (!row) throw std::move(row).status();
 
    if (auto singer_id = row->get<std::int64_t>("SingerId")) {
      std::cout << "SingerId: " << *singer_id << "\t";
    } else {
      std::cerr << singer_id.status();
    }
 
    if (auto last_name = row->get<std::string>("LastName")) {
      std::cout << "LastName: " << *last_name;
    } else {
      std::cerr << last_name.status();
    }
    std::cout << "\n";
  }
  std::cout << "Query completed for [spanner_query_data_select_star]\n";
}

Example

Using a DML statement with THEN RETURN.

void UpdateUsingDmlReturning(google::cloud::spanner::Client client) {
  // Update MarketingBudget column for records satisfying a particular
  // condition and return the modified MarketingBudget column of the
  // updated records using `THEN RETURN MarketingBudget`.
  auto commit = client.Commit(
      [&client](google::cloud::spanner::Transaction txn)
          -> google::cloud::StatusOr<google::cloud::spanner::Mutations> {
        auto sql = google::cloud::spanner::SqlStatement(R"""(
            UPDATE Albums SET MarketingBudget = MarketingBudget * 2
              WHERE SingerId = 1 AND AlbumId = 1
              THEN RETURN MarketingBudget
        )""");
        using RowType = std::tuple<absl::optional<std::int64_t>>;
        auto rows = client.ExecuteQuery(std::move(txn), std::move(sql));
        // Note: This mutator might be re-run, or its effects discarded, so
        // changing non-transactional state (e.g., by producing output) is,
        // in general, not something to be imitated.
        for (auto& row : google::cloud::spanner::StreamOf<RowType>(rows)) {
          if (!row) return std::move(row).status();
          std::cout << "MarketingBudget: ";
          if (std::get<0>(*row).has_value()) {
            std::cout << *std::get<0>(*row);
          } else {
            std::cout << "NULL";
          }
          std::cout << "\n";
        }
        std::cout << "Updated row(s) count: " << rows.RowsModified() << "\n";
        return google::cloud::spanner::Mutations{};
      });
  if (!commit) throw std::move(commit).status();
}

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

ExecuteQuery() [5/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a SQL query.

See also

ExecuteQuery(SqlStatement,Options)

ExecuteQuery() [6/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL query.

See also

ExecuteQuery(SqlStatement,Options)

ExecuteQuery() [7/12]

RowStream google::cloud::spanner::Client::ExecuteQuery	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = {}
	)

Executes a SQL query.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

SELECT * ... queries are supported, but there's no guarantee about the order, nor number, of returned columns. Therefore, the caller must look up the wanted values in each row by column name. When the desired column names are known in advance, it is better to list them explicitly in the query's SELECT statement, so that unnecessary values are not returned/ignored, and the column order is known. This enables more efficient and simpler code.

Can also execute a DML statement with a returning clause in a read/write transaction.

Note

No individual row in the RowStream can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

Query with explicitly selected columns.

void QueryData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  spanner::SqlStatement select("SELECT SingerId, LastName FROM Singers");
  using RowType = std::tuple<std::int64_t, std::string>;
  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "LastName: " << std::get<1>(*row) << "\n";
  }
 
  std::cout << "Query completed for [spanner_query_data]\n";
}

Example

Using SELECT *.

void QueryDataSelectStar(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  // With a "SELECT *" query, we don't know the order in which the columns will
  // be returned (nor the number of columns). Therefore, we look up each value
  // based on the column name rather than its position.
  spanner::SqlStatement select_star("SELECT * FROM Singers");
  for (auto& row : client.ExecuteQuery(std::move(select_star))) {
    if (!row) throw std::move(row).status();
 
    if (auto singer_id = row->get<std::int64_t>("SingerId")) {
      std::cout << "SingerId: " << *singer_id << "\t";
    } else {
      std::cerr << singer_id.status();
    }
 
    if (auto last_name = row->get<std::string>("LastName")) {
      std::cout << "LastName: " << *last_name;
    } else {
      std::cerr << last_name.status();
    }
    std::cout << "\n";
  }
  std::cout << "Query completed for [spanner_query_data_select_star]\n";
}

Example

Using a DML statement with THEN RETURN.

void UpdateUsingDmlReturning(google::cloud::spanner::Client client) {
  // Update MarketingBudget column for records satisfying a particular
  // condition and return the modified MarketingBudget column of the
  // updated records using `THEN RETURN MarketingBudget`.
  auto commit = client.Commit(
      [&client](google::cloud::spanner::Transaction txn)
          -> google::cloud::StatusOr<google::cloud::spanner::Mutations> {
        auto sql = google::cloud::spanner::SqlStatement(R"""(
            UPDATE Albums SET MarketingBudget = MarketingBudget * 2
              WHERE SingerId = 1 AND AlbumId = 1
              THEN RETURN MarketingBudget
        )""");
        using RowType = std::tuple<absl::optional<std::int64_t>>;
        auto rows = client.ExecuteQuery(std::move(txn), std::move(sql));
        // Note: This mutator might be re-run, or its effects discarded, so
        // changing non-transactional state (e.g., by producing output) is,
        // in general, not something to be imitated.
        for (auto& row : google::cloud::spanner::StreamOf<RowType>(rows)) {
          if (!row) return std::move(row).status();
          std::cout << "MarketingBudget: ";
          if (std::get<0>(*row).has_value()) {
            std::cout << *std::get<0>(*row);
          } else {
            std::cout << "NULL";
          }
          std::cout << "\n";
        }
        std::cout << "Updated row(s) count: " << rows.RowsModified() << "\n";
        return google::cloud::spanner::Mutations{};
      });
  if (!commit) throw std::move(commit).status();
}

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.
transaction	Execute this query as part of an existing transaction.

ExecuteQuery() [8/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( Transaction  transaction, SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a SQL query.

See also

ExecuteQuery(Transaction,SqlStatement,Options)

ExecuteQuery() [9/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL query.

See also

ExecuteQuery(Transaction,SqlStatement,Options)

ExecuteQuery() [10/12]

RowStream google::cloud::spanner::Client::ExecuteQuery	(	Transaction::SingleUseOptions	transaction_options,
		SqlStatement	statement,
		Options	opts = {}
	)

Executes a SQL query.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

SELECT * ... queries are supported, but there's no guarantee about the order, nor number, of returned columns. Therefore, the caller must look up the wanted values in each row by column name. When the desired column names are known in advance, it is better to list them explicitly in the query's SELECT statement, so that unnecessary values are not returned/ignored, and the column order is known. This enables more efficient and simpler code.

Can also execute a DML statement with a returning clause in a read/write transaction.

Note

No individual row in the RowStream can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

Query with explicitly selected columns.

void QueryData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  spanner::SqlStatement select("SELECT SingerId, LastName FROM Singers");
  using RowType = std::tuple<std::int64_t, std::string>;
  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "LastName: " << std::get<1>(*row) << "\n";
  }
 
  std::cout << "Query completed for [spanner_query_data]\n";
}

Example

Using SELECT *.

void QueryDataSelectStar(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  // With a "SELECT *" query, we don't know the order in which the columns will
  // be returned (nor the number of columns). Therefore, we look up each value
  // based on the column name rather than its position.
  spanner::SqlStatement select_star("SELECT * FROM Singers");
  for (auto& row : client.ExecuteQuery(std::move(select_star))) {
    if (!row) throw std::move(row).status();
 
    if (auto singer_id = row->get<std::int64_t>("SingerId")) {
      std::cout << "SingerId: " << *singer_id << "\t";
    } else {
      std::cerr << singer_id.status();
    }
 
    if (auto last_name = row->get<std::string>("LastName")) {
      std::cout << "LastName: " << *last_name;
    } else {
      std::cerr << last_name.status();
    }
    std::cout << "\n";
  }
  std::cout << "Query completed for [spanner_query_data_select_star]\n";
}

Example

Using a DML statement with THEN RETURN.

void UpdateUsingDmlReturning(google::cloud::spanner::Client client) {
  // Update MarketingBudget column for records satisfying a particular
  // condition and return the modified MarketingBudget column of the
  // updated records using `THEN RETURN MarketingBudget`.
  auto commit = client.Commit(
      [&client](google::cloud::spanner::Transaction txn)
          -> google::cloud::StatusOr<google::cloud::spanner::Mutations> {
        auto sql = google::cloud::spanner::SqlStatement(R"""(
            UPDATE Albums SET MarketingBudget = MarketingBudget * 2
              WHERE SingerId = 1 AND AlbumId = 1
              THEN RETURN MarketingBudget
        )""");
        using RowType = std::tuple<absl::optional<std::int64_t>>;
        auto rows = client.ExecuteQuery(std::move(txn), std::move(sql));
        // Note: This mutator might be re-run, or its effects discarded, so
        // changing non-transactional state (e.g., by producing output) is,
        // in general, not something to be imitated.
        for (auto& row : google::cloud::spanner::StreamOf<RowType>(rows)) {
          if (!row) return std::move(row).status();
          std::cout << "MarketingBudget: ";
          if (std::get<0>(*row).has_value()) {
            std::cout << *std::get<0>(*row);
          } else {
            std::cout << "NULL";
          }
          std::cout << "\n";
        }
        std::cout << "Updated row(s) count: " << rows.RowsModified() << "\n";
        return google::cloud::spanner::Mutations{};
      });
  if (!commit) throw std::move(commit).status();
}

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.
transaction_options	Execute this query in a single-use transaction with these options.

ExecuteQuery() [11/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( Transaction::SingleUseOptions  transaction_options, SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a SQL query.

See also

ExecuteQuery(Transaction::SingleUseOptions,SqlStatement,Options)

ExecuteQuery() [12/12]

RowStream google::cloud::spanner::Client::ExecuteQuery ( Transaction::SingleUseOptions  transaction_options, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL query.

See also

ExecuteQuery(Transaction::SingleUseOptions,SqlStatement,Options)

operator=() [1/2]

Client & google::cloud::spanner::Client::operator= ( Client &&  )

default

operator=() [2/2]

Client & google::cloud::spanner::Client::operator= ( Client const &  )

default

PartitionQuery() [1/3]

StatusOr< std::vector< QueryPartition > > google::cloud::spanner::Client::PartitionQuery	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = Options{}
	)

Creates a set of partitions that can be used to execute a query operation in parallel.

Each of the returned partitions can be passed to ExecuteQuery to specify a subset of the query result to read.

Partitions become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too old. When any of these happen, it is not possible to resume the query, and the whole operation must be restarted from the beginning.

Example

  google::cloud::StatusOr<std::vector<spanner::QueryPartition>> partitions =
      client.PartitionQuery(
          spanner::MakeReadOnlyTransaction(),
          spanner::SqlStatement(
              "SELECT SingerId, FirstName, LastName FROM Singers"),
          google::cloud::Options{}.set<spanner::PartitionDataBoostOption>(
              true));
  if (!partitions) throw std::move(partitions).status();
  for (auto& partition : *partitions) {
    remote_connection.SendPartitionToRemoteMachine(partition);
  }

Parameters

transaction	The transaction to execute the operation in. Must be a read-only snapshot transaction.
statement	The SQL statement to execute.
opts	Options used for this request.

Returns

A StatusOr containing a vector of QueryPartitions or error status on failure.

PartitionQuery() [2/3]

StatusOr< std::vector< QueryPartition > > google::cloud::spanner::Client::PartitionQuery ( Transaction  transaction, SqlStatement  statement, PartitionOptions const &  partition_options  )

inline

Creates a set of partitions that can be used to execute a query operation in parallel.

See also

PartitionQuery(Transaction,SqlStatement,Options)

PartitionQuery() [3/3]

StatusOr< std::vector< QueryPartition > > google::cloud::spanner::Client::PartitionQuery ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Creates a set of partitions that can be used to execute a query operation in parallel.

See also

PartitionQuery(Transaction,SqlStatement,Options)

PartitionRead() [1/3]

StatusOr< std::vector< ReadPartition > > google::cloud::spanner::Client::PartitionRead	(	Transaction	transaction,
		std::string	table,
		KeySet	keys,
		std::vector< std::string >	columns,
		Options	opts = {}
	)

Creates a set of partitions that can be used to execute a read operation in parallel.

Each of the returned partitions can be passed to Read to specify a subset of the read result to read.

There are no ordering guarantees on rows returned among the returned partition, or even within each individual Read call issued with a given partition.

Partitions become invalid when the session used to create them is deleted, is idle for too long, begins a new transaction, or becomes too old. When any of these happen, it is not possible to resume the read, and the whole operation must be restarted from the beginning.

Example

  spanner::Transaction ro_transaction = spanner::MakeReadOnlyTransaction();
  google::cloud::StatusOr<std::vector<spanner::ReadPartition>> partitions =
      client.PartitionRead(
          ro_transaction, "Singers", key_set,
          {"SingerId", "FirstName", "LastName"},
          google::cloud::Options{}.set<spanner::PartitionDataBoostOption>(
              true));
  if (!partitions) throw std::move(partitions).status();
  for (auto& partition : *partitions) {
    remote_connection.SendPartitionToRemoteMachine(partition);
  }

Parameters

transaction	The transaction to execute the operation in. Must be a read-only snapshot transaction.
table	The name of the table in the database to be read.
keys	Identifies the rows to be yielded. If read_options.index_name is set, names keys in that index; otherwise names keys in the primary index of table. It is not an error for keys to name rows that do not exist in the database; Read yields nothing for nonexistent rows.
columns	The columns of table to be returned for each row matching this request.
opts	Options used for this request.

Returns

A StatusOr containing a vector of ReadPartition or error status on failure.

PartitionRead() [2/3]

StatusOr< std::vector< ReadPartition > > google::cloud::spanner::Client::PartitionRead ( Transaction  transaction, std::string  table, KeySet  keys, std::vector< std::string >  columns, ReadOptions const &  read_options, PartitionOptions const &  partition_options  )

inline

Creates a set of partitions that can be used to execute a read operation in parallel.

See also

PartitionRead(Transaction,std::string,KeySet,std::vector<std::string>,Options)

PartitionRead() [3/3]

StatusOr< std::vector< ReadPartition > > google::cloud::spanner::Client::PartitionRead ( Transaction  transaction, std::string  table, KeySet  keys, std::vector< std::string >  columns, std::initializer_list< internal::NonConstructible >    )

inline

Creates a set of partitions that can be used to execute a read operation in parallel.

See also

PartitionRead(Transaction,std::string,KeySet,std::vector<std::string>,Options)

ProfileDml() [1/3]

StatusOr< ProfileDmlResult > google::cloud::spanner::Client::ProfileDml	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = {}
	)

Profiles a SQL DML statement.

Profiling executes the DML statement, provides the modified row count, ExecutionPlan, and execution statistics.

Operations inside read-write transactions might return ABORTED. If this occurs, the application should restart the transaction from the beginning.

Note

Single-use transactions are not supported with DML statements.

Example

  spanner::ProfileDmlResult dml_result;
  auto commit_result = client.Commit(
      [&client,
       &dml_result](spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto update = client.ProfileDml(
            std::move(txn),
            spanner::SqlStatement(
                "UPDATE Albums SET MarketingBudget = MarketingBudget * 2"
                "  WHERE SingerId = 1 AND AlbumId = 1"));
        if (!update) return std::move(update).status();
        dml_result = *std::move(update);
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
 
  // Stats only available after statement has been executed.
  std::cout << "Rows modified: " << dml_result.RowsModified();
  auto execution_stats = dml_result.ExecutionStats();
  if (execution_stats) {
    for (auto const& stat : *execution_stats) {
      std::cout << stat.first << ":\t" << stat.second << "\n";
    }
  }

Parameters

transaction	Execute this query as part of an existing transaction.
statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

ProfileDml() [2/3]

StatusOr< ProfileDmlResult > google::cloud::spanner::Client::ProfileDml ( Transaction  transaction, SqlStatement  statement, QueryOptions const &  opts  )

inline

Executes a SQL query.

See also

ExecuteQuery(SqlStatement,Options)

ProfileDml() [3/3]

StatusOr< ProfileDmlResult > google::cloud::spanner::Client::ProfileDml ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Executes a SQL query.

See also

ExecuteQuery(SqlStatement,Options)

ProfileQuery() [1/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery	(	SqlStatement	statement,
		Options	opts = {}
	)

Profiles a SQL query.

Profiling executes the query, provides the resulting rows, ExecutionPlan, and execution statistics.

Operations inside read-write transactions might return kAborted. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

Callers must consume all rows from the result before execution statistics and ExecutionPlan are available.

No individual row in the ProfileQueryResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

  namespace spanner = ::google::cloud::spanner;
  spanner::SqlStatement select(
      "SELECT AlbumId, AlbumTitle, MarketingBudget"
      " FROM Albums"
      " WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'");
  auto profile_query_result = client.ProfileQuery(std::move(select));
  for (auto& row : profile_query_result) {
    if (!row) throw std::move(row).status();
    // Discard rows for brevity in this example.
  }
 
  // Stats are only available after all rows from the result have been read.
  auto execution_stats = profile_query_result.ExecutionStats();
  if (execution_stats) {
    for (auto const& stat : *execution_stats) {
      std::cout << stat.first << ":\t" << stat.second << "\n";
    }
  }

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.

ProfileQuery() [2/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( SqlStatement  statement, QueryOptions const &  opts  )

inline

Profiles a SQL query.

See also

ProfileQuery(SqlStatement,Options)

ProfileQuery() [3/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Profiles a SQL query.

See also

ProfileQuery(SqlStatement,Options)

ProfileQuery() [4/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery	(	Transaction	transaction,
		SqlStatement	statement,
		Options	opts = {}
	)

Profiles a SQL query.

Profiling executes the query, provides the resulting rows, ExecutionPlan, and execution statistics.

Operations inside read-write transactions might return kAborted. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

Callers must consume all rows from the result before execution statistics and ExecutionPlan are available.

No individual row in the ProfileQueryResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

  namespace spanner = ::google::cloud::spanner;
  spanner::SqlStatement select(
      "SELECT AlbumId, AlbumTitle, MarketingBudget"
      " FROM Albums"
      " WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'");
  auto profile_query_result = client.ProfileQuery(std::move(select));
  for (auto& row : profile_query_result) {
    if (!row) throw std::move(row).status();
    // Discard rows for brevity in this example.
  }
 
  // Stats are only available after all rows from the result have been read.
  auto execution_stats = profile_query_result.ExecutionStats();
  if (execution_stats) {
    for (auto const& stat : *execution_stats) {
      std::cout << stat.first << ":\t" << stat.second << "\n";
    }
  }

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.
transaction	Execute this query as part of an existing transaction.

ProfileQuery() [5/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( Transaction  transaction, SqlStatement  statement, QueryOptions const &  opts  )

inline

Profiles a SQL query.

See also

ProfileQuery(Transaction,SqlStatement,Options)

ProfileQuery() [6/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( Transaction  transaction, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Profiles a SQL query.

See also

ProfileQuery(Transaction,SqlStatement,Options)

ProfileQuery() [7/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery	(	Transaction::SingleUseOptions	transaction_options,
		SqlStatement	statement,
		Options	opts = {}
	)

Profiles a SQL query.

Profiling executes the query, provides the resulting rows, ExecutionPlan, and execution statistics.

Operations inside read-write transactions might return kAborted. If this occurs, the application should restart the transaction from the beginning.

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

Callers must consume all rows from the result before execution statistics and ExecutionPlan are available.

No individual row in the ProfileQueryResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

  namespace spanner = ::google::cloud::spanner;
  spanner::SqlStatement select(
      "SELECT AlbumId, AlbumTitle, MarketingBudget"
      " FROM Albums"
      " WHERE AlbumTitle >= 'Aardvark' AND AlbumTitle < 'Goo'");
  auto profile_query_result = client.ProfileQuery(std::move(select));
  for (auto& row : profile_query_result) {
    if (!row) throw std::move(row).status();
    // Discard rows for brevity in this example.
  }
 
  // Stats are only available after all rows from the result have been read.
  auto execution_stats = profile_query_result.ExecutionStats();
  if (execution_stats) {
    for (auto const& stat : *execution_stats) {
      std::cout << stat.first << ":\t" << stat.second << "\n";
    }
  }

Parameters

statement	The SQL statement to execute.
opts	(optional) The Options to use for this call. If given, these will take precedence over the options set at the client and environment levels.
transaction_options	Execute this query in a single-use transaction with these options.

ProfileQuery() [8/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( Transaction::SingleUseOptions  transaction_options, SqlStatement  statement, QueryOptions const &  opts  )

inline

Profiles a SQL query.

See also

ProfileQuery(Transaction::SingleUseOptions,SqlStatement,Options)

ProfileQuery() [9/9]

ProfileQueryResult google::cloud::spanner::Client::ProfileQuery ( Transaction::SingleUseOptions  transaction_options, SqlStatement  statement, std::initializer_list< internal::NonConstructible >    )

inline

Profiles a SQL query.

See also

ProfileQuery(Transaction::SingleUseOptions,SqlStatement,Options)

Read() [1/10]

RowStream google::cloud::spanner::Client::Read	(	ReadPartition const &	partition,
		Options	opts = {}
	)

Reads rows from a subset of rows in a database.

Requires a prior call to PartitionRead to obtain the partition information; see the documentation of that method for full details.

Note

No individual row in the ReadResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

  google::cloud::StatusOr<spanner::ReadPartition> partition =
      remote_connection.ReceiveReadPartitionFromRemoteMachine();
  if (!partition) throw std::move(partition).status();
  for (auto& row : client.Read(*partition)) {
    if (row.status().code() ==                           
        google::cloud::StatusCode::kPermissionDenied) {  
      continue;                                          
    }                                                    
    if (!row) throw std::move(row).status();
    ProcessRow(*row);
  }

Parameters

partition	A ReadPartition, obtained by calling PartitionRead.
opts	Options used for this request.

Read() [2/10]

RowStream google::cloud::spanner::Client::Read	(	std::string	table,
		KeySet	keys,
		std::vector< std::string >	columns,
		Options	opts = {}
	)

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

No individual row in the ReadResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

void ReadData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  auto rows = client.Read("Albums", google::cloud::spanner::KeySet::All(),
                          {"SingerId", "AlbumId", "AlbumTitle"});
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumId: " << std::get<1>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<2>(*row) << "\n";
  }
 
  std::cout << "Read completed for [spanner_read_data]\n";
}

Parameters

table	The name of the table in the database to be read.
keys	Identifies the rows to be yielded. If read_options.index_name is set, names keys in that index; otherwise names keys in the primary index of table. It is not an error for keys to name rows that do not exist in the database; Read yields nothing for nonexistent rows.
columns	The columns of table to be returned for each row matching this request.
opts	Options used for this request.

Read() [3/10]

RowStream google::cloud::spanner::Client::Read ( std::string  table, KeySet  keys, std::vector< std::string >  columns, ReadOptions const &  read_options  )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(std::string,KeySet,std::vector<std::string>,Options)

Read() [4/10]

RowStream google::cloud::spanner::Client::Read ( std::string  table, KeySet  keys, std::vector< std::string >  columns, std::initializer_list< internal::NonConstructible >    )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(std::string,KeySet,std::vector<std::string>,Options)

Read() [5/10]

RowStream google::cloud::spanner::Client::Read	(	Transaction	transaction,
		std::string	table,
		KeySet	keys,
		std::vector< std::string >	columns,
		Options	opts = {}
	)

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

No individual row in the ReadResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

void ReadData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  auto rows = client.Read("Albums", google::cloud::spanner::KeySet::All(),
                          {"SingerId", "AlbumId", "AlbumTitle"});
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumId: " << std::get<1>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<2>(*row) << "\n";
  }
 
  std::cout << "Read completed for [spanner_read_data]\n";
}

Parameters

table	The name of the table in the database to be read.
keys	Identifies the rows to be yielded. If read_options.index_name is set, names keys in that index; otherwise names keys in the primary index of table. It is not an error for keys to name rows that do not exist in the database; Read yields nothing for nonexistent rows.
columns	The columns of table to be returned for each row matching this request.
opts	Options used for this request.
transaction	Execute this read as part of an existing transaction.

Read() [6/10]

RowStream google::cloud::spanner::Client::Read ( Transaction  transaction, std::string  table, KeySet  keys, std::vector< std::string >  columns, ReadOptions const &  read_options  )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(Transaction,std::string,KeySet,std::vector<std::string>,Options)

Read() [7/10]

RowStream google::cloud::spanner::Client::Read ( Transaction  transaction, std::string  table, KeySet  keys, std::vector< std::string >  columns, std::initializer_list< internal::NonConstructible >    )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(Transaction,std::string,KeySet,std::vector<std::string>,Options)

Read() [8/10]

RowStream google::cloud::spanner::Client::Read	(	Transaction::SingleUseOptions	transaction_options,
		std::string	table,
		KeySet	keys,
		std::vector< std::string >	columns,
		Options	opts = {}
	)

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

Callers can optionally supply a Transaction or Transaction::SingleUseOptions used to create a single-use transaction - or neither, in which case a single-use transaction with default options is used.

Note

No individual row in the ReadResult can exceed 100 MiB, and no column value can exceed 10 MiB.

Example

void ReadData(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;
 
  auto rows = client.Read("Albums", google::cloud::spanner::KeySet::All(),
                          {"SingerId", "AlbumId", "AlbumTitle"});
  using RowType = std::tuple<std::int64_t, std::int64_t, std::string>;
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << "SingerId: " << std::get<0>(*row) << "\t";
    std::cout << "AlbumId: " << std::get<1>(*row) << "\t";
    std::cout << "AlbumTitle: " << std::get<2>(*row) << "\n";
  }
 
  std::cout << "Read completed for [spanner_read_data]\n";
}

Parameters

table	The name of the table in the database to be read.
keys	Identifies the rows to be yielded. If read_options.index_name is set, names keys in that index; otherwise names keys in the primary index of table. It is not an error for keys to name rows that do not exist in the database; Read yields nothing for nonexistent rows.
columns	The columns of table to be returned for each row matching this request.
opts	Options used for this request.
transaction_options	Execute this read in a single-use transaction with these options.

Read() [9/10]

RowStream google::cloud::spanner::Client::Read ( Transaction::SingleUseOptions  transaction_options, std::string  table, KeySet  keys, std::vector< std::string >  columns, ReadOptions const &  read_options  )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(Transaction::SingleUseOptions,std::string,KeySet,std::vector<std::string>,Options)

Read() [10/10]

RowStream google::cloud::spanner::Client::Read ( Transaction::SingleUseOptions  transaction_options, std::string  table, KeySet  keys, std::vector< std::string >  columns, std::initializer_list< internal::NonConstructible >    )

inline

Reads rows from the database using key lookups and scans, as a simple key/value style alternative to ExecuteQuery().

See also

Read(Transaction::SingleUseOptions,std::string,KeySet,std::vector<std::string>,Options)

Rollback()

Status google::cloud::spanner::Client::Rollback	(	Transaction	transaction,
		Options	opts = {}
	)

Rolls back a read-write transaction, releasing any locks it holds.

At any time before Commit, the client can call Rollback to abort the transaction. It is a good idea to call this for any read-write transaction that includes one or more Read, ExecuteQuery, or ExecuteDml requests and ultimately decides not to commit.

Warning

It is an error to call Rollback with a read-only transaction.

Parameters

transaction	The transaction to roll back.
opts	(optional) The options to use for this call.

Returns

The error status of the rollback.

Friends And Related Function Documentation

operator!=

bool operator!= ( Client const &  a, Client const &  b  )

friend

operator==

bool operator== ( Client const &  a, Client const &  b  )

friend