druid/json-querying-api.md at 8a4dabc431d6b588f6a67f9583af902b362778fe

25 KiB

Raw Blame History

id	title	sidebar_label
json-querying-api	JSON querying API	JSON querying

This topic describes the API endpoints to submit JSON-based native queries to Apache Druid.

In this topic, http://SERVICE_IP:SERVICE_PORT is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace http://ROUTER_IP:ROUTER_PORT with http://localhost:8888.

Submit a query

Submits a JSON-based native query. The body of the request is the native query itself.

Druid supports different types of queries for different use cases. All queries require the following properties:

queryType: A string representing the type of query. Druid supports the following native query types: timeseries, topN, groupBy, timeBoundaries, segmentMetadata, datasourceMetadata, scan, and search.
dataSource: A string or object defining the source of data to query. The most common value is the name of the datasource to query. For more information, see Datasources.

For additional properties based on your query type or use case, see available native queries.

URL

POST /druid/v2/

Query parameters

pretty (optional)
- Druid returns the response in a pretty-printed format using indentation and line breaks.

Responses

Successfully submitted query

Error thrown due to bad query. Returns a JSON object detailing the error with the following format:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error.",
    "errorClass": "Class of exception that caused this error.",
    "host": "The host on which the error occurred."
}

For more information on possible error messages, see query execution failures.

Example query: `topN`

The following example shows a topN query. The query analyzes the social_media datasource to return the top five users from the username dimension with the highest number of views from the views metric.

curl "http://ROUTER_IP:ROUTER_PORT/druid/v2?pretty=null" \
--header 'Content-Type: application/json' \
--data '{
  "queryType": "topN",
  "dataSource": "social_media",
  "dimension": "username",
  "threshold": 5,
  "metric": "views",
  "granularity": "all",
  "aggregations": [
    {
      "type": "longSum",
      "name": "views",
      "fieldName": "views"
    }
  ],
  "intervals": [
    "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"
  ]
}'

POST /druid/v2?pretty=null HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 336

{
  "queryType": "topN",
  "dataSource": "social_media",
  "dimension": "username",
  "threshold": 5,
  "metric": "views",
  "granularity": "all",
  "aggregations": [
    {
      "type": "longSum",
      "name": "views",
      "fieldName": "views"
    }
  ],
  "intervals": [
    "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"
  ]
}

Example response: `topN`

Click to show sample response

[
  {
      "timestamp": "2023-07-03T18:49:54.848Z",
      "result": [
          {
              "views": 11591218026,
              "username": "gus"
          },
          {
              "views": 11578638578,
              "username": "miette"
          },
          {
              "views": 11561618880,
              "username": "leon"
          },
          {
              "views": 11552609824,
              "username": "mia"
          },
          {
              "views": 11551537517,
              "username": "milton"
          }
      ]
  }
]

Example query: `groupBy`

The following example submits a JSON query of the groupBy type to retrieve the username with the highest votes to posts ratio from the social_media datasource.

In this query:

The upvoteSum aggregation calculates the sum of the upvotes for each user.
The postCount aggregation calculates the sum of posts for each user.
The upvoteToPostRatio is a post-aggregation of the upvoteSum and the postCount, divided to calculate the ratio.
The result is sorted based on the upvoteToPostRatio in descending order.

curl "http://ROUTER_IP:ROUTER_PORT/druid/v2" \
--header 'Content-Type: application/json' \
--data '{
  "queryType": "groupBy",
  "dataSource": "social_media",
  "dimensions": ["username"],
  "granularity": "all",
  "aggregations": [
    { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" },
    { "type": "count", "name": "postCount", "fieldName": "post_title" }
  ],
  "postAggregations": [
    {
      "type": "arithmetic",
      "name": "upvoteToPostRatio",
      "fn": "/",
      "fields": [
        { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" },
        { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" }
      ]
    }
  ],
  "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"],
  "limitSpec": {
    "type": "default",
    "limit": 1,
    "columns": [
      { "dimension": "upvoteToPostRatio", "direction": "descending" }
    ]
  }
}'

POST /druid/v2?pretty=null HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 817

{
  "queryType": "groupBy",
  "dataSource": "social_media",
  "dimensions": ["username"],
  "granularity": "all",
  "aggregations": [
    { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" },
    { "type": "count", "name": "postCount", "fieldName": "post_title" }
  ],
  "postAggregations": [
    {
      "type": "arithmetic",
      "name": "upvoteToPostRatio",
      "fn": "/",
      "fields": [
        { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" },
        { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" }
      ]
    }
  ],
  "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"],
  "limitSpec": {
    "type": "default",
    "limit": 1,
    "columns": [
      { "dimension": "upvoteToPostRatio", "direction": "descending" }
    ]
  }
}

Example response: `groupBy`

Click to show sample response

```json [ { "version": "v1", "timestamp": "2022-01-01T00:00:00.000Z", "event": { "upvoteSum": 8.0419541E7, "upvoteToPostRatio": 69.53014661762697, "postCount": 1156614, "username": "miette" } } ] ```

Get segment information for query

Retrieves an array that contains objects with segment information, including the server locations associated with the query provided in the request body.

URL

POST /druid/v2/candidates/

Query parameters

pretty (optional)
- Druid returns the response in a pretty-printed format using indentation and line breaks.

Responses

Successfully retrieved segment information

Error thrown due to bad query. Returns a JSON object detailing the error with the following format:

{
    "error": "A well-defined error code.",
    "errorMessage": "A message with additional details about the error.",
    "errorClass": "Class of exception that caused this error.",
    "host": "The host on which the error occurred."
}

For more information on possible error messages, see query execution failures.

Sample request

curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/candidates" \
--header 'Content-Type: application/json' \
--data '{
  "queryType": "topN",
  "dataSource": "social_media",
  "dimension": "username",
  "threshold": 5,
  "metric": "views",
  "granularity": "all",
  "aggregations": [
    {
      "type": "longSum",
      "name": "views",
      "fieldName": "views"
    }
  ],
  "intervals": [
    "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"
  ]
}'

POST /druid/v2/candidates HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
Content-Length: 336

{
  "queryType": "topN",
  "dataSource": "social_media",
  "dimension": "username",
  "threshold": 5,
  "metric": "views",
  "granularity": "all",

  "aggregations": [
    {
      "type": "longSum",
      "name": "views",
      "fieldName": "views"
    }
  ],
  "intervals": [
    "2020-01-01T00:00:00.000/2024-01-01T00:00:00.000"
  ]
}

Sample response

Click to show sample response

[
  {
      "interval": "2023-07-03T18:00:00.000Z/2023-07-03T19:00:00.000Z",
      "version": "2023-07-03T18:51:18.905Z",
      "partitionNumber": 0,
      "size": 21563693,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-03T19:00:00.000Z/2023-07-03T20:00:00.000Z",
      "version": "2023-07-03T19:00:00.657Z",
      "partitionNumber": 0,
      "size": 6057236,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-05T21:00:00.000Z/2023-07-05T22:00:00.000Z",
      "version": "2023-07-05T21:09:58.102Z",
      "partitionNumber": 0,
      "size": 223926186,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-05T21:00:00.000Z/2023-07-05T22:00:00.000Z",
      "version": "2023-07-05T21:09:58.102Z",
      "partitionNumber": 1,
      "size": 20244827,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-05T22:00:00.000Z/2023-07-05T23:00:00.000Z",
      "version": "2023-07-05T22:00:00.524Z",
      "partitionNumber": 0,
      "size": 104628051,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-05T22:00:00.000Z/2023-07-05T23:00:00.000Z",
      "version": "2023-07-05T22:00:00.524Z",
      "partitionNumber": 1,
      "size": 1603995,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-05T23:00:00.000Z/2023-07-06T00:00:00.000Z",
      "version": "2023-07-05T23:21:55.242Z",
      "partitionNumber": 0,
      "size": 181506843,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T00:00:00.000Z/2023-07-06T01:00:00.000Z",
      "version": "2023-07-06T00:02:08.498Z",
      "partitionNumber": 0,
      "size": 9170974,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T00:00:00.000Z/2023-07-06T01:00:00.000Z",
      "version": "2023-07-06T00:02:08.498Z",
      "partitionNumber": 1,
      "size": 23969632,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T01:00:00.000Z/2023-07-06T02:00:00.000Z",
      "version": "2023-07-06T01:13:53.982Z",
      "partitionNumber": 0,
      "size": 599895,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T01:00:00.000Z/2023-07-06T02:00:00.000Z",
      "version": "2023-07-06T01:13:53.982Z",
      "partitionNumber": 1,
      "size": 1627041,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T02:00:00.000Z/2023-07-06T03:00:00.000Z",
      "version": "2023-07-06T02:55:50.701Z",
      "partitionNumber": 0,
      "size": 629753,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T02:00:00.000Z/2023-07-06T03:00:00.000Z",
      "version": "2023-07-06T02:55:50.701Z",
      "partitionNumber": 1,
      "size": 1342360,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T04:00:00.000Z/2023-07-06T05:00:00.000Z",
      "version": "2023-07-06T04:02:36.562Z",
      "partitionNumber": 0,
      "size": 2131434,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T05:00:00.000Z/2023-07-06T06:00:00.000Z",
      "version": "2023-07-06T05:23:27.856Z",
      "partitionNumber": 0,
      "size": 797161,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T05:00:00.000Z/2023-07-06T06:00:00.000Z",
      "version": "2023-07-06T05:23:27.856Z",
      "partitionNumber": 1,
      "size": 1176858,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T06:00:00.000Z/2023-07-06T07:00:00.000Z",
      "version": "2023-07-06T06:46:34.638Z",
      "partitionNumber": 0,
      "size": 2148760,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T07:00:00.000Z/2023-07-06T08:00:00.000Z",
      "version": "2023-07-06T07:38:28.050Z",
      "partitionNumber": 0,
      "size": 2040748,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T08:00:00.000Z/2023-07-06T09:00:00.000Z",
      "version": "2023-07-06T08:27:31.407Z",
      "partitionNumber": 0,
      "size": 678723,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T08:00:00.000Z/2023-07-06T09:00:00.000Z",
      "version": "2023-07-06T08:27:31.407Z",
      "partitionNumber": 1,
      "size": 1437866,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T10:00:00.000Z/2023-07-06T11:00:00.000Z",
      "version": "2023-07-06T10:02:42.079Z",
      "partitionNumber": 0,
      "size": 1671296,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T11:00:00.000Z/2023-07-06T12:00:00.000Z",
      "version": "2023-07-06T11:27:23.902Z",
      "partitionNumber": 0,
      "size": 574893,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T11:00:00.000Z/2023-07-06T12:00:00.000Z",
      "version": "2023-07-06T11:27:23.902Z",
      "partitionNumber": 1,
      "size": 1427384,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T12:00:00.000Z/2023-07-06T13:00:00.000Z",
      "version": "2023-07-06T12:52:00.846Z",
      "partitionNumber": 0,
      "size": 2115172,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T14:00:00.000Z/2023-07-06T15:00:00.000Z",
      "version": "2023-07-06T14:32:33.926Z",
      "partitionNumber": 0,
      "size": 589108,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T14:00:00.000Z/2023-07-06T15:00:00.000Z",
      "version": "2023-07-06T14:32:33.926Z",
      "partitionNumber": 1,
      "size": 1392649,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T15:00:00.000Z/2023-07-06T16:00:00.000Z",
      "version": "2023-07-06T15:53:25.467Z",
      "partitionNumber": 0,
      "size": 2037851,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T16:00:00.000Z/2023-07-06T17:00:00.000Z",
      "version": "2023-07-06T16:02:26.568Z",
      "partitionNumber": 0,
      "size": 230400650,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T16:00:00.000Z/2023-07-06T17:00:00.000Z",
      "version": "2023-07-06T16:02:26.568Z",
      "partitionNumber": 1,
      "size": 38209056,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  },
  {
      "interval": "2023-07-06T17:00:00.000Z/2023-07-06T18:00:00.000Z",
      "version": "2023-07-06T17:00:02.391Z",
      "partitionNumber": 0,
      "size": 211099463,
      "locations": [
          {
              "name": "localhost:8083",
              "host": "localhost:8083",
              "hostAndTlsPort": null,
              "maxSize": 300000000000,
              "type": "historical",
              "tier": "_default_tier",
              "priority": 0
          }
      ]
  }
]

25 KiB Raw Blame History

Submit a query

URL

Query parameters

Responses

Example query: topN

Example response: topN

Example query: groupBy

Example response: groupBy

Get segment information for query

URL

Query parameters

Responses

Sample request

Sample response

25 KiB

Raw Blame History

Example query: `topN`

Example response: `topN`

Example query: `groupBy`

Example response: `groupBy`