Learn how to submit async queries and get their status.
INSERT
, STOP ENGINE
, and ALTER ENGINE
, where keeping an HTTP connection open is both unreliable and unnecessary, and where the statement might return zero rows. In addition, tracking them can be challenging. Using an asynchronous query allows you to check the status of operations at intervals, based on the expected duration.
You should use asynchronous queries for any supported operation that may take more than a few minutes for which there are no results.
Supported asynchronous queries
SELECT
query to an Amazon S3 location.SELECT
query.INSERT
statement that groups generated numbers, periodically checks its run status, and then retrieves the row count from the example
table:
CALL fb_GetAsyncStatus
function as follows:
Column Name | Data Type | Description |
---|---|---|
account_name | TEXT | The name of the account where the asynchronous query was submitted. |
user_name | TEXT | The name of the user who submitted the asynchronous query. |
request_id | TEXT | Unique ID of the request which submitted the asynchronous query. |
query_id | TEXT | Unique ID of the asynchronous query. |
status | TEXT | Current status of the query: SUSPENDED, RUNNING, CANCELED_EXECUTION, EXECUTION_ERROR, ENDED_SUCCESSFULLY or IN_DOUBT. |
submitted_time | TIMESTAMPTZ | The time the asynchronous query was submitted. |
start_time | TIMESTAMPTZ | The time the async query was most recently started. |
end_time | TIMESTAMPTZ | If the asynchronous query is completed, the time it finished. |
error_message | TEXT | If the asynchronous query failed, the error message from the failure. |
retries | LONG | The number of times the asynchronous query has retried. |
scanned_bytes | LONG | The number of bytes scanned by the asynchronous query. |
scanned_rows | LONG | The number of rows scanned by the asynchronous query. |
Error Type | Cause | Solution |
---|---|---|
Protocol version mismatch | Using an outdated Firebolt protocol version. | Make sure your driver supports async queries. |
Query failure | The query encounters an execution error. | Check the error message in fb_GetAsyncStatus and validate the query syntax. |
Token not found | The provided async query token is invalid or expired. | Verify that the correct token is being used and that the query has not expired. |
Engine does not exist or you don’t have permission to access it | The specified Firebolt engine is not running or you don’t have permission to access it. | Start the engine before submitting the query and double check permissions. |