Cancel QueryHub Async Query¶
POST /api/v1/df/async_query/delete
Overview¶
Cancel QueryHub tasks submitted with the same API Key in the current workspace. A query that has already started may still run until it times out, and Studio discards late results.
Prerequisites and Usage Steps¶
- Submit an asynchronous data query using the current API Key, and select the QueryHub data source.
- Obtain the task identifier starting with qhtask_ from the returned content.data[*].async_id. You must use the same Key and workspace as when the task was submitted.
- The request cancels tasks in list order. If an item fails partway through, previously canceled tasks are not rolled back; to confirm status, poll the corresponding tasks separately.
After the cancellation succeeds, you can continue to call the asynchronous query endpoint for the task: POST JSON {"queries":[{"qtype":"queryhub","async_id":"qhtask_0123456789abcdef0123456789abcdef"}]}. Within the record's validity period, a canceled task reports query_status=failed, query_error.errorCode=QueryHubTaskCancelled, is_running=false, and async_id="". Task records are retained for 300 seconds from submission by default. Within the record's validity period, canceling an already canceled task again succeeds.
Request Headers¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| DF-API-KEY | string | Y | OpenAPI access key Example: <DF-API-KEY>How to obtain or enter: Create or obtain a Key with permissions for this API in API Key Management of the target workspace. |
Body Request Parameters¶
| Parameter | Type | Required | Description |
|---|---|---|---|
| asyncIds | array | Y | QueryHub asynchronous task ID list, 1 to 20 items Allow null: False Example: ["qhtask_0123456789abcdef0123456789abcdef"]How to obtain or enter: Copy exactly from content.data[*].async_id in the QueryHub asynchronous query submission response; up to 20 items. Do not enter task identifiers for other engines. |
Request Example¶
curl 'https://openapi.guance.com/api/v1/df/async_query/delete' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"asyncIds":["qhtask_0123456789abcdef0123456789abcdef"]}'
Response¶
HTTP 200, application/json.
| Field | Type | Description |
|---|---|---|
| content | object | {} on success. The background executor may still be running; late results are not delivered to the caller. |
| Response Header | Type | Description |
|---|---|---|
| Cache-Control | string | Both successful and QueryHub error responses use no-store. |
{
"code": 200,
"content": {},
"errorCode": "",
"success": true,
"message": "",
"traceId": "trace-example"
}
Error Responses¶
For authentication, rate limiting, and common request errors, see Common Error Definitions.
| HTTP Status | errorCode | Trigger Condition | Message or Response Description | Handling |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | Field type, required status, or constraints do not conform to the parameter table | Request field validation failed; the message indicates the field or rule. | Check the field, type, and constraints. |
| 400 | ft.RequestJsonFormatError | Request JSON syntax is invalid | Request JSON format error. | Read reason, line, and column in content, then correct the request. |
| 400 | forethought.QueryHubInvalidFields | List is empty, exceeds 20 items, or is not a QueryHub task ID | The message may be empty. | Check the ID prefix and count item by item. |
| 400 | forethought.QueryHubInvalidId | qhtask_ identifier contains invalid characters or is too long | The message may be empty. | Copy the complete async_id from the task submission response. |
| 403 | forethought.QueryHubForbidden | Identity is not applicable to this API or lacks query permission | No query permission. | Use an OpenAPI Key with call permission. |
| 404 | forethought.QueryHubTaskNotFound | Task is invalid, does not exist, or does not belong to the current Key | The query task is invalid. Submit it again. | Check the workspace, Key, and task status. |
| 503 | forethought.QueryHubUnavailable | QueryHub is currently unavailable or not enabled | The query service or data source is temporarily unavailable. | Confirm that the service is enabled, then retry based on the status. |