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.
Namespace
Google.Cloud.Spanner.DataAssembly
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. |
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 |
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 |
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 |
DbConnection
protected override DbConnection DbConnection { get; set; }
Property Value | |
---|---|
Type | Description |
DbConnection |
DbParameterCollection
protected override DbParameterCollection DbParameterCollection { get; }
Property Value | |
---|---|
Type | Description |
DbParameterCollection |
DbTransaction
protected override DbTransaction DbTransaction { get; set; }
Property Value | |
---|---|
Type | Description |
DbTransaction |
DesignTimeVisible
public override bool DesignTimeVisible { get; set; }
Property Value | |
---|---|
Type | Description |
bool |
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 |
Methods
Cancel()
public override void 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 |
Dispose(bool)
protected override void Dispose(bool disposing)
Parameter | |
---|---|
Name | Description |
disposing | bool |
ExecuteDbDataReader(CommandBehavior)
protected override DbDataReader ExecuteDbDataReader(CommandBehavior behavior)
Parameter | |
---|---|
Name | Description |
behavior | CommandBehavior |
Returns | |
---|---|
Type | Description |
DbDataReader |
ExecuteDbDataReaderAsync(CommandBehavior, CancellationToken)
protected override Task<DbDataReader> ExecuteDbDataReaderAsync(CommandBehavior behavior, CancellationToken cancellationToken)
Parameters | |
---|---|
Name | Description |
behavior | CommandBehavior |
cancellationToken | CancellationToken |
Returns | |
---|---|
Type | Description |
TaskDbDataReader |
ExecuteNonQuery()
public override int ExecuteNonQuery()
Returns | |
---|---|
Type | Description |
int |
ExecuteNonQueryAsync(CancellationToken)
public override Task<int> ExecuteNonQueryAsync(CancellationToken cancellationToken)
Parameter | |
---|---|
Name | Description |
cancellationToken | CancellationToken |
Returns | |
---|---|
Type | Description |
Taskint |
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. |
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. |
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.
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 |
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 |
ExecuteScalarAsync(CancellationToken)
public override Task<object> ExecuteScalarAsync(CancellationToken cancellationToken)
Parameter | |
---|---|
Name | Description |
cancellationToken | CancellationToken |
Returns | |
---|---|
Type | Description |
Taskobject |
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(long?, long?, CancellationToken)
public Task<IReadOnlyList<CommandPartition>> GetReaderPartitionsAsync(long? partitionSizeBytes = null, long? maxPartitions = null, 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 |
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()