Class PreparedStatement

Namespace

Apache.Arrow.Flight.Sql

Assembly

Apache.Arrow.Flight.Sql.dll

public class PreparedStatement : IDisposable, IAsyncDisposable

Inheritance

object

PreparedStatement

Implements

IDisposable

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

PreparedStatement(FlightSqlClient, string, Schema, Schema)

Initializes a new instance of the PreparedStatement class.

public PreparedStatement(FlightSqlClient client, string handle, Schema datasetSchema, Schema parameterSchema)

Parameters

client FlightSqlClient

The Flight SQL client used for executing SQL operations.

handle string

The handle representing the prepared statement.

datasetSchema Schema

The schema of the result dataset.

parameterSchema Schema

The schema of the parameters for this prepared statement.

Properties

DatasetSchema

public Schema DatasetSchema { get; }

Property Value

Schema

Handle

public string Handle { get; }

Property Value

string

IsClosed

public bool IsClosed { get; }

Property Value

bool

ParameterSchema

public Schema ParameterSchema { get; }

Property Value

Schema

ParametersBatch

public RecordBatch? ParametersBatch { get; }

Property Value

RecordBatch

Methods

BindParametersAsync(FlightDescriptor, RecordBatch, FlightCallOptions?, CancellationToken)

Binds parameters to the prepared statement by streaming the given RecordBatch to the server asynchronously.

public Task<ByteString> BindParametersAsync(FlightDescriptor descriptor, RecordBatch parameterBatch, FlightCallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

descriptor FlightDescriptor

The FlightDescriptor that identifies the statement or command being executed.

parameterBatch RecordBatch

The RecordBatch containing the parameters to bind to the prepared statement.

options FlightCallOptions

The FlightCallOptions for the operation, which may include timeouts, headers, and other options for the call.

cancellationToken CancellationToken

Cancellation token

Returns

Task<ByteString>

A Task<TResult> that represents the asynchronous operation. The task result contains the metadata from the server after binding the parameters.

Exceptions

ArgumentNullException

Thrown when parameterBatch is null.

InvalidOperationException

Thrown if the operation is canceled or if there is an error during the DoPut operation.

CloseAsync(FlightCallOptions?, CancellationToken)

Closes the prepared statement asynchronously.

public Task CloseAsync(FlightCallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options FlightCallOptions

The options used to configure the Flight call.

cancellationToken CancellationToken

Cancellation token

Returns

Task

A task representing the asynchronous operation.

Exceptions

InvalidOperationException

Thrown if closing the prepared statement fails.

Dispose()

Disposes of the resources used by the prepared statement.

public void Dispose()

Dispose(bool)

Disposes of the resources used by the prepared statement.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Whether the method is called from Dispose().

DisposeAsync()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources asynchronously.

public ValueTask DisposeAsync()

Returns

ValueTask

A task that represents the asynchronous dispose operation.

ExecuteAsync(FlightCallOptions?, CancellationToken)

Executes the prepared statement asynchronously and retrieves the query results as FlightInfo.

public Task<FlightInfo> ExecuteAsync(FlightCallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options FlightCallOptions

Optional FlightCallOptionsThe FlightCallOptions for the operation, which may include timeouts, headers, and other options for the call.

cancellationToken CancellationToken

Optional CancellationToken to observe while waiting for the task to complete. The task will be canceled if the token is canceled.

Returns

Task<FlightInfo>

A Task<TResult> representing the asynchronous operation. The task result contains the FlightInfo describing the executed query results.

Exceptions

InvalidOperationException

Thrown if the prepared statement is closed or if there is an error during execution.

OperationCanceledException

Thrown if the operation is canceled by the cancellationToken.

ExecuteUpdateAsync(RecordBatch, FlightCallOptions?, CancellationToken)

Executes a prepared update statement asynchronously with the provided parameter batch.

public Task<long> ExecuteUpdateAsync(RecordBatch parameterBatch, FlightCallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

parameterBatch RecordBatch

A RecordBatch containing the parameters to be bound to the update statement. This batch should match the schema expected by the prepared statement.

options FlightCallOptions

The FlightCallOptions for this execution, containing headers and other options.

cancellationToken CancellationToken

Cancellation token

Returns

Task<long>

A Task<TResult> representing the asynchronous operation. The task result contains the number of rows affected by the update.

Examples

The following example demonstrates how to use the ExecuteUpdateAsync(RecordBatch, FlightCallOptions?, CancellationToken) method to execute an update operation:

var parameterBatch = CreateParameterBatch();
var affectedRows = await preparedStatement.ExecuteUpdateAsync(new FlightCallOptions(), parameterBatch);
Console.WriteLine($"Rows affected: {affectedRows}");

Remarks

This method executes an update operation using a prepared statement. The provided parameterBatch is bound to the statement, and the operation is sent to the server. The server processes the update and returns metadata indicating the number of affected rows.

This operation is asynchronous and can be canceled via the provided cancellationToken.

Exceptions

ArgumentNullException

Thrown if parameterBatch is null, as a valid parameter batch is required for execution.

InvalidOperationException

Thrown if the update operation fails for any reason, including when the server returns invalid or empty metadata, or if the operation is canceled via the cancellationToken.

GetSchemaAsync(FlightCallOptions?, CancellationToken)

Retrieves the schema associated with the prepared statement asynchronously.

public Task<Schema> GetSchemaAsync(FlightCallOptions? options = null, CancellationToken cancellationToken = default)

Parameters

options FlightCallOptions

The options used to configure the Flight call.

cancellationToken CancellationToken

Cancellation token

Returns

Task<Schema>

A task representing the asynchronous operation, which returns the schema of the result set.

Exceptions

InvalidOperationException

Thrown when the schema is empty or invalid.

ParseResponseAsync(FlightSqlClient, IAsyncEnumerable<FlightData>)

Parses the response of a prepared statement execution from the FlightData stream.

public Task<PreparedStatement> ParseResponseAsync(FlightSqlClient client, IAsyncEnumerable<FlightData> results)

Parameters

client FlightSqlClient

The Flight SQL client.

results IAsyncEnumerable<FlightData>

The asynchronous stream of FlightData objects.

Returns

Task<PreparedStatement>

A task representing the asynchronous operation, which returns the populated PreparedStatement.

Exceptions

ArgumentNullException

Thrown if client or results is null.

InvalidOperationException

Thrown if the prepared statement handle or data is invalid.

ReadResultAsync(IAsyncEnumerable<FlightData>, IMessage)

Reads the result from an asynchronous stream of FlightData and populates the provided Protobuf message.

public Task ReadResultAsync(IAsyncEnumerable<FlightData> results, IMessage message)

Parameters

results IAsyncEnumerable<FlightData>

The asynchronous stream of FlightData objects.

message IMessage

The Protobuf message to populate with the data from the stream.

Returns

Task

A task that represents the asynchronous read operation.

Exceptions

ArgumentNullException

Thrown if results or message is null.

InvalidOperationException

Thrown if parsing the data fails.

SetParameters(RecordBatch)

Binds the specified parameter batch to the prepared statement and returns the status.

public void SetParameters(RecordBatch parameterBatch)

Parameters

parameterBatch RecordBatch

The RecordBatch containing parameters to bind to the statement.

Exceptions

ArgumentNullException

Thrown if parameterBatch is null.