Apache
/
druid
mirror of https://github.com/apache/druid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[Docs] Fix API placeholder formatting (#16240)

This commit is contained in:
Katya Macedo 2024-04-12 11:19:13 -05:00 committed by GitHub
parent 3340b200db
commit 7f06a53cb1
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 394 additions and 264 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/api-reference/automatic-compaction-api.md
View File

@ -43,7 +43,7 @@ Note that this endpoint returns an HTTP `200 OK` message code even if the dataso
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/config/compaction</code>
`POST` `/druid/coordinator/v1/config/compaction`
#### Responses
@ -132,7 +132,7 @@ Removes the automatic compaction configuration for a datasource. This updates th
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/coordinator/v1/config/compaction/:dataSource</code>
`DELETE` `/druid/coordinator/v1/config/compaction/{dataSource}`
#### Responses
@ -190,7 +190,7 @@ Note that while the max compaction tasks can theoretically be set to 2147483647,
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/config/compaction/taskslots</code>
`POST` `/druid/coordinator/v1/config/compaction/taskslots`
#### Query parameters
@ -262,7 +262,7 @@ You can use this endpoint to retrieve `compactionTaskSlotRatio` and `maxCompacti
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/config/compaction</code>
`GET` `/druid/coordinator/v1/config/compaction`
#### Responses
@ -304,7 +304,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -411,7 +411,7 @@ Retrieves the automatic compaction configuration for a datasource.
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/config/compaction/:dataSource</code>
`GET` `/druid/coordinator/v1/config/compaction/{dataSource}`
#### Responses
@ -461,7 +461,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -523,7 +523,7 @@ The response contains a list of objects with the following keys:
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/config/compaction/:dataSource/history</code>
`GET` `/druid/coordinator/v1/config/compaction/{dataSource}/history`
#### Query parameters
* `interval` (optional)
@ -579,7 +579,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -683,7 +683,7 @@ Returns the total size of segments awaiting compaction for a given datasource. R
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/compaction/progress?dataSource=:dataSource</code>
`GET` `/druid/coordinator/v1/compaction/progress?dataSource={dataSource}`
#### Query parameter
* `dataSource` (required)
@ -738,7 +738,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -767,7 +767,7 @@ The `latestStatus` object has the following properties:
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/compaction/status</code>
`GET` `/druid/coordinator/v1/compaction/status`
#### Query parameters
* `dataSource` (optional)
@ -813,7 +813,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{

29
docs/api-reference/data-management-api.md
View File

@ -62,7 +62,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the segme
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/coordinator/v1/datasources/:datasource/segments/:segmentId</code>
`DELETE` `/druid/coordinator/v1/datasources/{datasource}/segments/{segmentId}`
#### Header
@ -119,7 +119,7 @@ Accept: application/json, text/plain
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -134,7 +134,7 @@ Marks the state of a segment as used, using the segment ID.
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/segments/:segmentId</code>
`POST` `/druid/coordinator/v1/datasources/segments/{segmentId}`
#### Header
@ -191,7 +191,7 @@ Accept: application/json, text/plain
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -211,7 +211,7 @@ within the specified interval that match the optional list of versions; partiall
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/:datasource/markUnused</code>
`POST` `/druid/coordinator/v1/datasources/{datasource}/markUnused`
#### Request body
@ -293,7 +293,7 @@ Content-Length: 230
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -313,7 +313,7 @@ within the specified interval that match the optional list of versions; partiall
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/:datasource/markUsed</code>
`POST` `/druid/coordinator/v1/datasources/{datasource}/markUsed`
#### Request body
@ -395,7 +395,7 @@ Content-Length: 230
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -413,7 +413,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the datas
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/coordinator/v1/datasources/:datasource</code>
`DELETE` `/druid/coordinator/v1/datasources/{datasource}`
#### Responses
@ -455,7 +455,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -473,7 +473,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the datas
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/:datasource</code>
`POST` `/druid/coordinator/v1/datasources/{datasource}`
#### Header
@ -483,6 +483,7 @@ The following headers are required for this request:
Content-Type: application/json
Accept: application/json, text/plain
```
#### Responses
<Tabs>
@ -530,7 +531,7 @@ Accept: application/json, text/plain
#### Sample response
<details>
<summary>Show sample response</summary>
<summary>View the response</summary>
```json
{
@ -547,11 +548,11 @@ The DELETE endpoint sends a [kill task](../ingestion/tasks.md) for a given inter
Note that this endpoint returns an HTTP `200 OK` response code even if the datasource doesn't exist.
This endpoint supersedes the deprecated endpoint: `DELETE /druid/coordinator/v1/datasources/:datasource?kill=true&interval=:interval`
This endpoint supersedes the deprecated endpoint: `DELETE /druid/coordinator/v1/datasources/{datasource}?kill=true&interval={interval}`
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/coordinator/v1/datasources/:datasource/intervals/:interval</code>
`DELETE` `/druid/coordinator/v1/datasources/{datasource}/intervals/{interval}`
#### Responses

27
docs/api-reference/dynamic-configuration-api.md
View File

@ -44,7 +44,7 @@ Retrieves the current Coordinator dynamic configuration. Returns a JSON object w
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/config</code>
`GET` `/druid/coordinator/v1/config`
#### Responses
@ -86,7 +86,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -120,7 +120,7 @@ For information on the supported properties, see [Dynamic configuration](../conf
#### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/config</code>
`POST` `/druid/coordinator/v1/config`
#### Header parameters
@ -226,7 +226,7 @@ Retrieves the history of changes to Coordinator dynamic configuration over an in
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/config/history</code>
`GET` `/druid/coordinator/v1/config/history`
#### Query parameters
@ -283,7 +283,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -315,7 +315,7 @@ Returns an empty response body if there is no current Overlord dynamic configura
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/worker</code>
`GET` `/druid/indexer/v1/worker`
#### Responses
@ -355,7 +355,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -380,7 +380,7 @@ For information on the supported properties, see [Overlord dynamic configuration
#### URL
<code class="postAPI">POST</code><code>/druid/indexer/v1/worker</code>
`POST` `/druid/indexer/v1/worker`
#### Header parameters
@ -466,8 +466,7 @@ Retrieves the history of changes to Overlord dynamic configuration over an inter
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/worker/history</code>
`GET` `/druid/indexer/v1/worker/history`
#### Query parameters
@ -523,7 +522,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -547,7 +546,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
Returns an array of all the worker nodes in the cluster along with its corresponding metadata.
<code class="getAPI">GET</code><code>/druid/indexer/v1/workers</code>
`GET` `/druid/indexer/v1/workers`
#### Responses
@ -589,7 +588,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -621,7 +620,7 @@ Returns an empty response body if there are no Overlord scaling events.
#### URL
<code class="getAPI">GET</code><code>/druid/indexer/v1/scaling</code>
`GET` `/druid/indexer/v1/scaling`
#### Responses

12
docs/api-reference/json-querying-api.md
View File

@ -44,7 +44,7 @@ For additional properties based on your query type or use case, see [available n
### URL
<code class="postAPI">POST</code> <code>/druid/v2/</code>
`POST` `/druid/v2`
### Query parameters
@ -148,7 +148,7 @@ Content-Length: 336
#### Example response: `topN`
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -277,7 +277,7 @@ Content-Length: 817
#### Example response: `groupBy`
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -301,9 +301,10 @@ Retrieves an array that contains objects with segment information, including the
### URL
<code class="postAPI">POST</code> <code>/druid/v2/candidates/</code>
`POST` `/druid/v2/candidates`
### Query parameters
* `pretty` (optional)
* Druid returns the response in a pretty-printed format using indentation and line breaks.
@ -330,6 +331,7 @@ Retrieves an array that contains objects with segment information, including the
"host": "The host on which the error occurred."
}
```
For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
</TabItem>
@ -404,7 +406,7 @@ Content-Length: 336
### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[

13
docs/api-reference/lookups-api.md
View File

@ -28,6 +28,7 @@ This document describes the API endpoints to configure, update, retrieve, and ma
## Configure lookups
### Bulk update
Lookups can be updated in bulk by posting a JSON object to `/druid/coordinator/v1/lookups/config`. The format of the json object is as follows:
```json
@ -212,27 +213,27 @@ These end points can be used to get the propagation status of configured lookups
### List load status of all lookups
`GET /druid/coordinator/v1/lookups/status` with optional query parameter `detailed`.
`GET` `/druid/coordinator/v1/lookups/status` with optional query parameter `detailed`.
### List load status of lookups in a tier
`GET /druid/coordinator/v1/lookups/status/{tier}` with optional query parameter `detailed`.
`GET` `/druid/coordinator/v1/lookups/status/{tier}` with optional query parameter `detailed`.
### List load status of single lookup
`GET /druid/coordinator/v1/lookups/status/{tier}/{lookup}` with optional query parameter `detailed`.
`GET` `/druid/coordinator/v1/lookups/status/{tier}/{lookup}` with optional query parameter `detailed`.
### List lookup state of all processes
`GET /druid/coordinator/v1/lookups/nodeStatus` with optional query parameter `discover` to discover tiers advertised by other Druid nodes, or by default, returning all configured lookup tiers. The default response will also include the lookups which are loaded, being loaded, or being dropped on each node, for each tier, including the complete lookup spec. Add the optional query parameter `detailed=false` to only include the 'version' of the lookup instead of the complete spec.
`GET` `/druid/coordinator/v1/lookups/nodeStatus` with optional query parameter `discover` to discover tiers advertised by other Druid nodes, or by default, returning all configured lookup tiers. The default response will also include the lookups which are loaded, being loaded, or being dropped on each node, for each tier, including the complete lookup spec. Add the optional query parameter `detailed=false` to only include the 'version' of the lookup instead of the complete spec.
### List lookup state of processes in a tier
`GET /druid/coordinator/v1/lookups/nodeStatus/{tier}`
`GET` `/druid/coordinator/v1/lookups/nodeStatus/{tier}`
### List lookup state of single process
`GET /druid/coordinator/v1/lookups/nodeStatus/{tier}/{host:port}`
`GET` `/druid/coordinator/v1/lookups/nodeStatus/{tier}/{host:port}`
## Internal API

18
docs/api-reference/retention-rules-api.md
View File

@ -48,7 +48,7 @@ Note that this endpoint returns an HTTP `200 OK` even if the datasource does not
### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/rules/:dataSource</code>
`POST` `/druid/coordinator/v1/rules/{dataSource}`
### Header parameters
@ -156,7 +156,7 @@ This request overwrites any existing rules for all datasources. To remove defaul
### URL
<code class="postAPI">POST</code> <code>/druid/coordinator/v1/rules/_default</code>
`POST` `/druid/coordinator/v1/rules/_default`
### Header parameters
@ -244,7 +244,7 @@ Retrieves all current retention rules in the cluster including the default reten
### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/rules</code>
`GET` `/druid/coordinator/v1/rules`
### Responses
@ -286,7 +286,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -313,11 +313,11 @@ Host: http://ROUTER_IP:ROUTER_PORT
Retrieves an array of rule objects for a single datasource. Returns an empty array if there are no retention rules.
Note that this endpoint returns an HTTP `200 OK` message code even if the datasource does not exist.
Note that this endpoint returns an HTTP `200 OK` message code even if the datasource doesn't exist.
### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/rules/:dataSource</code>
`GET` `/druid/coordinator/v1/rules/{dataSource}`
### Query parameters
@ -366,7 +366,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -398,7 +398,7 @@ Retrieves the audit history of rules for all datasources over an interval of tim
### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/rules/history</code>
`GET` `/druid/coordinator/v1/rules/history`
### Query parameters
@ -465,7 +465,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[

80
docs/api-reference/service-status-api.md
View File

@ -36,7 +36,7 @@ In this document, `http://SERVICE_IP:SERVICE_PORT` is a placeholder for the serv
All services support the following endpoints.
You can use each endpoint with the ports for each type of service. The following table contains port addresses for a local configuration:
You can use each endpoint with the ports for each type of service. The following table contains port addresses for a local configuration:
|Service|Port address|
| ------ | ------------ |
@ -55,7 +55,7 @@ Modify the host and port for the endpoint to match the service to query. Refer t
#### URL
<code class="getAPI">GET</code> <code>/status</code>
`GET` `/status`
#### Responses
@ -99,7 +99,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -207,7 +207,7 @@ Additional checks for readiness should use the [Historical segment readiness](#g
#### URL
<code class="getAPI">GET</code> <code>/status/health</code>
`GET` `/status/health`
#### Responses
@ -249,7 +249,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
true
@ -266,7 +266,7 @@ Modify the host and port for the endpoint to match the service to query. Refer t
#### URL
<code class="getAPI">GET</code> <code>/status/properties</code>
`GET` `/status/properties`
#### Responses
@ -308,7 +308,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -409,7 +409,6 @@ Host: http://ROUTER_IP:ROUTER_PORT
</details>
### Get node discovery status and cluster integration confirmation
Retrieves a JSON map of the form `{"selfDiscovered": true/false}`, indicating whether the node has received a confirmation from the central node discovery mechanism (currently ZooKeeper) of the Druid cluster that the node has been added to the cluster.
@ -419,7 +418,7 @@ For nodes that use Zookeeper segment discovery, a response of `{"selfDiscovered"
#### URL
<code class="getAPI">GET</code> <code>/status/selfDiscovered/status</code>
`GET` `/status/selfDiscovered/status`
#### Responses
@ -461,7 +460,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -479,7 +478,7 @@ Use this endpoint for monitoring checks that are unable to examine the response
#### URL
<code class="getAPI">GET</code> <code>/status/selfDiscovered</code>
`GET` `/status/selfDiscovered`
#### Responses
@ -538,7 +537,7 @@ Retrieves the address of the current leader Coordinator of the cluster. If any r
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/leader</code>
`GET` `/druid/coordinator/v1/leader`
#### Responses
@ -582,7 +581,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
http://localhost:8081
@ -598,7 +597,7 @@ Use this endpoint as a load balancer status check when you only want the active
#### URL
<code class="getAPI">GET</code> <code>/druid/coordinator/v1/isLeader</code>
`GET` `/druid/coordinator/v1/isLeader`
#### Responses
@ -650,7 +649,7 @@ Host: http://COORDINATOR_IP:COORDINATOR_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -668,7 +667,7 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/leader</code>
`GET` `/druid/indexer/v1/leader`
#### Responses
@ -712,7 +711,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
http://localhost:8081
@ -729,7 +728,7 @@ Use this endpoint as a load balancer status check when you only want the active
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/isLeader</code>
`GET` `/druid/indexer/v1/isLeader`
#### Responses
@ -781,7 +780,7 @@ Host: http://OVERLORD_IP:OVERLORD_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -800,7 +799,7 @@ Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by t
#### URL
<code class="getAPI">GET</code> <code>/druid/worker/v1/enabled</code>
`GET` `/druid/worker/v1/enabled`
#### Responses
@ -844,7 +843,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -860,7 +859,7 @@ Retrieves a list of active tasks being run on MiddleManager. Returns JSON list o
#### URL
<code class="getAPI">GET</code> <code>/druid/worker/v1/tasks</code>
`GET` `/druid/worker/v1/tasks`
#### Responses
@ -904,7 +903,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -921,16 +920,16 @@ Retrieves task log output stream by task ID. For normal usage, you should use th
#### URL
<code class="getAPI">GET</code> <code>/druid/worker/v1/task/:taskId/log</code>
`GET` `/druid/worker/v1/task/{taskId}/log`
### Shut down running task
Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/:taskId/shutdown`
Shuts down a running task by ID. For normal usage, you should use the `/druid/indexer/v1/task/{taskId}/shutdown`
[Tasks API](./tasks-api.md) endpoint instead.
#### URL
<code class="postAPI">POST</code> <code>/druid/worker/v1/task/:taskId/shutdown</code>
`POST` `/druid/worker/v1/task/{taskId}/shutdown`
#### Responses
<Tabs>
@ -975,7 +974,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -992,7 +991,7 @@ keyed by the combined `druid.host` and `druid.port`.
#### URL
<code class="postAPI">POST</code> <code>/druid/worker/v1/disable</code>
`POST` `/druid/worker/v1/disable`
#### Responses
@ -1034,7 +1033,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1046,12 +1045,11 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
### Enable MiddleManager
Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object
keyed by the combined `druid.host` and `druid.port`.
Enables a MiddleManager, allowing it to accept new tasks again if it was previously disabled. Returns a JSON object keyed by the combined `druid.host` and `druid.port`.
#### URL
<code class="postAPI">POST</code> <code>/druid/worker/v1/enable</code>
`POST` `/druid/worker/v1/enable`
#### Responses
@ -1093,7 +1091,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1113,7 +1111,7 @@ Use this endpoint to know when a Broker service is ready to accept queries after
#### URL
<code class="getAPI">GET</code> <code>/druid/historical/v1/loadstatus</code>
`GET` `/druid/historical/v1/loadstatus`
#### Responses
@ -1155,7 +1153,7 @@ Host: http://HISTORICAL_IP:HISTORICAL_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1171,7 +1169,7 @@ Retrieves a status code to indicate if all segments in the local cache have been
#### URL
<code class="getAPI">GET</code> <code>/druid/historical/v1/readiness</code>
`GET` `/druid/historical/v1/readiness`
#### Responses
@ -1230,7 +1228,7 @@ Retrieves a flag indicating if the Broker knows about all segments in the cluste
#### URL
<code class="getAPI">GET</code> <code>/druid/broker/v1/loadstatus</code>
`GET` `/druid/broker/v1/loadstatus`
#### Responses
@ -1272,7 +1270,7 @@ Host: http://<BROKER_IP>:<BROKER_PORT>
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1288,7 +1286,7 @@ Retrieves a status code to indicate Broker readiness. Readiness signifies the Br
#### URL
<code class="getAPI">GET</code> <code>/druid/broker/v1/readiness</code>
`GET` `/druid/broker/v1/readiness`
#### Responses
@ -1337,6 +1335,4 @@ Host: http://BROKER_IP:BROKER_PORT
#### Sample response
A successful response to this endpoint results in an empty response body.
A successful response to this endpoint results in an empty response body.

21
docs/api-reference/sql-api.md
View File

@ -44,7 +44,7 @@ Each query has an associated SQL query ID. You can set this ID manually using th
#### URL
<code class="postAPI">POST</code> <code>/druid/v2/sql</code>
`POST` `/druid/v2/sql`
#### Request body
@ -198,7 +198,7 @@ Content-Length: 192
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -320,7 +320,7 @@ Cancellation requests require READ permission on all resources used in the SQL q
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/v2/sql/:sqlQueryId</code>
`DELETE` `/druid/v2/sql/{sqlQueryId}`
#### Responses
@ -417,7 +417,7 @@ Note that at least part of a datasource must be available on a Historical proces
#### URL
<code class="postAPI">POST</code> <code>/druid/v2/sql/statements</code>
`POST` `/druid/v2/sql/statements`
#### Request body
@ -505,7 +505,7 @@ Content-Length: 134
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -631,7 +631,7 @@ Retrieves information about the query associated with the given query ID. The re
#### URL
<code class="getAPI">GET</code> <code>/druid/v2/sql/statements/:queryId</code>
`GET` `/druid/v2/sql/statements/{queryId}`
#### Responses
@ -690,7 +690,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -845,14 +845,13 @@ Host: http://ROUTER_IP:ROUTER_PORT
Retrieves results for completed queries. Results are separated into pages, so you can use the optional `page` parameter to refine the results you get. Druid returns information about the composition of each page and its page number (`id`). For information about pages, see [Get query status](#get-query-status).
If a page number isn't passed, all results are returned sequentially in the same response. If you have large result sets, you may encounter timeouts based on the value configured for `druid.router.http.readTimeout`.
Getting the query results for an ingestion query returns an empty response.
#### URL
<code class="getAPI">GET</code> <code>/druid/v2/sql/statements/:queryId/results</code>
`GET` `/druid/v2/sql/statements/{queryId}/results`
#### Query parameters
* `page` (optional)
@ -944,7 +943,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -1178,7 +1177,7 @@ Cancels a running or accepted query.
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/v2/sql/statements/:queryId</code>
`DELETE` `/druid/v2/sql/statements/{queryId}`
#### Responses

280
docs/api-reference/sql-ingestion-api.md
View File

@ -31,41 +31,87 @@ import TabItem from '@theme/TabItem';
ingestion method is right for you.
:::
The **Query** view in the web console provides a friendly experience for the multi-stage query task engine (MSQ task
engine) and multi-stage query architecture. We recommend using the web console if you do not need a programmatic
interface.
The **Query** view in the web console provides a friendly experience for the multi-stage query task engine (MSQ task engine) and multi-stage query architecture. We recommend using the web console if you don't need a programmatic interface.
When using the API for the MSQ task engine, the action you want to take determines the endpoint you use:
- `/druid/v2/sql/task` endpoint: Submit a query for ingestion.
- `/druid/indexer/v1/task` endpoint: Interact with a query, including getting its status, getting its details, or canceling it. This page describes a few of the Overlord Task APIs that you can use with the MSQ task engine. For information about Druid APIs, see the [API reference for Druid](../ingestion/tasks.md).
- `/druid/v2/sql/task`: Submit a query for ingestion.
- `/druid/indexer/v1/task`: Interact with a query, including getting its status or details, or canceling the query. This page describes a few of the Overlord Task APIs that you can use with the MSQ task engine. For information about Druid APIs, see the [API reference for Druid](../ingestion/tasks.md).
In this topic, `http://ROUTER_IP:ROUTER_PORT` is a placeholder for your Router service address and port. Replace it with the information for your deployment. For example, use `http://localhost:8888` for quickstart deployments.
## Submit a query
You submit queries to the MSQ task engine using the `POST /druid/v2/sql/task/` endpoint.
Submits queries to the MSQ task engine.
#### Request
The `/druid/v2/sql/task` endpoint accepts the following:
The SQL task endpoint accepts [SQL requests in the JSON-over-HTTP form](sql-api.md#request-body) using the
`query`, `context`, and `parameters` fields, but ignoring the `resultFormat`, `header`, `typesHeader`, and
`sqlTypesHeader` fields.
- [SQL requests in the JSON-over-HTTP form](sql-api.md#request-body) using the
`query`, `context`, and `parameters` fields. The endpoint ignores the `resultFormat`, `header`, `typesHeader`, and `sqlTypesHeader` fields.
- [INSERT](../multi-stage-query/reference.md#insert) and [REPLACE](../multi-stage-query/reference.md#replace) statements.
- SELECT queries (experimental feature). SELECT query results are collected from workers by the controller, and written into the [task report](#get-the-report-for-a-query-task) as an array of arrays. The behavior and result format of plain SELECT queries (without INSERT or REPLACE) is subject to change.
This endpoint accepts [INSERT](../multi-stage-query/reference.md#insert) and [REPLACE](../multi-stage-query/reference.md#replace) statements.
### URL
As an experimental feature, this endpoint also accepts SELECT queries. SELECT query results are collected from workers
by the controller, and written into the [task report](#get-the-report-for-a-query-task) as an array of arrays. The
behavior and result format of plain SELECT queries (without INSERT or REPLACE) is subject to change.
`POST` `/druid/v2/sql/task`
### Responses
<Tabs>
<TabItem value="1" label="HTTP">
<TabItem value="1" label="200 SUCCESS">
```
POST /druid/v2/sql/task
```
*Successfully submitted query*
</TabItem>
<TabItem value="2" label="400 BAD REQUEST">
*Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
```json
{
"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."
}
```
</TabItem>
<TabItem value="3" label="500 INTERNAL SERVER ERROR">
*Request not sent due to unexpected conditions. Returns a JSON object detailing the error with the following format:*
```json
{
"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."
}
```
</TabItem>
</Tabs>
---
### Sample request
The following example shows a query that fetches data from an external JSON source and inserts it into a table named `wikipedia`.
<Tabs>
<TabItem value="4" label="HTTP">
```HTTP
POST /druid/v2/sql/task HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
Content-Type: application/json
{
"query": "INSERT INTO wikipedia\nSELECT\n TIME_PARSE(\"timestamp\") AS __time,\n *\nFROM TABLE(\n EXTERN(\n '{\"type\": \"http\", \"uris\": [\"https://druid.apache.org/data/wikipedia.json.gz\"]}',\n '{\"type\": \"json\"}',\n '[{\"name\": \"added\", \"type\": \"long\"}, {\"name\": \"channel\", \"type\": \"string\"}, {\"name\": \"cityName\", \"type\": \"string\"}, {\"name\": \"comment\", \"type\": \"string\"}, {\"name\": \"commentLength\", \"type\": \"long\"}, {\"name\": \"countryIsoCode\", \"type\": \"string\"}, {\"name\": \"countryName\", \"type\": \"string\"}, {\"name\": \"deleted\", \"type\": \"long\"}, {\"name\": \"delta\", \"type\": \"long\"}, {\"name\": \"deltaBucket\", \"type\": \"string\"}, {\"name\": \"diffUrl\", \"type\": \"string\"}, {\"name\": \"flags\", \"type\": \"string\"}, {\"name\": \"isAnonymous\", \"type\": \"string\"}, {\"name\": \"isMinor\", \"type\": \"string\"}, {\"name\": \"isNew\", \"type\": \"string\"}, {\"name\": \"isRobot\", \"type\": \"string\"}, {\"name\": \"isUnpatrolled\", \"type\": \"string\"}, {\"name\": \"metroCode\", \"type\": \"string\"}, {\"name\": \"namespace\", \"type\": \"string\"}, {\"name\": \"page\", \"type\": \"string\"}, {\"name\": \"regionIsoCode\", \"type\": \"string\"}, {\"name\": \"regionName\", \"type\": \"string\"}, {\"name\": \"timestamp\", \"type\": \"string\"}, {\"name\": \"user\", \"type\": \"string\"}]'\n )\n)\nPARTITIONED BY DAY",
"context": {
@ -76,12 +122,11 @@ POST /druid/v2/sql/task
</TabItem>
<TabItem value="2" label="curl">
<TabItem value="5" label="cURL">
```bash
# Make sure you replace `username`, `password`, `your-instance`, and `port` with the values for your deployment.
curl --location --request POST 'https://<username>:<password>@<your-instance>:<port>/druid/v2/sql/task/' \
```shell
curl --location --request POST 'http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/task' \
--header 'Content-Type: application/json' \
--data-raw '{
"query": "INSERT INTO wikipedia\nSELECT\n TIME_PARSE(\"timestamp\") AS __time,\n *\nFROM TABLE(\n EXTERN(\n '\''{\"type\": \"http\", \"uris\": [\"https://druid.apache.org/data/wikipedia.json.gz\"]}'\'',\n '\''{\"type\": \"json\"}'\'',\n '\''[{\"name\": \"added\", \"type\": \"long\"}, {\"name\": \"channel\", \"type\": \"string\"}, {\"name\": \"cityName\", \"type\": \"string\"}, {\"name\": \"comment\", \"type\": \"string\"}, {\"name\": \"commentLength\", \"type\": \"long\"}, {\"name\": \"countryIsoCode\", \"type\": \"string\"}, {\"name\": \"countryName\", \"type\": \"string\"}, {\"name\": \"deleted\", \"type\": \"long\"}, {\"name\": \"delta\", \"type\": \"long\"}, {\"name\": \"deltaBucket\", \"type\": \"string\"}, {\"name\": \"diffUrl\", \"type\": \"string\"}, {\"name\": \"flags\", \"type\": \"string\"}, {\"name\": \"isAnonymous\", \"type\": \"string\"}, {\"name\": \"isMinor\", \"type\": \"string\"}, {\"name\": \"isNew\", \"type\": \"string\"}, {\"name\": \"isRobot\", \"type\": \"string\"}, {\"name\": \"isUnpatrolled\", \"type\": \"string\"}, {\"name\": \"metroCode\", \"type\": \"string\"}, {\"name\": \"namespace\", \"type\": \"string\"}, {\"name\": \"page\", \"type\": \"string\"}, {\"name\": \"regionIsoCode\", \"type\": \"string\"}, {\"name\": \"regionName\", \"type\": \"string\"}, {\"name\": \"timestamp\", \"type\": \"string\"}, {\"name\": \"user\", \"type\": \"string\"}]'\''\n )\n)\nPARTITIONED BY DAY",
@ -93,15 +138,14 @@ curl --location --request POST 'https://<username>:<password>@<your-instance>:<p
</TabItem>
<TabItem value="3" label="Python">
<TabItem value="6" label="Python">
```python
import json
import requests
# Make sure you replace `your-instance`, and `port` with the values for your deployment.
url = "https://<your-instance>:<port>/druid/v2/sql/task/"
url = "http://ROUTER_IP:ROUTER_PORT/druid/v2/sql/task"
payload = json.dumps({
"query": "INSERT INTO wikipedia\nSELECT\n TIME_PARSE(\"timestamp\") AS __time,\n *\nFROM TABLE(\n EXTERN(\n '{\"type\": \"http\", \"uris\": [\"https://druid.apache.org/data/wikipedia.json.gz\"]}',\n '{\"type\": \"json\"}',\n '[{\"name\": \"added\", \"type\": \"long\"}, {\"name\": \"channel\", \"type\": \"string\"}, {\"name\": \"cityName\", \"type\": \"string\"}, {\"name\": \"comment\", \"type\": \"string\"}, {\"name\": \"commentLength\", \"type\": \"long\"}, {\"name\": \"countryIsoCode\", \"type\": \"string\"}, {\"name\": \"countryName\", \"type\": \"string\"}, {\"name\": \"deleted\", \"type\": \"long\"}, {\"name\": \"delta\", \"type\": \"long\"}, {\"name\": \"deltaBucket\", \"type\": \"string\"}, {\"name\": \"diffUrl\", \"type\": \"string\"}, {\"name\": \"flags\", \"type\": \"string\"}, {\"name\": \"isAnonymous\", \"type\": \"string\"}, {\"name\": \"isMinor\", \"type\": \"string\"}, {\"name\": \"isNew\", \"type\": \"string\"}, {\"name\": \"isRobot\", \"type\": \"string\"}, {\"name\": \"isUnpatrolled\", \"type\": \"string\"}, {\"name\": \"metroCode\", \"type\": \"string\"}, {\"name\": \"namespace\", \"type\": \"string\"}, {\"name\": \"page\", \"type\": \"string\"}, {\"name\": \"regionIsoCode\", \"type\": \"string\"}, {\"name\": \"regionName\", \"type\": \"string\"}, {\"name\": \"timestamp\", \"type\": \"string\"}, {\"name\": \"user\", \"type\": \"string\"}]'\n )\n)\nPARTITIONED BY DAY",
@ -123,7 +167,10 @@ print(response.text)
</Tabs>
#### Response
### Sample response
<details>
<summary>View the response</summary>
```json
{
@ -131,49 +178,78 @@ print(response.text)
"state": "RUNNING",
}
```
</details>
**Response fields**
| Field | Description |
|---|---|
| `taskId` | Controller task ID. You can use Druid's standard [Tasks API](./tasks-api.md) to interact with this controller task. |
| `state` | Initial state for the query, which is "RUNNING". |
| `state` | Initial state for the query. |
## Get the status for a query task
You can retrieve status of a query to see if it is still running, completed successfully, failed, or got canceled.
Retrieves the status of a query task. It returns a JSON object with the task's status code, runner status, task type, datasource, and other relevant metadata.
#### Request
### URL
`GET` `/druid/indexer/v1/task/{taskId}/status`
### Responses
<Tabs>
<TabItem value="4" label="HTTP">
<TabItem value="7" label="200 SUCCESS">
```
GET /druid/indexer/v1/task/<taskId>/status
<br/>
*Successfully retrieved task status*
</TabItem>
<TabItem value="8" label="404 NOT FOUND">
<br/>
*Cannot find task with ID*
</TabItem>
</Tabs>
---
### Sample request
The following example shows how to retrieve the status of a task with the ID `query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e`.
<Tabs>
<TabItem value="9" label="HTTP">
```HTTP
GET /druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/status HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
```
</TabItem>
<TabItem value="5" label="curl">
<TabItem value="10" label="cURL">
```bash
# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment.
curl --location --request GET 'https://<username>:<password>@<your-instance>:<port>/druid/indexer/v1/task/<taskId>/status'
```shell
curl --location --request GET 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/status'
```
</TabItem>
<TabItem value="6" label="Python">
<TabItem value="11" label="Python">
```python
import requests
# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment.
url = "https://<your-instance>:<port>/druid/indexer/v1/task/<taskId>/status"
url = "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/status"
payload={}
headers = {}
@ -187,9 +263,12 @@ print(response.text)
</Tabs>
#### Response
### Sample response
```
<details>
<summary>View the response</summary>
```json
{
"task": "query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e",
"status": {
@ -212,55 +291,76 @@ print(response.text)
}
}
```
</details>
## Get the report for a query task
A report provides detailed information about a query task, including things like the stages, warnings, and errors.
Retrieves the task report for a query.
The report provides detailed information about the query task, including things like the stages, warnings, and errors.
Keep the following in mind when using the task API to view reports:
- The task report for an entire job is associated with the `query_controller` task. The `query_worker` tasks do not have
their own reports; their information is incorporated into the controller report.
- The task report for an entire job is associated with the `query_controller` task. The `query_worker` tasks don't have their own reports; their information is incorporated into the controller report.
- The task report API may report `404 Not Found` temporarily while the task is in the process of starting up.
- As an experimental feature, the MSQ task engine supports running SELECT queries. SELECT query results are written into
the `multiStageQuery.payload.results.results` task report key as an array of arrays. The behavior and result format of plain
SELECT queries (without INSERT or REPLACE) is subject to change.
- `multiStageQuery.payload.results.resultsTruncated` denote whether the results of the report have been truncated to prevent
the reports from blowing up
- `multiStageQuery.payload.results.resultsTruncated` denotes whether the results of the report have been truncated to prevent the reports from blowing up.
For an explanation of the fields in a report, see [Report response fields](#report-response-fields).
#### Request
### URL
`GET` `/druid/indexer/v1/task/{taskId}/reports`
### Responses
<Tabs>
<TabItem value="7" label="HTTP">
<TabItem value="12" label="200 SUCCESS">
```
GET /druid/indexer/v1/task/<taskId>/reports
<br/>
*Successfully retrieved task report*
</TabItem>
</Tabs>
---
### Sample request
The following example shows how to retrieve the report for a query with the task ID `query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e`.
<Tabs>
<TabItem value="13" label="HTTP">
```HTTP
GET /druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/reports HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
```
</TabItem>
<TabItem value="8" label="curl">
<TabItem value="14" label="cURL">
```bash
# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment.
curl --location --request GET 'https://<username>:<password>@<your-instance>:<port>/druid/indexer/v1/task/<taskId>/reports'
```shell
curl --location --request GET 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/reports'
```
</TabItem>
<TabItem value="9" label="Python">
<TabItem value="15" label="Python">
```python
import requests
# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment.
url = "https://<your-instance>:<port>/druid/indexer/v1/task/<taskId>/reports"
url = "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/reports"
headers = {}
response = requests.get(url, headers=headers, auth=('USER', 'PASSWORD'))
@ -271,11 +371,11 @@ print(response.text)
</Tabs>
#### Response
### Sample response
The response shows an example report for a query.
<details><summary>Show the response</summary>
<details><summary>View the response</summary>
```json
{
@ -608,7 +708,7 @@ The response shows an example report for a query.
<a name="report-response-fields"></a>
The following table describes the response fields when you retrieve a report for a MSQ task engine using the `/druid/indexer/v1/task/<taskId>/reports` endpoint:
The following table describes the response fields when you retrieve a report for a MSQ task engine using the `/druid/indexer/v1/task/{taskId}/reports` endpoint:
| Field | Description |
|---|---|
@ -663,37 +763,69 @@ The following table describes the response fields when you retrieve a report for
## Cancel a query task
#### Request
Cancels a query task.
Returns a JSON object with the ID of the task that was canceled successfully.
### URL
`POST` `/druid/indexer/v1/task/{taskId}/shutdown`
### Responses
<Tabs>
<TabItem value="10" label="HTTP">
<TabItem value="16" label="200 SUCCESS">
```
POST /druid/indexer/v1/task/<taskId>/shutdown
<br/>
*Successfully shut down task*
</TabItem>
<TabItem value="17" label="404 NOT FOUND">
<br/>
*Cannot find task with ID or task is no longer running*
</TabItem>
</Tabs>
---
### Sample request
The following example shows how to cancel a query task with the ID `query-655efe33-781a-4c50-ae84-c2911b42d63c`.
<Tabs>
<TabItem value="18" label="HTTP">
```HTTP
POST /druid/indexer/v1/task/query-655efe33-781a-4c50-ae84-c2911b42d63c/shutdown HTTP/1.1
Host: http://ROUTER_IP:ROUTER_PORT
```
</TabItem>
<TabItem value="11" label="curl">
<TabItem value="19" label="cURL">
```bash
# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment.
curl --location --request POST 'https://<username>:<password>@<your-instance>:<port>/druid/indexer/v1/task/<taskId>/shutdown'
```shell
curl --location --request POST 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-655efe33-781a-4c50-ae84-c2911b42d63c/shutdown'
```
</TabItem>
<TabItem value="12" label="Python">
<TabItem value="20" label="Python">
```python
import requests
# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment.
url = "https://<your-instance>:<port>/druid/indexer/v1/task/<taskId>/shutdown"
url = "http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-655efe33-781a-4c50-ae84-c2911b42d63c/shutdown"
payload={}
headers = {}
@ -707,9 +839,11 @@ print(response.text)
</Tabs>
#### Response
### Sample response
```
The response shows the ID of the task that was canceled.
```json
{
"task": "query-655efe33-781a-4c50-ae84-c2911b42d63c"
}

4
docs/api-reference/sql-jdbc.md
View File

@ -28,7 +28,6 @@ sidebar_label: SQL JDBC driver
This document describes the SQL language.
:::
You can make [Druid SQL](../querying/sql.md) queries using the [Avatica JDBC driver](https://calcite.apache.org/avatica/downloads/).
We recommend using Avatica JDBC driver version 1.23.0 or later. Note that starting with Avatica 1.21.0, you may need to set the [`transparent_reconnection`](https://calcite.apache.org/avatica/docs/client_reference.html#transparent_reconnection) property to `true` if you notice intermittent query failures.
@ -89,6 +88,7 @@ For a runnable example that includes a query that you might run, see [Examples](
It is also possible to use a protocol buffers JDBC connection with Druid, this offer reduced bloat and potential performance
improvements for larger result sets. To use it apply the following connection URL instead, everything else remains the same
```
String url = "jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica-protobuf/;transparent_reconnection=true;serialization=protobuf";
```
@ -134,7 +134,7 @@ You can try out these examples after verifying that you meet the [prerequisites]
For more information about the connection options, see [Client Reference](https://calcite.apache.org/avatica/docs/client_reference.html).
### Prerequisites
### Prerequisites
Make sure you meet the following requirements before trying these examples:

76
docs/api-reference/supervisor-api.md
View File

@ -48,7 +48,7 @@ Returns an array of strings representing the names of active supervisors. If the
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor</code>
`GET` `/druid/indexer/v1/supervisor`
#### Responses
@ -90,7 +90,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -106,7 +106,7 @@ Retrieves an array of active supervisor objects. If there are no active supervis
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor?full</code>
`GET` `/druid/indexer/v1/supervisor?full`
#### Responses
@ -148,7 +148,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -774,7 +774,7 @@ Retrieves an array of objects representing active supervisors and their current
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor?state=true</code>
`GET` `/druid/indexer/v1/supervisor?state=true`
#### Responses
@ -816,7 +816,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -845,7 +845,7 @@ Retrieves the specification for a single supervisor. The returned specification
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/:supervisorId</code>
`GET` `/druid/indexer/v1/supervisor/{supervisorId}`
#### Responses
@ -896,7 +896,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1209,7 +1209,7 @@ For additional information about the status report, see [Supervisor reference](.
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/:supervisorId/status</code>
`GET` `/druid/indexer/v1/supervisor/{supervisorId}/status`
#### Responses
@ -1259,7 +1259,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1313,7 +1313,7 @@ Retrieves the current health report for a single supervisor. The health of a sup
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/:supervisorId/health</code>
`GET` `/druid/indexer/v1/supervisor/{supervisorId}/health`
#### Responses
@ -1367,7 +1367,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1382,7 +1382,7 @@ Returns a snapshot of the current ingestion row counters for each task being man
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/:supervisorId/stats</code>
`GET` `/druid/indexer/v1/supervisor/{supervisorId}/stats`
#### Responses
@ -1432,7 +1432,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1488,7 +1488,7 @@ Retrieves an audit history of specs for all supervisors.
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/history</code>
`GET` `/druid/indexer/v1/supervisor/history`
#### Responses
@ -1530,7 +1530,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1848,7 +1848,7 @@ Retrieves an audit history of specs for a single supervisor.
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/supervisor/:supervisorId/history</code>
`GET` `/druid/indexer/v1/supervisor/{supervisorId}/history`
#### Responses
@ -1899,7 +1899,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -2232,7 +2232,7 @@ This way, you can apply configuration changes without a pause in ingestion.
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor</code>
`POST` `/druid/indexer/v1/supervisor`
#### Responses
@ -2385,7 +2385,7 @@ Content-Length: 1359
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -2400,7 +2400,8 @@ Suspends a single running supervisor. Returns the updated supervisor spec, where
Indexing tasks remain suspended until you [resume the supervisor](#resume-a-supervisor).
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/suspend</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/suspend`
#### Responses
@ -2456,7 +2457,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -2766,7 +2767,8 @@ Host: http://ROUTER_IP:ROUTER_PORT
Suspends all supervisors. Note that this endpoint returns an HTTP `200 Success` code message even if there are no supervisors or running supervisors to suspend.
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/suspendAll</code>
`POST` `/druid/indexer/v1/supervisor/suspendAll`
#### Responses
@ -2808,7 +2810,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -2823,7 +2825,7 @@ Resumes indexing tasks for a supervisor. Returns an updated supervisor spec with
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/resume</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/resume`
#### Responses
@ -2879,7 +2881,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3190,7 +3192,7 @@ Resumes all supervisors. Note that this endpoint returns an HTTP `200 Success` c
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/resumeAll</code>
`POST` `/druid/indexer/v1/supervisor/resumeAll`
#### Responses
@ -3232,7 +3234,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3255,7 +3257,7 @@ The indexing service keeps track of the latest persisted offsets in Kafka or seq
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/reset</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/reset`
#### Responses
@ -3305,7 +3307,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3330,7 +3332,7 @@ Use this endpoint with caution. It can cause skipped messages, leading to data l
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/resetOffsets</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/resetOffsets`
#### Responses
@ -3416,7 +3418,7 @@ when the supervisor's tasks restart, they resume reading from `{"0": 100, "1": 1
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3433,7 +3435,7 @@ The terminated supervisor still exists in the metadata store and its history can
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/terminate</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/terminate`
#### Responses
@ -3481,7 +3483,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3496,7 +3498,7 @@ Terminates all supervisors. Terminated supervisors still exist in the metadata s
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/terminateAll</code>
`POST` `/druid/indexer/v1/supervisor/terminateAll`
#### Responses
@ -3538,7 +3540,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -3553,4 +3555,4 @@ Shuts down a supervisor. This endpoint is deprecated and will be removed in futu
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/supervisor/:supervisorId/shutdown</code>
`POST` `/druid/indexer/v1/supervisor/{supervisorId}/shutdown`

62
docs/api-reference/tasks-api.md
View File

@ -39,7 +39,7 @@ Retrieves an array of all tasks in the Druid cluster. Each task object includes
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/tasks</code>
`GET` `/druid/indexer/v1/tasks`
#### Query parameters
@ -118,7 +118,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -187,7 +187,7 @@ Retrieves an array of completed tasks in the Druid cluster. This is functionally
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/completeTasks</code>
`GET` `/druid/indexer/v1/completeTasks`
#### Query parameters
@ -250,7 +250,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -301,7 +301,7 @@ Retrieves an array of running task objects in the Druid cluster. It is functiona
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/runningTasks</code>
`GET` `/druid/indexer/v1/runningTasks`
#### Query parameters
@ -357,7 +357,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -390,7 +390,7 @@ Retrieves an array of waiting tasks in the Druid cluster. It is functionally equ
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/waitingTasks</code>
`GET` `/druid/indexer/v1/waitingTasks`
#### Query parameters
@ -445,7 +445,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -514,7 +514,7 @@ Retrieves an array of pending tasks in the Druid cluster. It is functionally equ
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/pendingTasks</code>
`GET` `/druid/indexer/v1/pendingTasks`
#### Query parameters
@ -569,7 +569,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
[
@ -620,7 +620,7 @@ Retrieves the payload of a task given the task ID. It returns a JSON object with
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId</code>
`GET` `/druid/indexer/v1/task/{taskId}`
#### Responses
@ -675,7 +675,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -835,7 +835,7 @@ Retrieves the status of a task given the task ID. It returns a JSON object with
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId/status</code>
`GET` `/druid/indexer/v1/task/{taskId}/status`
#### Responses
@ -890,7 +890,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -926,7 +926,7 @@ In addition to enabling audit logs, configure a cleanup strategy to prevent over
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId/segments</code>
`GET` `/druid/indexer/v1/task/{taskId}/segments`
#### Responses
@ -981,11 +981,7 @@ Task logs are automatically retrieved from the Middle Manager/Indexer or in long
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId/log</code>
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId/log</code>
`GET` `/druid/indexer/v1/task/{taskId}/log`
#### Query parameters
@ -1037,7 +1033,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
2023-07-03T22:11:17,891 INFO [qtp1251996697-122] org.apache.druid.indexing.seekablestream.SeekableStreamIndexTaskRunner - Sequence[index_kafka_social_media_0e905aa31037879_0] end offsets updated from [{0=9223372036854775807}] to [{0=230985}].
@ -1109,7 +1105,7 @@ Retrieves a [task completion report](../ingestion/tasks.md#task-reports) for a t
#### URL
<code class="getAPI">GET</code> <code>/druid/indexer/v1/task/:taskId/reports</code>
`GET` `/druid/indexer/v1/task/{taskId}/reports`
#### Responses
@ -1155,7 +1151,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1201,7 +1197,7 @@ Note that for most batch ingestion use cases, you should use the [SQL-ingestion
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/task</code>
`POST` `/druid/indexer/v1/task`
#### Responses
@ -1355,7 +1351,7 @@ Content-Length: 952
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1371,7 +1367,7 @@ Shuts down a task if it not already complete. Returns a JSON object with the ID
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/task/:taskId/shutdown</code>
`POST` `/druid/indexer/v1/task/{taskId}/shutdown`
#### Responses
@ -1425,7 +1421,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1441,7 +1437,7 @@ Shuts down all tasks for a specified datasource. If successful, it returns a JSO
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/datasources/:datasource/shutdownAllTasks</code>
`POST` `/druid/indexer/v1/datasources/{datasource}/shutdownAllTasks`
#### Responses
@ -1495,7 +1491,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1513,7 +1509,7 @@ Retrieves list of task status objects for list of task ID strings in request bod
#### URL
<code class="postAPI">POST</code> <code>/druid/indexer/v1/taskStatus</code>
`POST` `/druid/indexer/v1/taskStatus`
#### Responses
@ -1574,7 +1570,7 @@ Content-Length: 134
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{
@ -1614,7 +1610,7 @@ which automates this operation to perform periodically.
#### URL
<code class="deleteAPI">DELETE</code> <code>/druid/indexer/v1/pendingSegments/:datasource</code>
`DELETE` `/druid/indexer/v1/pendingSegments/{datasource}`
#### Responses
@ -1660,7 +1656,7 @@ Host: http://ROUTER_IP:ROUTER_PORT
#### Sample response
<details>
<summary>Click to show sample response</summary>
<summary>View the response</summary>
```json
{

10
docs/ingestion/tasks.md
View File

@ -53,7 +53,7 @@ The reporting feature is supported by [native batch tasks](native-batch.md), the
After a task completes, if it supports reports, its report can be retrieved at:
```
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/task/<task-id>/reports
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/task/{taskId}/reports
```
An example output is shown below:
@ -176,7 +176,7 @@ For some task types, the indexing task can wait for the newly ingested segments
When a task is running, a live report containing ingestion state, unparseable events and moving average for number of events processed for 1 min, 5 min, 15 min time window can be retrieved at:
```
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/task/<task-id>/reports
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/task/{taskId}/reports
```
An example output is shown below:
@ -263,7 +263,7 @@ The [native batch task](native-batch.md), the Hadoop batch task, and Kafka and K
The live report can be accessed with a GET to the following URL on a Peon running a task:
```
http://<middlemanager-host>:<worker-port>/druid/worker/v1/chat/<task-id>/rowStats
http://<middlemanager-host>:<worker-port>/druid/worker/v1/chat/{taskId}/rowStats
```
An example report is shown below. The `movingAverages` section contains 1 minute, 5 minute, and 15 minute moving averages of increases to the four row counters, which have the same definitions as those in the completion report. The `totals` section shows the current totals.
@ -310,7 +310,7 @@ An example report is shown below. The `movingAverages` section contains 1 minute
For the Kafka Indexing Service, a GET to the following Overlord API will retrieve live row stat reports from each task being managed by the supervisor and provide a combined report.
```
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/supervisor/<supervisor-id>/stats
http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/supervisor/{supervisorId}/stats
```
### Unparseable events
@ -318,7 +318,7 @@ http://<OVERLORD-HOST>:<OVERLORD-PORT>/druid/indexer/v1/supervisor/<supervisor-i
Lists of recently-encountered unparseable events can be retrieved from a running task with a GET to the following Peon API:
```
http://<middlemanager-host>:<worker-port>/druid/worker/v1/chat/<task-id>/unparseableEvents
http://<middlemanager-host>:<worker-port>/druid/worker/v1/chat/{taskId}/unparseableEvents
```
Note that this functionality is not supported by all task types. Currently, it is only supported by the