--- title: "POST /v1/{+session}:batchWrite" method: POST path: "/v1/{+session}:batchWrite" tags: ["projects"] --- # POST /v1/{+session}:batchWrite `POST /v1/{+session}: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, that is, some groups might have been committed successfully, while some might have failed. The results of individual batches are streamed into the response as the batches are applied. `BatchWrite` requests are not replay protected, meaning that each mutation group can be applied more than once. Replays of non-idempotent mutations can have undesirable effects. For example, replays of an insert mutation can produce an already exists error or if you use generated or commit timestamp-based keys, it can result in additional rows being added to the mutation's table. We recommend structuring your mutation groups to be idempotent to avoid this issue. ## Path parameters - `session` string, required ## Request body - BatchWriteRequest — The request for BatchWrite. - `requestOptions` RequestOptions — Common request options for various APIs. - `priority` 'PRIORITY_UNSPECIFIED' | 'PRIORITY_LOW' | 'PRIORITY_MEDIUM' | 'PRIORITY_HIGH' — Priority for the request. - `requestTag` string — A per-request tag which can be applied to queries or reads, used for statistics collection. Both `request_tag` and `transaction_tag` can be specified for a read or query that belongs to a transaction. This field is ignored for requests where it's not applicable (for example, `CommitRequest`). Legal characters for `request_tag` values are all printable characters (ASCII 32 - 126) and the length of a request_tag is limited to 50 characters. Values that exceed this limit are truncated. Any leading underscore (_) characters are removed from the string. - `transactionTag` string — A tag used for statistics collection about this transaction. Both `request_tag` and `transaction_tag` can be specified for a read or query that belongs to a transaction. To enable tagging on a transaction, `transaction_tag` must be set to the same value for all requests belonging to the same transaction, including BeginTransaction. If this request doesn't belong to any transaction, `transaction_tag` is ignored. Legal characters for `transaction_tag` values are all printable characters (ASCII 32 - 126) and the length of a `transaction_tag` is limited to 50 characters. Values that exceed this limit are truncated. Any leading underscore (_) characters are removed from the string. - `clientContext` ClientContext — Container for various pieces of client-owned context attached to a request. - `secureContext` object — Optional. Map of parameter name to value for this request. These values will be returned by any SECURE_CONTEXT() calls invoked by this request (e.g., by queries against Parameterized Secure Views). - `mutationGroups` MutationGroup[] — Required. The groups of mutations to be applied. - `mutations` Mutation[] — Required. The mutations in this group. - `insert` Write — Arguments to insert, update, insert_or_update, and replace operations. - `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[] — 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 `Mutation`s, each containing one `values` entry and repeating table and columns. Individual values in each list are encoded as described here. - unknown[] - unknown - `update` Write — Arguments to insert, update, insert_or_update, and replace operations. - `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[] — 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 `Mutation`s, each containing one `values` entry and repeating table and columns. Individual values in each list are encoded as described here. - unknown[] - unknown - `insertOrUpdate` Write — Arguments to insert, update, insert_or_update, and replace operations. - `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[] — 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 `Mutation`s, each containing one `values` entry and repeating table and columns. Individual values in each list are encoded as described here. - unknown[] - unknown - `replace` Write — Arguments to insert, update, insert_or_update, and replace operations. - `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[] — 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 `Mutation`s, each containing one `values` entry and repeating table and columns. Individual values in each list are encoded as described here. - unknown[] - unknown - `delete` Delete — Arguments to delete operations. - `table` string — Required. The table whose rows will be deleted. - `keySet` KeySet — `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All the keys are expected to be in the same table or index. The keys need not be sorted in any particular way. If the same key is specified multiple times in the set (for example if two ranges, two keys, or a key and a range overlap), Cloud Spanner behaves as if the key were only specified once. - `keys` array[] — A list of specific keys. Entries in `keys` should have exactly as many elements as there are columns in the primary or index key with which this `KeySet` is used. Individual key values are encoded as described here. - unknown[] - … - `ranges` KeyRange[] — A list of key ranges. See KeyRange for more information about key range specifications. - `startClosed` unknown[] — If the start is closed, then the range includes all rows whose first `len(start_closed)` key columns exactly match `start_closed`. - … - `startOpen` unknown[] — If the start is open, then the range excludes rows whose first `len(start_open)` key columns exactly match `start_open`. - … - `endClosed` unknown[] — If the end is closed, then the range includes all rows whose first `len(end_closed)` key columns exactly match `end_closed`. - … - `endOpen` unknown[] — If the end is open, then the range excludes rows whose first `len(end_open)` key columns exactly match `end_open`. - … - `all` boolean — For convenience `all` can be set to `true` to indicate that this `KeySet` matches all keys in the table or index. Note that any keys specified in `keys` or `ranges` are only yielded once. - `send` Send — Arguments to send operations. - `queue` string — Required. The queue to which the message will be sent. - `key` unknown[] — Required. The primary key of the message to be sent. - unknown - `deliverTime` string, google-datetime — The time at which Spanner will begin attempting to deliver the message. If `deliver_time` is not set, Spanner will deliver the message immediately. If `deliver_time` is in the past, Spanner will replace it with a value closer to the current time. - `payload` unknown - `ack` Ack — Arguments to ack operations. - `queue` string — Required. The queue where the message to be acked is stored. - `key` unknown[] — Required. The primary key of the message to be acked. - unknown - `ignoreNotFound` boolean — By default, an attempt to ack a message that does not exist will fail with a `NOT_FOUND` error. With `ignore_not_found` set to true, the ack will succeed even if the message does not exist. This is useful for unconditionally acking a message, even if it is missing or has already been acked. - `excludeTxnFromChangeStreams` boolean — Optional. If you don't set the `exclude_txn_from_change_streams` option or if it's set to `false`, then any change streams monitoring columns modified by transactions will capture the updates made within that transaction. ## Response `200` Successful response --- [API](https://skmtc.net/google/apis/spanner.md) · [All operations](https://skmtc.net/google/apis/spanner/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/google/spanner/versions/4b66067d2622/schema)