Skip to content

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

  1. Submit an asynchronous data query using the current API Key, and select the QueryHub data source.
  2. 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.
  3. 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.

Feedback

Is this page helpful?