Method: projects.instances.databases.sessions.batchWrite

Batches the supplied mutation groups in a collection of efficient transactions. All mutations in a group are committed atomically. However, mutations across groups can be committed non-atomically in an unspecified order and thus, they must be independent of each other. Partial failure is possible, i.e., some groups may have been committed successfully, while some may have failed. The results of individual batches are streamed into the response as the batches are applied.

sessions.batchWrite requests are not replay protected, meaning that each mutation group may be applied more than once. Replays of non-idempotent mutations may have undesirable effects. For example, replays of an insert mutation may produce an already exists error or if you use generated or commit timestamp-based keys, it may result in additional rows being added to the mutation's table. We recommend structuring your mutation groups to be idempotent to avoid this issue.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
session

string

Required. The session in which the batch request is to be run.

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 
{
  "requestOptions": {
    object (RequestOptions)
  },
  "mutationGroups": [
    {
      object (MutationGroup)
    }
  ]
}
Fields
requestOptions

object (RequestOptions)

Common options for this request.
mutationGroups[]

object (MutationGroup)

Required. The groups of mutations to be applied.

Response body

The result of applying a batch of mutations.

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

JSON representation 
{
  "indexes": [
    integer
  ],
  "status": {
    object (Status)
  },
  "commitTimestamp": string
}
Fields
indexes[]

integer

The mutation groups applied in this batch. The values index into the mutationGroups field in the corresponding BatchWriteRequest.
status

object (Status)

An OK status indicates success. Any other status indicates a failure.
commitTimestamp

string (Timestamp format)

The commit timestamp of the transaction that applied this batch. Present if status is OK, absent otherwise.

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

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.

MutationGroup

A group of mutations to be committed together. Related mutations should be placed in a group. For example, two mutations inserting rows with the same primary key prefix in both parent and child tables are related.

JSON representation 
{
  "mutations": [
    {
      object (Mutation)
    }
  ]
}
Fields
mutations[]

object (Mutation)

Required. The mutations in this group.