Method QueryAsync

QueryAsync(String, QueryOptions, CancellationToken)

Queries a table based on the query statement.
Declaration
public Task<QueryResult<RecordValue>> QueryAsync(string statement, QueryOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
String statement Query SQL statement.
QueryOptions options (Optional) Options for the Query operation. If not specified or null, appropriate defaults will be used. See QueryOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<QueryResult<RecordValue>> Task returning QueryResult<TRow> of RecordValue.
Remarks

Queries that include a full shard key will execute much more efficiently than more distributed queries that must go to multiple shards.

DDL-style queries such as "CREATE TABLE ..." or "DROP TABLE .." are not supported by this API. Those operations must be performed using ExecuteTableDDLAsync and similar APIs.

For performance reasons prepared queries are preferred for queries that may be reused, so you may prefer to use QueryAsync(PreparedStatement, QueryOptions, CancellationToken) over QueryAsync(String, QueryOptions, CancellationToken) if you are executing the query multiple times. Prepared queries bypass compilation of the query. They also allow for parameterized queries using bind variables.

The amount of data read by a single query request is limited by a system default and can be further limited by setting MaxReadKB. This limits the amount of data read and not the amount of data returned, which means that a query can return zero results but still have more data to read. This situation is detected by checking if ContinuationKey is returned. In addition, number of results returned by the query may be explicitly limited by setting Limit. For these reasons queries should always in a loop, acquiring more results, until ContinuationKey is null, indicating that the query is done. Inside the loop the continuation key is applied to QueryAsync by setting ContinuationKey. The example shows this pattern.

Alternatively to this method, you may call GetQueryAsyncEnumerable(String, QueryOptions, CancellationToken) and iterate over resulting IAsyncEnumerable<T>. This is equivalent to the loop described above but allows you to avoid dealing with the continuation key explicitly.

The only exception to the above are queries that definitely use a complete primary key and thus can read only a single row. These include INSERT statements as well as selects, updates or deletes of a single row based on the complete primary key. In these cases, the looping is not required, but you may still wish to check ContinuationKey to check for correctness.

Examples
Executing a query in a loop. 
var statement = "SELECT * FROM myTable";
var options = new QueryOptions();
do
{
    var result = client.Query(statement, options);
    foreach(var row in result.Rows)
    {
        // row is an instance of RecordValue
        Console.WriteLine($"Id: {row["id"]}, Name: {row["name"]}");
    }
    options.ContinuationKey = result.ContinuationKey;
}
while(options.ContinuationKey != null);
Exceptions
Type Condition
ArgumentException If statement is null or invalid or options contains invalid values.
TimeoutException Operation has timed out.
InvalidOperationException The table or the service is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also

QueryAsync(PreparedStatement, QueryOptions, CancellationToken)

Queries a table based on the prepared query statement.
Declaration
public Task<QueryResult<RecordValue>> QueryAsync(PreparedStatement preparedStatement, QueryOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
PreparedStatement preparedStatement Prepared query statement.
QueryOptions options (Optional) Options for the Query operation. If not specified or null, appropriate defaults will be used. See QueryOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<QueryResult<RecordValue>> Task returning QueryResult<TRow> of RecordValue.
Remarks
This method is similar to QueryAsync(String, QueryOptions, CancellationToken) but it executes a query that has been prepared as PreparedStatement via PrepareAsync(String, PrepareOptions, CancellationToken).
Exceptions
Type Condition
ArgumentException If preparedStatement is null or invalid or options contains invalid values or if the statement uses external variables and there is a variable that was not bound or if a variable was bound that is not present in the query.
TimeoutException Operation has timed out.
InvalidOperationException The table or the service is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also