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 with no initial commands. You can then add commands to a SpannerBatchCommand using the Add(SpannerCommandTextBuilder, SpannerParameterCollection) or Add(string, SpannerParameterCollection) or Add(SpannerCommand) methods.

For batched DML commands use ExecuteNonQueryAsync(CancellationToken) or ExecuteNonQuery() to execute the batched commands.

Inheritance

object

SpannerBatchCommand

Inherited Members

object.GetHashCode()

object.GetType()

object.ToString()

Namespace: Google.Cloud.Spanner.Data

Assembly: Google.Cloud.Spanner.Data.dll

Syntax

public sealed class SpannerBatchCommand

Properties

CommandTimeout

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.

Declaration

public int CommandTimeout { get; set; }

Property Value

Type	Description
int

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

The type of this batch command. If initialy set to 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.

Declaration

public SpannerBatchCommandType CommandType { get; set; }

Property Value

Type	Description
SpannerBatchCommandType

Connection

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

Declaration

public SpannerConnection Connection { get; }

Property Value

Type	Description
SpannerConnection

EphemeralTransactionCreationOptions

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() or an ambient transaction has been started via OpenAsync(SpannerTransactionCreationOptions, SpannerTransactionOptions, CancellationToken) and similar methods. May be null, in which case appropriate defaults will be used when needed.

Declaration

public SpannerTransactionCreationOptions EphemeralTransactionCreationOptions { get; set; }

Property Value

Type	Description
SpannerTransactionCreationOptions

MaxCommitDelay

The maximum amount of time the commit of the implicit transaction associated with this command, if any, may be delayed server side for batching with other commits. The bigger the delay, the better the throughput (QPS), but at the expense of commit latency. If set to Zero, commit batching is disabled. May be null, in which case commits will continue to be batched as they had been before this configuration option was made available to Spanner API consumers. May be set to any value between Zero and 500ms.

Declaration

public TimeSpan? MaxCommitDelay { get; set; }

Property Value

Type	Description
TimeSpan?

Remarks

When a batch command is executed with no explicit or ambient transaction, an implicit transaction is created and the command is executed within it. This value will be applied to the commit operation of such transaction, if there is any. Otherwise, this value will be ignored.

Priority

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

Declaration

public Priority Priority { get; set; }

Property Value

Type	Description
Priority

Tag

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

Declaration

public string Tag { get; set; }

Property Value

Type	Description
string

Transaction

The transaction to use when executing this command. If this is null, the command will be executed without a transaction.

Declaration

public SpannerTransaction Transaction { get; }

Property Value

Type	Description
SpannerTransaction

Methods

Add(SpannerCommand)

Adds a command to the collection of batch commands to be executed by this SpannerBatchCommand. Only CommandText and Parameters will be taken into account. Other SpannerCommand properties like SpannerConnection and DbTransaction will be ignored.

Declaration

public void Add(SpannerCommand command)

Parameters

Type	Name	Description
SpannerCommand	command	The command to be added.

Add(SpannerCommandTextBuilder, SpannerParameterCollection)

Adds a command to the collection of batch commands to be executed by this SpannerBatchCommand.

Declaration

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

Parameters

Type	Name	Description
SpannerCommandTextBuilder	commandTextBuilder	A SpannerCommandTextBuilder representing the command to be added. Must not be null or empty. Currently only DML commands are supported in batch operations.
SpannerParameterCollection	parameters	The parameters associated with commandTextBuilder. If commandTextBuilder doesn't require parameters then parameters can be either null or empty.

Add(string, SpannerParameterCollection)

Adds a command to the collection of batch commands to be executed by this SpannerBatchCommand.

Declaration

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

Parameters

Type	Name	Description
string	commandText	The command text to be added. Must not be null or empty. Currently only DML commands are supported in batch operations.
SpannerParameterCollection	parameters	The parameters associated with commandText. If commandText doesn't require parameters then parameters can be either null or empty.

ExecuteNonQuery()

Executes the batch commands sequentially. If a command fails, execution is halted and this method will throw an SpannerBatchNonQueryException containing information about the failure and the number of affected rows by each of the commands that executed successfully before the failure ocurred.

Declaration

public IEnumerable<long> ExecuteNonQuery()

Returns

Type	Description
IEnumerable<long>	The number of rows affected by each of the executed commands.

ExecuteNonQueryAsync(CancellationToken)

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

Declaration

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

Parameters

Type	Name	Description
CancellationToken	cancellationToken	A cancellation token for the operation.

Returns

Type	Description
Task<IReadOnlyList<long>>	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 containing information about the failure and the number of affected rows by each of the commands that executed successfully before the failure ocurred.