From f631c92647e7deba35b390d6f3c10afa40896fb6 Mon Sep 17 00:00:00 2001 From: Krzysztof Nozderko Date: Tue, 26 Mar 2024 12:58:18 +0100 Subject: [PATCH 1/3] SNOW-817091 async execution documentation --- README.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/README.md b/README.md index 41a7d61da..0f33e82af 100644 --- a/README.md +++ b/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 From 5bc558c92200297c37360b131456575767d0c045 Mon Sep 17 00:00:00 2001 From: Krzysztof Nozderko Date: Tue, 26 Mar 2024 13:52:24 +0100 Subject: [PATCH 2/3] little fix --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0f33e82af..6c57c2f94 100644 --- a/README.md +++ b/README.md @@ -549,7 +549,7 @@ Assert.IsTrue(conn.IsStillRunning(queryStatus)); // assuming that the query is s 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: +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 maximal number of attempts. The synchronous code example: ```cs DbDataReader reader = cmd.GetResultsFromQueryId(queryId); ``` From 67bbe2baf9d7c1b6a7746b8405baef32155be395 Mon Sep 17 00:00:00 2001 From: Krzysztof Nozderko Date: Tue, 26 Mar 2024 14:00:26 +0100 Subject: [PATCH 3/3] little fix --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6c57c2f94..cc7aba2ef 100644 --- a/README.md +++ b/README.md @@ -549,7 +549,9 @@ Assert.IsTrue(conn.IsStillRunning(queryStatus)); // assuming that the query is s 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 maximal number of attempts. The synchronous code example: +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); ```