Skip to main content
Apache Druid supports two query languages: Druid SQL and native queries. This document describes the SQL API.
The Druid SQL API allows you to submit SQL queries to Druid using HTTP requests. The SQL query engine provides a familiar interface for users who know SQL.

​
Query from Historicals

​
Submit a query

Submits a SQL query in JSON or text format. Returns query results with optional metadata. Each query has an associated SQL query ID. You can set this manually using the sqlQueryId context parameter, or Druid will generate one automatically and return it in the X-Druid-SQL-Query-Id response header. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql" \
--header 'Content-Type: application/json' \
--data '{
    "query": "SELECT * FROM wikipedia WHERE user='BlueMoon2662'",
    "context" : {"sqlTimeZone" : "America/Los_Angeles"},
    "header" : true,
    "typesHeader" : true,
    "sqlTypesHeader" : true
}'
​
query
string
required
SQL query string. You can include multiple SET statements to assign SQL query context parameters.
​
resultFormat
string
default:"object"
Format for query results. Options:
  • object: JSON array of objects
  • array: JSON array of arrays
  • objectLines: Newline-delimited JSON objects
  • arrayLines: Newline-delimited JSON arrays
  • csv: Comma-separated values
​
header
boolean
default:false
When true, returns column names as the first row of results.
​
typesHeader
boolean
default:false
Adds Druid runtime type information in the header. Requires header to be true.
​
sqlTypesHeader
boolean
default:false
Adds SQL type information in the header. Requires header to be true.
​
context
object
JSON object containing optional SQL query context parameters like query ID, time zone, and approximation settings.
​
parameters
array
List of query parameters for parameterized queries. Each parameter should be a JSON object with SQL data type and value.
​
results
array
Query results in the format specified by resultFormat.

​
Text Format Requests

You can also submit queries in plain text by setting Content-Type to text/plain: 
echo 'SELECT 1' | curl -H 'Content-Type: text/plain' \
  http://ROUTER_IP:ROUTER_PORT/druid/v2/sql --data @-

​
Cancel a query

Cancels a query with the specified sqlQueryId. Druid handles cancellation in a best-effort manner. 
curl --request DELETE \
  "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/request01"
​
sqlQueryId
string
required
The ID of the query to cancel.
{}

​
Query from deep storage

The sql/statements endpoint allows you to query segments that exist only in deep storage.

​
Submit a query

Submit a query for data stored in deep storage. At least part of a datasource must be available on a Historical process for Druid to plan your query. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/statements" \
--header 'Content-Type: application/json' \
--data '{
    "query": "SELECT * FROM wikipedia WHERE user='BlueMoon2662'",
    "context": {
        "executionMode":"ASYNC"
    }
}'
​
context.executionMode
string
default:"ASYNC"
Determines how query results are fetched. Currently only supports ASYNC.
​
context.selectDestination
string
Where final results are written. Set to durableStorage for large result sets (>3000 rows).
​
queryId
string
Unique identifier for the submitted query.
​
state
string
Initial state of the query (typically “ACCEPTED”).
​
schema
array
Array of column definitions with name, type, and nativeType.

​
Get query status

Retrieves the status of a query, including results information for completed queries. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/statements/query-9b93f6f7-ab0e-48f5-986a-3520f84f0804?detail=true"
​
queryId
string
required
The query ID to check status for.
​
detail
boolean
default:false
Include detailed information about stages, counters, and warnings.
​
state
string
Current query state: ACCEPTED, RUNNING, SUCCESS, or FAILED.
​
result
object
Summary of query results including row count, size, and sample records.
​
result.pages
array
Information about each page of results including row count, size, and page ID.

​
Get query results

Retrieves results for completed queries. Results are separated into pages. 
curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/statements/query-f3bca219-173d-44d4-bdc7-5002e910352f/results"
​
queryId
string
required
The query ID to retrieve results for.
​
page
integer
Specific page number to retrieve. If not specified, all results are returned.
​
resultFormat
string
default:"object"
Format for results: arrayLines, objectLines, array, object, or csv.
[
    {
        "__time": 1442018818771,
        "channel": "#en.wikipedia",
        "cityName": "",
        "comment": "added project",
        "user": "GELongstreet",
        "delta": 36,
        "added": 36,
        "deleted": 0
    }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us