Class Client (2.20.0)

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.

See Also

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

See Also

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

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.

See Also

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

See Also

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

See Also

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

See Also

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

See Also

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

See Also

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

See Also

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

See Also

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

See Also

ExecuteQuery(SqlStatement,Options)

See Also

ExecuteQuery(SqlStatement,Options)

See Also

ExecuteQuery(Transaction::SingleUseOptions,SqlStatement,Options)

See Also

ExecuteQuery(Transaction::SingleUseOptions,SqlStatement,Options)

See Also

ExecuteQuery(Transaction,SqlStatement,Options)

See Also

ExecuteQuery(Transaction,SqlStatement,Options)

See Also

ExecuteQuery(QueryPartition const&,Options)

See Also

ExecuteQuery(QueryPartition const&,Options)

See Also

ProfileQuery(SqlStatement,Options)

See Also

ProfileQuery(SqlStatement,Options)

See Also

ProfileQuery(Transaction::SingleUseOptions,SqlStatement,Options)

See Also

ProfileQuery(Transaction::SingleUseOptions,SqlStatement,Options)

See Also

ProfileQuery(Transaction,SqlStatement,Options)

See Also

ProfileQuery(Transaction,SqlStatement,Options)

See Also

ExecuteDml(Transaction,SqlStatement,Options)

See Also

ExecuteDml(Transaction,SqlStatement,Options)

See Also

ExecuteQuery(SqlStatement,Options)

See Also

ExecuteQuery(SqlStatement,Options)

See Also

AnalyzeSql(Transaction,SqlStatement,Options)

See Also

AnalyzeSql(Transaction,SqlStatement,Options)

See Also

ExecutePartitionedDml(SqlStatement,Options)

See Also

ExecutePartitionedDml(SqlStatement,Options)

See Also

PartitionQuery(Transaction,SqlStatement,Options)

See Also

PartitionQuery(Transaction,SqlStatement,Options)

See Also

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

See Also

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

See Also

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

See Also

Commit(Mutations,Options)

See Also

Commit(Mutations,Options)

See Also

Commit(Transaction,Mutations,Options)

See Also

Commit(Transaction,Mutations,Options)

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.

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";
}

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.

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";
}

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.

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";
}

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

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) throw std::move(row).status();
    ProcessRow(*row);
  }

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);
  }

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.

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";
}

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

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

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();
}

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

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) throw std::move(row).status();
    ProcessRow(*row);
  }

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.

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";
    }
  }

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.

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";
    }
  }

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.

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";
    }
  }

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);
  }

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

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;

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.

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";
    }
  }

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.

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");
  }

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.

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";
}

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";
}

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();

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.

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).

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.

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();
  }

All mutations within a group are committed atomically. There is no atomicity or ordering between groups however, so all groups must be independent of each other.

Partial failure is possible. That is, some groups can commit successfully while others fail. The results of individual batches are returned via the response stream as their transactions complete.

Mutation groups are not replay protected. That is, it is possible that each mutation group may be applied more than once. If the mutations are not idempotent, this may lead to a failure. For example, replays of an insert mutation might produce an "already exists" error, or, if you use generated or commit-timestamp-based keys, might result in additional rows being added to the mutation's table. We recommend structuring your mutation groups to be idempotent to avoid this issue.

Example

  namespace spanner = ::google::cloud::spanner;
  // Use upserts as mutation groups are not replay protected.
  auto commit_results = client.CommitAtLeastOnce({
      // group #0
      spanner::Mutations{
          spanner::InsertOrUpdateMutationBuilder(
              "Singers", {"SingerId", "FirstName", "LastName"})
              .EmplaceRow(16, "Scarlet", "Terry")
              .Build(),
      },
      // group #1
      spanner::Mutations{
          spanner::InsertOrUpdateMutationBuilder(
              "Singers", {"SingerId", "FirstName", "LastName"})
              .EmplaceRow(17, "Marc", "")
              .EmplaceRow(18, "Catalina", "Smith")
              .Build(),
          spanner::InsertOrUpdateMutationBuilder(
              "Albums", {"SingerId", "AlbumId", "AlbumTitle"})
              .EmplaceRow(17, 1, "Total Junk")
              .EmplaceRow(18, 2, "Go, Go, Go")
              .Build(),
      },
  });
  for (auto& commit_result : commit_results) {
    if (!commit_result) throw std::move(commit_result).status();
    std::cout << "Mutation group indexes [";
    for (auto index : commit_result->indexes) std::cout << " " << index;
    std::cout << " ]: ";
    if (commit_result->commit_timestamp) {
      auto const& ts = *commit_result->commit_timestamp;
      std::cout << "Committed at " << ts.get<absl::Time>().value();
    } else {
      std::cout << commit_result->commit_timestamp.status();
    }
    std::cout << "\n";
  }

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.

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";
}

See Also

Partitioned DML Transactions for an overview of Partitioned DML transactions.

See Also

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