Apache Druid supports two query languages: Druid SQL and native queries. This document describes the SQL language.
Asynchronous download is Generally Available (GA) for Imply Enterprise deployments only. It is not supported for other deployments, including Imply Hybrid.
Asynchronous query download (async download) lets you run longer-executing queries and retrieve the results after the queries complete. It solves problems caused when timeouts cause interruptions in the connection between query clients and the Druid cluster.
Query execution using the async download APIs is similar to that of using the synchronous APIs. Instead of one synchronous API, async download requires you to call three APIs to:
- Submit the query.
- Poll for query status.
- Fetch the result.
Use the async download API to submit and manage your asynchronous queries. As a prerequisite, enable async download as described in Async SQL download setup.
Submit a query
To start a query, send a POST request with a request payload in the same format as the SQL sync API.
When the query has been accepted, Druid returns an HTTP 202 response and a JSON object with the following fields:
asyncResultId: Unique ID for the query. This ID may be different from the queryId for native or sql queries. Always present.
state: Query state. Always present. Possible states:
INITIALIZED: The query is set up but has not yet started running.
RUNNING: The query is running. The load state of the system affects the time it takes for a query to move from
COMPLETE: The query is finished, and results are ready to fetch.
FAILED: The query failed.
UNDETERMINED: The query state is unknown. Druid accepted the query but cannot determine its state. This may occur if the Broker has gone offline longer than the value specified in
resultFormat: Result format for this query. See the SQL sync API for the available result formats. Present when state is
COMPLETE, absent otherwise.
resultLength: Size in bytes of the query results. Present when state is
COMPLETE, absent otherwise.
error: Druid query error object, as described in Query execution failures. Present when state is
FAILED, absent otherwise.
HTTP 429. Druid rejected the query due to concurrency limits. Retry the query after waiting for some time, for example 60 seconds. We recommend exponential backoff. Druid sets the query state to
HTTP 4xx or 5xx. Druid rejected the query for a reason other than concurrency. HTTP 429 will not be returned in this case. Druid sets the query state to
Get query status
Send a GET request with the query ID as shown below to check the status of the query.
When the API succeeds, it returns an HTTP 200 response with the same JSON object as described in Submit a query.
HTTP 403. The user is not authorized to get the query status. Only the user who submitted the query may view its status.
Get query results
Once a query completes, fetch the results by sending a GET request with the query ID.
Druid automatically cleans up expired query states and result files. For large results with long downloads, Druid periodically resets the retention period during the download to prevent premature cleanup of results. See Query state and result file management to configure the retention and refresh times for async downloads.
For a successful request, Druid returns an HTTP 200 response with the result file. The response contains the following HTTP headers:
Content-Length: the result file size
Content-Type: the query result format
This API returns the same results for the same query during the async download retention period, no matter how many times you call the API.
HTTP 403. The user is not authorized to get the query results. Only the user who submitted the query may view its results.
HTTP 404. Druid returns an HTTP 404 response for one of the following conditions:
Cancel a query
After you submit a query, you can subsequently cancel it using a DELETE request. Canceling a query cleans up all associated records as if you never issued the query. You can cancel queries of any state.
Druid returns an HTTP 202 response when it accepts the deletion request.
The cancellation proceeds in the background. Immediately after cancellation, the query status API may still return details for the query.
HTTP 403. The query ID originated from a different user. No one, including cluster admins, may cancel queries submitted from a different user.
HTTP 404. Druid returns an HTTP 404 response if the async result ID does not exist. This may result if Druid rejected the query or if the async result ID expired. To configure the query retention time, see Query state and result file management.
HTTP 500. Internal server error. Example:
"error": "unable to clear metadata"