SNOW-817091 async executions documentation

README.md

@@ -503,6 +503,63 @@ 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 happended or reaching the maximal 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