Method QueryAsync
QueryAsync(String, QueryOptions, CancellationToken)
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)
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
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. |