Google.Cloud.Spanner.Data - Class SpannerBatchCommand (5.0.0-beta02)

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

Properties

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
`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

public SpannerBatchCommandType CommandType { get; set; }

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.

Property Value
Type	Description
`SpannerBatchCommandType`

CommitDelay

public TimeSpan? CommitDelay { get; set; }

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.

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.

Connection

public SpannerConnection Connection { get; }

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

Property Value
Type	Description
`SpannerConnection`

Priority

public Priority Priority { get; set; }

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

Property Value
Type	Description
`Priority`

Tag

public string Tag { get; set; }

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

Property Value
Type	Description
`string`

Transaction

public SpannerTransaction Transaction { get; }

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

Property Value
Type	Description
`SpannerTransaction`

Methods

Add(SpannerCommand)

public void Add(SpannerCommand command)

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.

Parameter
Name	Description
`command`	`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.

Parameters

Name Description

commandTextBuilder

SpannerCommandTextBuilder

A SpannerCommandTextBuilder representing the command to be added. Must not be null or empty. Currently only DML commands are supported in batch operations.

parameters

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.

Parameters

Name Description

commandText

string

The command text to be added. Must not be null or empty. Currently only DML commands are supported in batch operations.

parameters

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 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
`IEnumerablelong`	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`	`CancellationToken` A cancellation token for the operation.

Returns
Type	Description
`TaskIReadOnlyListlong`	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.