Method: projects.instances.databases.sessions.commit

Commits a transaction. The request includes the mutations to be applied to rows in the database.

sessions.commit might return an ABORTED 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 sessions.commit returns ABORTED, the caller should re-attempt the transaction from the beginning, re-using the same session.

On very rare occasions, sessions.commit might return UNKNOWN. This can happen, for example, if the client job experiences a 1+ hour networking failure. At that point, Cloud Spanner has lost track of the transaction outcome and we recommend that you perform another read from the database to see the state of things as they are now.

HTTP request

POST https://spanner.googleapis.com/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
session

string

Required. The session in which the transaction to be committed is running.

Authorization requires the following IAM permission on the specified resource session:

  • spanner.databases.write

Request body

The request body contains data with the following structure:

JSON representation 
{
  "mutations": [
    {
      object (Mutation)
    }
  ],
  "returnCommitStats": boolean,
  "requestOptions": {
    object (RequestOptions)
  },

  // Union field transaction can be only one of the following:
  "transactionId": string,
  "singleUseTransaction": {
    object (TransactionOptions)
  }
  // End of list of possible types for union field transaction.
}
Fields
mutations[]

object (Mutation)

The mutations to be executed when this transaction commits. All mutations are applied atomically, in the order they appear in this list.
returnCommitStats

boolean

If true, then statistics related to the transaction will be included in the CommitResponse. Default value is false.
requestOptions

object (RequestOptions)

Common options for this request.
Union field transaction. Required. The transaction in which to commit. transaction can be only one of the following:
transactionId

string (bytes format)

sessions.commit a previously-started transaction.

A base64-encoded string.
singleUseTransaction

object (TransactionOptions)

Execute mutations in a temporary transaction. Note that unlike commit of a previously-started transaction, commit with a temporary transaction is non-idempotent. That is, if the CommitRequest is sent to Cloud Spanner more than once (for instance, due to retries in the application, or in the transport library), it is possible that the mutations are executed more than once. If this is undesirable, use sessions.beginTransaction and sessions.commit instead.

Response body

If successful, the response body contains data with the following structure:

The response for sessions.commit.

JSON representation 
{
  "commitTimestamp": string,
  "commitStats": {
    object (CommitStats)
  }
}
Fields
commitTimestamp

string (Timestamp format)

The Cloud Spanner timestamp at which the transaction committed.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
commitStats

object (CommitStats)

The statistics about this sessions.commit. Not returned by default. For more information, see CommitRequest.return_commit_stats.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/spanner.data
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

Mutation

A modification to one or more Cloud Spanner rows. Mutations can be applied to a Cloud Spanner database by sending them in a sessions.commit call.

JSON representation 
{

  // Union field operation can be only one of the following:
  "insert": {
    object (Write)
  },
  "update": {
    object (Write)
  },
  "insertOrUpdate": {
    object (Write)
  },
  "replace": {
    object (Write)
  },
  "delete": {
    object (Delete)
  }
  // End of list of possible types for union field operation.
}
Fields
Union field operation. Required. The operation to perform. operation can be only one of the following:
insert

object (Write)

Insert new rows in a table. If any of the rows already exist, the write or transaction fails with error ALREADY_EXISTS.
update

object (Write)

Update existing rows in a table. If any of the rows does not already exist, the transaction fails with error NOT_FOUND.
insertOrUpdate

object (Write)

Like insert, except that if the row already exists, then its column values are overwritten with the ones provided. Any column values not explicitly written are preserved.

When using insertOrUpdate, just as when using insert, all NOT NULL columns in the table must be given a value. This holds true even when the row already exists and will therefore actually be updated.
replace

object (Write)

Like insert, except that if the row already exists, it is deleted, and the column values provided are inserted instead. Unlike insertOrUpdate, this means any values not explicitly written become NULL.

In an interleaved table, if you create the child table with the ON DELETE CASCADE annotation, then replacing a parent row also deletes the child rows. Otherwise, you must delete the child rows before you replace the parent row.
delete

object (Delete)

Delete rows from a table. Succeeds whether or not the named rows were present.

Write

Arguments to insert, update, insertOrUpdate, and replace operations.

JSON representation 
{
  "table": string,
  "columns": [
    string
  ],
  "values": [
    array
  ]
}
Fields
table

string

Required. The table whose rows will be written.
columns[]

string

The names of the columns in table to be written.

The list of columns must contain enough columns to allow Cloud Spanner to derive values for all primary key columns in the row(s) to be modified.
values[]

array (ListValue format)

The values to be written. values can contain more than one list of values. If it does, then multiple rows are written, one for each entry in values. Each list in values must have exactly as many entries as there are entries in columns above. Sending multiple lists is equivalent to sending multiple Mutations, each containing one values entry and repeating table and columns. Individual values in each list are encoded as described here.

Delete

Arguments to delete operations.

JSON representation 
{
  "table": string,
  "keySet": {
    object (KeySet)
  }
}
Fields
table

string

Required. The table whose rows will be deleted.
keySet

object (KeySet)

Required. The primary keys of the rows within table to delete. The primary keys must be specified in the order in which they appear in the PRIMARY KEY() clause of the table's equivalent DDL statement (the DDL statement used to create the table). Delete is idempotent. The transaction will succeed even if some or all rows do not exist.

CommitStats

Additional statistics about a commit.

JSON representation 
{
  "mutationCount": string
}
Fields
mutationCount

string (int64 format)

The total number of mutations for the transaction. Knowing the mutationCount value can help you maximize the number of mutations in a transaction and minimize the number of API round trips. You can also monitor this value to prevent transactions from exceeding the system limit. If the number of mutations exceeds the limit, the server returns INVALID_ARGUMENT.