# Google.Cloud.Spanner.Data - Class SpannerBatchCommand (5.13.0-beta07)

5.13.0-beta07 5.13.0-beta06 5.12.0 (latest) 5.11.0 5.10.0 5.9.0 5.8.0 5.7.0 5.6.0 5.5.0 5.4.0 5.3.0 5.2.0 5.1.0 5.0.0 4.6.0 4.5.0 4.4.0 4.3.0 4.2.0 4.1.0 4.0.0 3.15.1 3.14.0 3.13.0 3.12.0 3.11.0 3.10.0 3.9.0 3.8.0 3.7.0 3.6.0 3.5.0

    public sealed class SpannerBatchCommand

Reference documentation and code samples for the Google.Cloud.Spanner.Data class SpannerBatchCommand.

Represents batched commands to execute against a Spanner database.
Currently only DML commands are supported in batch mode.


You can create an instance of [SpannerBatchCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand) with no
initial commands.
You can then add commands to a [SpannerBatchCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand) using the
[Add(SpannerCommandTextBuilder, SpannerParameterCollection)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand#Google_Cloud_Spanner_Data_SpannerBatchCommand_Add_Google_Cloud_Spanner_Data_SpannerCommandTextBuilder_Google_Cloud_Spanner_Data_SpannerParameterCollection_) or
[Add(string, SpannerParameterCollection)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand#Google_Cloud_Spanner_Data_SpannerBatchCommand_Add_System_String_Google_Cloud_Spanner_Data_SpannerParameterCollection_) or [Add(SpannerCommand)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand#Google_Cloud_Spanner_Data_SpannerBatchCommand_Add_Google_Cloud_Spanner_Data_SpannerCommand_) methods.


For batched DML commands use [ExecuteNonQueryAsync(CancellationToken)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand#Google_Cloud_Spanner_Data_SpannerBatchCommand_ExecuteNonQueryAsync_System_Threading_CancellationToken_) or
[ExecuteNonQuery()](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand#Google_Cloud_Spanner_Data_SpannerBatchCommand_ExecuteNonQuery) to execute the batched commands.

## Inheritance

[object](https://learn.microsoft.com/dotnet/api/system.object) \> SpannerBatchCommand

## Inherited Members

[object.GetHashCode()](https://learn.microsoft.com/dotnet/api/system.object.gethashcode) [object.GetType()](https://learn.microsoft.com/dotnet/api/system.object.gettype) [object.ToString()](https://learn.microsoft.com/dotnet/api/system.object.tostring)

## Namespace

[Google.Cloud.Spanner.Data](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data)

## Assembly

Google.Cloud.Spanner.Data.dll

## Properties

### ClientContext

    public ClientContext ClientContext { get; set; }

Client context to be attached to the request. This can be used to pass values that can be read
by any SECURE_CONTEXT() calls invoked by this request (e.g., by queries against Parameterized Secure Views).

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.ClientContext` |   |

### CommandTimeout

    public int CommandTimeout { get; set; }

Gets or sets the wait time before terminating the attempt to execute a command and generating an error.
Defaults to the timeout from the connection string.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.int32` |   |

**Remarks** A value of '0' normally indicates that no timeout should be used (it waits an infinite amount of time).
However, if you specify AllowImmediateTimeouts=true in the connection string, '0' will cause a timeout
that expires immediately. This is normally used only for testing purposes.

### CommandType

    public SpannerBatchCommandType CommandType { get; set; }

The type of this batch command. If initialy set to [None](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommandType#Google_Cloud_Spanner_Data_SpannerBatchCommandType_None), this value will be
calculated when the first command is added to the batch.

Only DML commands are currently supported in batch mode.

You can set this property freely as long as there are no commands in this bacth command.
Once there are commands in this batch command an attempt to change this property's value will throw
and [ArgumentException](https://learn.microsoft.com/dotnet/api/system.argumentexception).

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommandType` |   |

### Connection

    public SpannerConnection Connection { get; }

The connection to the data source. This is never null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerConnection` |   |

### EphemeralTransactionCreationOptions

    public SpannerTransactionCreationOptions EphemeralTransactionCreationOptions { get; set; }

Options to be used for creating the ephemeral transaction under which this command will be executed
if no explicit or ambient transaction is set.
These options will be ignored if an explicit transaction is set on the command via [CreateBatchDmlCommand()](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransaction#Google_Cloud_Spanner_Data_SpannerTransaction_CreateBatchDmlCommand)
or an ambient transaction has been started via [OpenAsync(SpannerTransactionCreationOptions, SpannerTransactionOptions, CancellationToken)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerConnection#Google_Cloud_Spanner_Data_SpannerConnection_OpenAsync_Google_Cloud_Spanner_Data_SpannerTransactionCreationOptions_Google_Cloud_Spanner_Data_SpannerTransactionOptions_System_Threading_CancellationToken_)
and similar methods.
May be null, in which case appropriate defaults will be used when needed.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransactionCreationOptions` |   |

### EphemeralTransactionOptions

    public SpannerTransactionOptions EphemeralTransactionOptions { get; }

Options to be applied to the ephemeral transaction under which this command will be executed
if no explicit or ambient transaction is set.
These options will be ignored if an explicit transaction is set on the command via [CreateBatchDmlCommand()](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransaction#Google_Cloud_Spanner_Data_SpannerTransaction_CreateBatchDmlCommand)
or an ambient transaction has been started via [OpenAsync(SpannerTransactionCreationOptions, SpannerTransactionOptions, CancellationToken)](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerConnection#Google_Cloud_Spanner_Data_SpannerConnection_OpenAsync_Google_Cloud_Spanner_Data_SpannerTransactionCreationOptions_Google_Cloud_Spanner_Data_SpannerTransactionOptions_System_Threading_CancellationToken_)
and similar methods. Won't be null.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransactionOptions` |   |

**Remarks** Even though the value of this property cannot be changed, instances of [SpannerTransactionOptions](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransactionOptions) are mutable.
This is useful for ORM and similar implementations that depend on ADO.NET for transaction and command
creation, which does not know about these Spanner specific options. These implementations may still
access transaction and commands after creation and change these options.
When an implephemeral transaction is created, this value will be cloned.

### Priority

    public Priority Priority { get; set; }

The RPC priority to use for this command. The default priority is Unspecified.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.Priority` |   |

### Tag

    public string Tag { get; set; }

The statement tag to send to Cloud Spanner for this command.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.string` |   |

### Transaction

    public SpannerTransaction Transaction { get; }

The transaction to use when executing this command. If this is null,
the command will be executed with no explicit transaction.

| **Property Value** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerTransaction` |   |

## Methods

### Add(SpannerCommand)

    public void Add(SpannerCommand command)

Adds a command to the collection of batch commands to be executed by this [SpannerBatchCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand).
Only [CommandText](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand#Google_Cloud_Spanner_Data_SpannerCommand_CommandText) and [Parameters](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand#Google_Cloud_Spanner_Data_SpannerCommand_Parameters) will be taken into
account. Other [SpannerCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand) properties like [SpannerConnection](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand#Google_Cloud_Spanner_Data_SpannerCommand_SpannerConnection)
and [DbTransaction](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand#Google_Cloud_Spanner_Data_SpannerCommand_DbTransaction) will be ignored.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `command` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommand` The command to be added. |

### Add(SpannerCommandTextBuilder, SpannerParameterCollection)

    public void Add(SpannerCommandTextBuilder commandTextBuilder, SpannerParameterCollection parameters = null)

Adds a command to the collection of batch commands to be executed by this [SpannerBatchCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand).

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `commandTextBuilder` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommandTextBuilder` A [SpannerCommandTextBuilder](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerCommandTextBuilder) representing the command to be added. Must not be null or empty. Currently only DML commands are supported in batch operations. |
| `parameters` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerParameterCollection` The parameters associated with `commandTextBuilder`. If `commandTextBuilder` doesn't require parameters then `parameters` can be either null or empty. |

### Add(string, SpannerParameterCollection)

    public void Add(string commandText, SpannerParameterCollection parameters = null)

Adds a command to the collection of batch commands to be executed by this [SpannerBatchCommand](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchCommand).

| **Parameters** ||
|---|---|
| **Name** | **Description** |
| `commandText` | `https://learn.microsoft.com/dotnet/api/system.string` The command text to be added. Must not be null or empty. Currently only DML commands are supported in batch operations. |
| `parameters` | `https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerParameterCollection` The parameters associated with `commandText`. If `commandText` doesn't require parameters then `parameters` can be either null or empty. |

### ExecuteNonQuery()

    public IEnumerable<long> ExecuteNonQuery()

Executes the batch commands sequentially.
If a command fails, execution is halted and this method will throw an [SpannerBatchNonQueryException](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchNonQueryException)
containing information about the failure and the number of affected rows by each of the commands
that executed successfully before the failure ocurred.

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.collections.generic.ienumerable-1https://learn.microsoft.com/dotnet/api/system.int64` | The number of rows affected by each of the executed commands. |

### ExecuteNonQueryAsync(CancellationToken)

    public Task<IReadOnlyList<long>> ExecuteNonQueryAsync(CancellationToken cancellationToken = default)

Executes the batch commands sequentially. The execution of this method overall is asynchronous.

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `cancellationToken` | `https://learn.microsoft.com/dotnet/api/system.threading.cancellationtoken` A cancellation token for the operation. |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://learn.microsoft.com/dotnet/api/system.threading.tasks.task-1https://learn.microsoft.com/dotnet/api/system.collections.generic.ireadonlylist-1https://learn.microsoft.com/dotnet/api/system.int64` | A task that once completed will indicate the number of rows affected by each of the executed commands. If a command fails, execution is halted and this method will return a faulted task with an [SpannerBatchNonQueryException](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Spanner.Data/latest/Google.Cloud.Spanner.Data.SpannerBatchNonQueryException) containing information about the failure and the number of affected rows by each of the commands that executed successfully before the failure ocurred. |