Skip to content

Commit

Permalink
SNOW-817091 async executions documentation (#896)
Browse files Browse the repository at this point in the history
### Description
Async executions documentation.

### Checklist
- [x] Code compiles correctly
- [x] Code is formatted according to [Coding
Conventions](../CodingConventions.md)
- [x] Created tests which fail without the change (if possible)
- [x] All tests passing (`dotnet test`)
- [x] Extended the README / documentation, if necessary
- [x] Provide JIRA issue id (if possible) or GitHub issue id in PR name
  • Loading branch information
sfc-gh-knozderko authored Mar 26, 2024
1 parent 5aec6b4 commit ee0cdaa
Showing 1 changed file with 59 additions and 0 deletions.
59 changes: 59 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -503,6 +503,65 @@ Note that because this method is not available in the generic `IDataReader` inte
TimeSpan timeSpanTime = ((SnowflakeDbDataReader)reader).GetTimeSpan(13);
```

## Execute a query asynchronously on the server

You can run the query asynchronously on the server. The server responds immediately with `queryId` and continues to execute the query asynchronously.
Then you can use this `queryId` to check the query status or wait until the query is completed and get the results.
It is fine to start the query in one session and continue to query for the results in another one based on the queryId.

**Note**: There are 2 levels of asynchronous execution. One is asynchronous execution in terms of C# language (`async await`).
Another is asynchronous execution of the query by the server (you can recognize it by `InAsyncMode` containing method names, e. g. `ExecuteInAsyncMode`, `ExecuteAsyncInAsyncMode`).

Example of synchronous code starting a query to be executed asynchronously on the server:
```cs
using (SnowflakeDbConnection conn = new SnowflakeDbConnection("account=testaccount;username=testusername;password=testpassword"))
{
conn.Open();
SnowflakeDbCommand cmd = (SnowflakeDbCommand)conn.CreateCommand();
cmd.CommandText = "SELECT ...";
var queryId = cmd.ExecuteInAsyncMode();
// ...
}
```

Example of asynchronous code starting a query to be executed asynchronously on the server:
```cs
using (SnowflakeDbConnection conn = new SnowflakeDbConnection("account=testaccount;username=testusername;password=testpassword"))
{
await conn.OpenAsync(CancellationToken.None).ConfigureAwait(false);
SnowflakeDbCommand cmd = (SnowflakeDbCommand)conn.CreateCommand())
cmd.CommandText = "SELECT ...";
var queryId = await cmd.ExecuteAsyncInAsyncMode(CancellationToken.None).ConfigureAwait(false);
// ...
}
```

You can check the status of a query executed asynchronously on the server either in synchronous code:
```cs
var queryStatus = cmd.GetQueryStatus(queryId);
Assert.IsTrue(conn.IsStillRunning(queryStatus)); // assuming that the query is still running
Assert.IsFalse(conn.IsAnError(queryStatus)); // assuming that the query has not finished with error
```
or the same in an asynchronous code:
```cs
var queryStatus = await cmd.GetQueryStatusAsync(queryId, CancellationToken.None).ConfigureAwait(false);
Assert.IsTrue(conn.IsStillRunning(queryStatus)); // assuming that the query is still running
Assert.IsFalse(conn.IsAnError(queryStatus)); // assuming that the query has not finished with error
```

The following example shows how to get query results.
The operation will repeatedly check the query status until the query is completed or timeout happened or reaching the maximum number of attempts.
The synchronous code example:
```cs
DbDataReader reader = cmd.GetResultsFromQueryId(queryId);
```
and the asynchronous code example:
```cs
DbDataReader reader = await cmd.GetResultsFromQueryIdAsync(queryId, CancellationToken.None).ConfigureAwait(false);
```

**Note**: GET/PUT operations are currently not enabled for asynchronous executions.

## Executing a Batch of SQL Statements (Multi-Statement Support)

With version 2.0.18 and later of the .NET connector, you can send
Expand Down

0 comments on commit ee0cdaa

Please sign in to comment.