Native queries

    Native queries in Druid are JSON objects and are typically issued to the Broker or Router processes. Queries can be posted like this:

    Druid’s native query language is JSON over HTTP, although many members of the community have contributed different client libraries in other languages to query Druid.

    The Content-Type/Accept Headers can also take ‘application/x-jackson-smile’.

    Note: If Accept header is not provided, it defaults to value of ‘Content-Type’ header.

    Even though queries are typically made to Brokers or Routers, they can also be accepted by processes and by Peons (task JVMs)) that are running stream ingestion tasks. This may be valuable if you want to query results for specific segments that are served by specific processes.

    Druid has numerous query types for various use cases. Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The documentation for the various query types describe all the JSON properties that can be set.

    For aggregation queries, if more than one would satisfy your needs, we generally recommend using Timeseries or TopN whenever possible, as they are specifically optimized for their use cases. If neither is a good fit, you should use the GroupBy query, which is the most flexible.

    Queries can be cancelled explicitly using their unique identifier. If the query identifier is set at the time of query, or is otherwise known, the following endpoint can be used on the Broker or Router to cancel the query.

    If a query fails, you will get an HTTP 500 response containing a JSON object with the following structure:

    If a query request fails due to being limited by the , an HTTP 429 response with the same JSON object schema as an error response, but with errorMessage of the form: “Total query capacity exceeded” or “Query capacity exceeded for lane ‘low’”.

    The fields in the response are:

    Possible codes for the error field include:

    codedescription
    Query timeoutThe query timed out.
    The query was interrupted, possibly due to JVM shutdown.
    Query cancelledThe query was cancelled through the query cancellation API.
    Resource limit exceededThe query exceeded a configured resource limit (e.g. groupBy maxResults).
    The query was denied due to security policy. Either the user was not recognized, or the user was recognized but does not have access to the requested resource.
    Unsupported operationThe query attempted to perform an unsupported operation. This may occur when using undocumented features or when using an incompletely implemented extension.
    Unknown exceptionSome other exception occurred. Check errorMessage and errorClass for details, although keep in mind that the contents of those fields are free-form and may change from release to release.