Google.Cloud.Spanner.Data - Class SpannerCommand (4.6.0)

public sealed class SpannerCommand : DbCommand, IComponent, IDbCommand, IDisposable, IAsyncDisposable, ICloneable

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

Represents a SQL query or command to execute against a Spanner database. If the command is a SQL query, then CommandText contains the entire SQL statement. Use ExecuteReaderAsync() to obtain results.

If the command is an update, insert or delete command, then CommandText is simply "[operation] [spanner_table]" such as "UPDATE MYTABLE" with the parameter collection containing SpannerParameter instances whose name matches a column in the target table. Use ExecuteNonQueryAsync(CancellationToken) to execute the command.

The command may also be a DDL statement such as CREATE TABLE. Use ExecuteNonQueryAsync(CancellationToken) to execute a DDL statement.

Inheritance

object > MarshalByRefObject > Component > DbCommand > SpannerCommand

Implements

IComponent, IDbCommand, IDisposable, IAsyncDisposable, ICloneable

Inherited Members

DbCommand.CreateParameter()

DbCommand.ExecuteNonQueryAsync()

DbCommand.ExecuteReader()

DbCommand.ExecuteReader(CommandBehavior)

DbCommand.ExecuteScalarAsync()

DbCommand.PrepareAsync(CancellationToken)

DbCommand.DisposeAsync()

DbCommand.Connection

DbCommand.Transaction

Component.Dispose()

Component.ToString()

Component.Container

Component.Site

Component.Disposed

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

object.GetHashCode()

object.GetType()

Namespace

Google.Cloud.Spanner.Data

Assembly

Google.Cloud.Spanner.Data.dll

Constructors

SpannerCommand()

public SpannerCommand()

Initializes a new instance of SpannerCommand, using a default command timeout.

SpannerCommand(SpannerCommandTextBuilder, SpannerConnection, SpannerTransaction, SpannerParameterCollection)

public SpannerCommand(SpannerCommandTextBuilder commandTextBuilder, SpannerConnection connection, SpannerTransaction transaction = null, SpannerParameterCollection parameters = null)

Initializes a new instance of SpannerCommand.

Parameters
Name	Description
`commandTextBuilder`	`SpannerCommandTextBuilder` The SpannerCommandTextBuilder that configures the text of this command. Must not be null.
`connection`	`SpannerConnection` The SpannerConnection that is associated with this SpannerCommand. Must not be null.
`transaction`	`SpannerTransaction` An optional SpannerTransaction created through BeginTransactionAsync(CancellationToken). May be null.
`parameters`	`SpannerParameterCollection` An optional collection of SpannerParameter that is used in the command. May be null.

Remarks

The initial command timeout is taken from the options associated with connection.

SpannerCommand(SpannerConnection, SpannerTransaction, CommandPartition)

public SpannerCommand(SpannerConnection connection, SpannerTransaction transaction, CommandPartition commandPartition)

Initializes a new instance of SpannerCommand.

Parameters
Name	Description
`connection`	`SpannerConnection` The SpannerConnection that is associated with this SpannerCommand. Must not be null.
`transaction`	`SpannerTransaction` The SpannerTransaction used when creating the CommandPartition.
`commandPartition`	`CommandPartition` The partition which this command is restricted to. See BeginReadOnlyTransaction(TransactionId)

SpannerCommand(string, SpannerConnection, SpannerTransaction, SpannerParameterCollection)

public SpannerCommand(string commandText, SpannerConnection connection, SpannerTransaction transaction = null, SpannerParameterCollection parameters = null)

Initializes a new instance of SpannerCommand

Parameters
Name	Description
`commandText`	`string` If this command is a SQL Query, then commandText is the SQL statement. If its an update, insert or delete command, then this text is "[operation] [table]" such as "UPDATE MYTABLE"
`connection`	`SpannerConnection` The SpannerConnection that is associated with this SpannerCommand. Must not be null.
`transaction`	`SpannerTransaction` An optional SpannerTransaction created through . May be null.
`parameters`	`SpannerParameterCollection` An optional collection of SpannerParameter that is used in the command. May be null.

Properties

CommandText

public override string CommandText { get; set; }

Property Value
Type	Description
`string`

Overrides

DbCommand.CommandText

CommandTimeout

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

Overrides

DbCommand.CommandTimeout

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 override CommandType CommandType { get; set; }

Property Value
Type	Description
`CommandType`

Overrides

DbCommand.CommandType

DbConnection

protected override DbConnection DbConnection { get; set; }

Property Value
Type	Description
`DbConnection`

Overrides

DbCommand.DbConnection

DbParameterCollection

protected override DbParameterCollection DbParameterCollection { get; }

Property Value
Type	Description
`DbParameterCollection`

Overrides

DbCommand.DbParameterCollection

DbTransaction

protected override DbTransaction DbTransaction { get; set; }

Property Value
Type	Description
`DbTransaction`

Overrides

DbCommand.DbTransaction

DesignTimeVisible

public override bool DesignTimeVisible { get; set; }

Property Value
Type	Description
`bool`

Overrides

DbCommand.DesignTimeVisible

KeySet

public KeySet KeySet { get; }

The keys of the rows that should be read from the target table if the command is Read, or null otherwise.

Property Value
Type	Description
`KeySet`

Parameters

public SpannerParameterCollection Parameters { get; }

The parameters of the SQL statement or command.

Property Value
Type	Description
`SpannerParameterCollection`

Partition

public CommandPartition Partition { get; set; }

The optional partition which this command is restricted to. If set, the command runs only on the data associated with the given partition. Setting this property overrides any values in CommandText and Parameters

Property Value
Type	Description
`CommandPartition`

Priority

public Priority Priority { get; set; }

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

Property Value
Type	Description
`Priority`

QueryOptions

public QueryOptions QueryOptions { get; set; }

Query options to use when running SQL and streaming SQL commands.

Property Value
Type	Description
`QueryOptions`

SpannerConnection

public SpannerConnection SpannerConnection { get; set; }

The connection to the data source.

Property Value
Type	Description
`SpannerConnection`

Tag

public string Tag { get; set; }

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

Property Value
Type	Description
`string`

UpdatedRowSource

public override UpdateRowSource UpdatedRowSource { get; set; }

Property Value
Type	Description
`UpdateRowSource`

Overrides

DbCommand.UpdatedRowSource

Methods

Cancel()

public override void Cancel()

Overrides

DbCommand.Cancel()

Clone()

public object Clone()

Returns a copy of this SpannerCommand.

Returns
Type	Description
`object`	a copy of this SpannerCommand.

CreateDbParameter()

protected override DbParameter CreateDbParameter()

Returns
Type	Description
`DbParameter`

Overrides

DbCommand.CreateDbParameter()

Dispose(bool)

protected override void Dispose(bool disposing)

Parameter
Name	Description
`disposing`	`bool`

Overrides

Component.Dispose(bool)

ExecuteDbDataReader(CommandBehavior)

protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)

Parameter
Name	Description
`behavior`	`CommandBehavior`

Returns
Type	Description
`DbDataReader`

Overrides

DbCommand.ExecuteDbDataReader(CommandBehavior)

ExecuteDbDataReaderAsync(CommandBehavior, CancellationToken)

protected override Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)

Parameters
Name	Description
`behavior`	`CommandBehavior`
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`TaskDbDataReader`

Overrides

DbCommand.ExecuteDbDataReaderAsync(CommandBehavior, CancellationToken)

ExecuteNonQuery()

public override int ExecuteNonQuery()

Returns
Type	Description
`int`

Overrides

DbCommand.ExecuteNonQuery()

ExecuteNonQueryAsync(CancellationToken)

public override Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)

Parameter
Name	Description
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`Taskint`

Overrides

DbCommand.ExecuteNonQueryAsync(CancellationToken)

ExecutePartitionedUpdate()

public long ExecutePartitionedUpdate()

Executes this command as a partitioned update. The command must be a generalized DML command; CreateDmlCommand(string, SpannerParameterCollection) for details.

Returns
Type	Description
`long`	A lower bound for the number of rows affected.

Remarks

The command is executed in parallel across multiple partitions, and automatically committed as it executes. This operation is not atomic: if it is cancelled part way through, the data that has already been updated will remain updated. Additionally, it is performed "at least once" in each partition; if the statement is non-idempotent (for example, incrementing a column) then the update may be performed more than once on a given row. This command must not be part of any other transaction.

ExecutePartitionedUpdateAsync(CancellationToken)

public Task<long> ExecutePartitionedUpdateAsync(CancellationToken cancellationToken = default)

Executes this command as a partitioned update. The command must be a generalized DML command; CreateDmlCommand(string, SpannerParameterCollection) for details.

Parameter
Name	Description
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`Tasklong`	A task whose result is a lower bound for the number of rows affected.

Remarks

ExecuteReaderAsync()

public Task<SpannerDataReader> ExecuteReaderAsync()

Sends the command to Cloud Spanner and builds a SpannerDataReader.

Returns
Type	Description
`TaskSpannerDataReader`	An asynchronous Task that produces a SpannerDataReader.

ExecuteReaderAsync(TimestampBound, CancellationToken)

public Task<DbDataReader> ExecuteReaderAsync(TimestampBound singleUseReadSettings, CancellationToken cancellationToken = default)

Executes the command against the SpannerConnection.

Parameters
Name	Description
`singleUseReadSettings`	`TimestampBound` The settings to use for the implicit single-use read-only transaction.
`cancellationToken`	`CancellationToken` A cancellation token for the operation.

Returns
Type	Description
`TaskDbDataReader`	A SpannerDataReader.

Remarks

This method is thread safe.

ExecuteReaderAsync(CommandBehavior)

public Task<SpannerDataReader> ExecuteReaderAsync(CommandBehavior behavior)

Sends the command to Cloud Spanner and builds a SpannerDataReader.

Parameter
Name	Description
`behavior`	`CommandBehavior` Options for statement execution and data retrieval.

Returns
Type	Description
`TaskSpannerDataReader`	An asynchronous Task that produces a SpannerDataReader.

ExecuteReaderAsync(CommandBehavior, CancellationToken)

public Task<SpannerDataReader> ExecuteReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)

Sends the command to Cloud Spanner and builds a SpannerDataReader.

Parameters
Name	Description
`behavior`	`CommandBehavior` Options for statement execution and data retrieval.
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`TaskSpannerDataReader`	An asynchronous Task that produces a SpannerDataReader.

ExecuteReaderAsync(CancellationToken)

public Task<SpannerDataReader> ExecuteReaderAsync(CancellationToken cancellationToken)

Sends the command to Cloud Spanner and builds a SpannerDataReader.

Parameter
Name	Description
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`TaskSpannerDataReader`	An asynchronous Task that produces a SpannerDataReader.

ExecuteScalar()

public override object ExecuteScalar()

Returns
Type	Description
`object`

Overrides

DbCommand.ExecuteScalar()

ExecuteScalarAsync(CancellationToken)

public override Task<object> ExecuteScalarAsync(CancellationToken cancellationToken)

Parameter
Name	Description
`cancellationToken`	`CancellationToken`

Returns
Type	Description
`Taskobject`

Overrides

DbCommand.ExecuteScalarAsync(CancellationToken)

ExecuteScalarAsync<T>(CancellationToken)

public Task<T> ExecuteScalarAsync<T>(CancellationToken cancellationToken = default)

Executes the query and returns the first column of the first row in the result set returned by the query. All other columns and rows are ignored. The return value is converted to type T if possible. This method is thread safe.

Parameter
Name	Description
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`Task`	The first column of the first row resulting from execution of the query.

Type Parameter

Name Description

T

The expected return type. If possible the return type will be converted to this type. If conversion is requested between incompatible types, an InvalidOperationException will be thrown. If the conversion fails due to the contents returned (for example a string representing a boolean does not have either 'true' or 'false') then a FormatException exception will be thrown as documented by the Convert class.

GetReaderPartitionsAsync(PartitionOptions, CancellationToken)

public Task<IReadOnlyList<CommandPartition>> GetReaderPartitionsAsync(PartitionOptions options, CancellationToken cancellationToken = default)

Creates a set of CommandPartition objects that are used to execute a query or read operation in parallel. Each of the returned command partitions are used by CreateCommandWithPartition(CommandPartition, SpannerTransaction) to create a new SpannerCommand that returns a subset of data.

Parameters
Name	Description
`options`	`PartitionOptions` The PartitionOptions used to create and read partitions.
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`TaskIReadOnlyListCommandPartition`	The list of partitions that can be used to create SpannerCommand objects.

GetReaderPartitionsAsync(long?, long?, CancellationToken)

[Obsolete("This method is deprecated, please use GetReaderPartitionsAsync(PartitionOptions, CancellationToken) instead.")]
public Task<IReadOnlyList<CommandPartition>> GetReaderPartitionsAsync(long? partitionSizeBytes = null, long? maxPartitions = null, CancellationToken cancellationToken = default)

Parameters
Name	Description
`partitionSizeBytes`	`long` The desired data size for each partition generated. The default for this option is currently 1 GiB. This is only a hint. The actual size of each partition may be smaller or larger than this size request.
`maxPartitions`	`long` The desired maximum number of partitions to return. For example, this may be set to the number of workers available. The default for this option is currently 10,000. The maximum value is currently 200,000. This is only a hint. The actual number of partitions returned may be smaller or larger than this maximum count request.
`cancellationToken`	`CancellationToken` An optional token for canceling the call.

Returns
Type	Description
`TaskIReadOnlyListCommandPartition`	The list of partitions that can be used to create SpannerCommand objects.

Prepare()

public override void Prepare()

Overrides

DbCommand.Prepare()