From 7f06a53cb19ab53b209331f4a22791c29473d8db Mon Sep 17 00:00:00 2001 From: Katya Macedo <38017980+ektravel@users.noreply.github.com> Date: Fri, 12 Apr 2024 11:19:13 -0500 Subject: [PATCH] [Docs] Fix API placeholder formatting (#16240) --- .../api-reference/automatic-compaction-api.md | 26 +- docs/api-reference/data-management-api.md | 29 +- .../dynamic-configuration-api.md | 27 +- docs/api-reference/json-querying-api.md | 12 +- docs/api-reference/lookups-api.md | 13 +- docs/api-reference/retention-rules-api.md | 18 +- docs/api-reference/service-status-api.md | 80 +++-- docs/api-reference/sql-api.md | 21 +- docs/api-reference/sql-ingestion-api.md | 280 +++++++++++++----- docs/api-reference/sql-jdbc.md | 4 +- docs/api-reference/supervisor-api.md | 76 ++--- docs/api-reference/tasks-api.md | 62 ++-- docs/ingestion/tasks.md | 10 +- 13 files changed, 394 insertions(+), 264 deletions(-) diff --git a/docs/api-reference/automatic-compaction-api.md b/docs/api-reference/automatic-compaction-api.md index a986585ed84..a443e108639 100644 --- a/docs/api-reference/automatic-compaction-api.md +++ b/docs/api-reference/automatic-compaction-api.md @@ -43,7 +43,7 @@ Note that this endpoint returns an HTTP `200 OK` message code even if the dataso #### URL -POST /druid/coordinator/v1/config/compaction +`POST` `/druid/coordinator/v1/config/compaction` #### Responses @@ -132,7 +132,7 @@ Removes the automatic compaction configuration for a datasource. This updates th #### URL -DELETE /druid/coordinator/v1/config/compaction/:dataSource +`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 -POST /druid/coordinator/v1/config/compaction/taskslots +`POST` `/druid/coordinator/v1/config/compaction/taskslots` #### Query parameters @@ -262,7 +262,7 @@ You can use this endpoint to retrieve `compactionTaskSlotRatio` and `maxCompacti #### URL -GET /druid/coordinator/v1/config/compaction +`GET` `/druid/coordinator/v1/config/compaction` #### Responses @@ -304,7 +304,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -411,7 +411,7 @@ Retrieves the automatic compaction configuration for a datasource. #### URL -GET /druid/coordinator/v1/config/compaction/:dataSource +`GET` `/druid/coordinator/v1/config/compaction/{dataSource}` #### Responses @@ -461,7 +461,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -523,7 +523,7 @@ The response contains a list of objects with the following keys: #### URL -GET /druid/coordinator/v1/config/compaction/:dataSource/history +`GET` `/druid/coordinator/v1/config/compaction/{dataSource}/history` #### Query parameters * `interval` (optional) @@ -579,7 +579,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -683,7 +683,7 @@ Returns the total size of segments awaiting compaction for a given datasource. R #### URL -GET /druid/coordinator/v1/compaction/progress?dataSource=:dataSource +`GET` `/druid/coordinator/v1/compaction/progress?dataSource={dataSource}` #### Query parameter * `dataSource` (required) @@ -738,7 +738,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -767,7 +767,7 @@ The `latestStatus` object has the following properties: #### URL -GET /druid/coordinator/v1/compaction/status +`GET` `/druid/coordinator/v1/compaction/status` #### Query parameters * `dataSource` (optional) @@ -813,7 +813,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { diff --git a/docs/api-reference/data-management-api.md b/docs/api-reference/data-management-api.md index 754bf62f725..d7156376c52 100644 --- a/docs/api-reference/data-management-api.md +++ b/docs/api-reference/data-management-api.md @@ -62,7 +62,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the segme #### URL -DELETE /druid/coordinator/v1/datasources/:datasource/segments/:segmentId +`DELETE` `/druid/coordinator/v1/datasources/{datasource}/segments/{segmentId}` #### Header @@ -119,7 +119,7 @@ Accept: application/json, text/plain #### Sample response
- Show sample response + View the response ```json { @@ -134,7 +134,7 @@ Marks the state of a segment as used, using the segment ID. #### URL -POST /druid/coordinator/v1/datasources/segments/:segmentId +`POST` `/druid/coordinator/v1/datasources/segments/{segmentId}` #### Header @@ -191,7 +191,7 @@ Accept: application/json, text/plain #### Sample response
- Show sample response + View the response ```json { @@ -211,7 +211,7 @@ within the specified interval that match the optional list of versions; partiall #### URL -POST /druid/coordinator/v1/datasources/:datasource/markUnused +`POST` `/druid/coordinator/v1/datasources/{datasource}/markUnused` #### Request body @@ -293,7 +293,7 @@ Content-Length: 230 #### Sample response
- Show sample response + View the response ```json { @@ -313,7 +313,7 @@ within the specified interval that match the optional list of versions; partiall #### URL -POST /druid/coordinator/v1/datasources/:datasource/markUsed +`POST` `/druid/coordinator/v1/datasources/{datasource}/markUsed` #### Request body @@ -395,7 +395,7 @@ Content-Length: 230 #### Sample response
- Show sample response + View the response ```json { @@ -413,7 +413,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the datas #### URL -DELETE /druid/coordinator/v1/datasources/:datasource +`DELETE` `/druid/coordinator/v1/datasources/{datasource}` #### Responses @@ -455,7 +455,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Show sample response + View the response ```json { @@ -473,7 +473,7 @@ Note that this endpoint returns an HTTP `200 OK` response code even if the datas #### URL -POST /druid/coordinator/v1/datasources/:datasource +`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 @@ -530,7 +531,7 @@ Accept: application/json, text/plain #### Sample response
- Show sample response + View the response ```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 -DELETE /druid/coordinator/v1/datasources/:datasource/intervals/:interval +`DELETE` `/druid/coordinator/v1/datasources/{datasource}/intervals/{interval}` #### Responses diff --git a/docs/api-reference/dynamic-configuration-api.md b/docs/api-reference/dynamic-configuration-api.md index 00d49cd5a31..85c7dcf5e49 100644 --- a/docs/api-reference/dynamic-configuration-api.md +++ b/docs/api-reference/dynamic-configuration-api.md @@ -44,7 +44,7 @@ Retrieves the current Coordinator dynamic configuration. Returns a JSON object w #### URL -GET /druid/coordinator/v1/config +`GET` `/druid/coordinator/v1/config` #### Responses @@ -86,7 +86,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
-Click to show sample response +View the response ```json { @@ -120,7 +120,7 @@ For information on the supported properties, see [Dynamic configuration](../conf #### URL -POST /druid/coordinator/v1/config +`POST` `/druid/coordinator/v1/config` #### Header parameters @@ -226,7 +226,7 @@ Retrieves the history of changes to Coordinator dynamic configuration over an in #### URL -GET /druid/coordinator/v1/config/history +`GET` `/druid/coordinator/v1/config/history` #### Query parameters @@ -283,7 +283,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -315,7 +315,7 @@ Returns an empty response body if there is no current Overlord dynamic configura #### URL -GET /druid/indexer/v1/worker +`GET` `/druid/indexer/v1/worker` #### Responses @@ -355,7 +355,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -380,7 +380,7 @@ For information on the supported properties, see [Overlord dynamic configuration #### URL -POST/druid/indexer/v1/worker +`POST` `/druid/indexer/v1/worker` #### Header parameters @@ -466,8 +466,7 @@ Retrieves the history of changes to Overlord dynamic configuration over an inter #### URL -GET /druid/indexer/v1/worker/history - +`GET` `/druid/indexer/v1/worker/history` #### Query parameters @@ -523,7 +522,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```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. -GET/druid/indexer/v1/workers +`GET` `/druid/indexer/v1/workers` #### Responses @@ -589,7 +588,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -621,7 +620,7 @@ Returns an empty response body if there are no Overlord scaling events. #### URL -GET/druid/indexer/v1/scaling +`GET` `/druid/indexer/v1/scaling` #### Responses diff --git a/docs/api-reference/json-querying-api.md b/docs/api-reference/json-querying-api.md index 633a04d1ac6..5d03ec8b316 100644 --- a/docs/api-reference/json-querying-api.md +++ b/docs/api-reference/json-querying-api.md @@ -44,7 +44,7 @@ For additional properties based on your query type or use case, see [available n ### URL -POST /druid/v2/ +`POST` `/druid/v2` ### Query parameters @@ -148,7 +148,7 @@ Content-Length: 336 #### Example response: `topN`
- Click to show sample response + View the response ```json [ @@ -277,7 +277,7 @@ Content-Length: 817 #### Example response: `groupBy`
- Click to show sample response + View the response ```json [ @@ -301,9 +301,10 @@ Retrieves an array that contains objects with segment information, including the ### URL -POST /druid/v2/candidates/ +`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). @@ -404,7 +406,7 @@ Content-Length: 336 ### Sample response
- Click to show sample response + View the response ```json [ diff --git a/docs/api-reference/lookups-api.md b/docs/api-reference/lookups-api.md index 9238ade01af..4a122917b53 100644 --- a/docs/api-reference/lookups-api.md +++ b/docs/api-reference/lookups-api.md @@ -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 diff --git a/docs/api-reference/retention-rules-api.md b/docs/api-reference/retention-rules-api.md index 0f41eba3e6d..c21e546abd2 100644 --- a/docs/api-reference/retention-rules-api.md +++ b/docs/api-reference/retention-rules-api.md @@ -48,7 +48,7 @@ Note that this endpoint returns an HTTP `200 OK` even if the datasource does not ### URL -POST /druid/coordinator/v1/rules/:dataSource +`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 -POST /druid/coordinator/v1/rules/_default +`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 -GET /druid/coordinator/v1/rules +`GET` `/druid/coordinator/v1/rules` ### Responses @@ -286,7 +286,7 @@ Host: http://ROUTER_IP:ROUTER_PORT ### Sample response
- Click to show sample response + View the response ```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 -GET /druid/coordinator/v1/rules/:dataSource +`GET` `/druid/coordinator/v1/rules/{dataSource}` ### Query parameters @@ -366,7 +366,7 @@ Host: http://ROUTER_IP:ROUTER_PORT ### Sample response
- Click to show sample response + View the response ```json [ @@ -398,7 +398,7 @@ Retrieves the audit history of rules for all datasources over an interval of tim ### URL -GET /druid/coordinator/v1/rules/history +`GET` `/druid/coordinator/v1/rules/history` ### Query parameters @@ -465,7 +465,7 @@ Host: http://ROUTER_IP:ROUTER_PORT ### Sample response
- Click to show sample response + View the response ```json [ diff --git a/docs/api-reference/service-status-api.md b/docs/api-reference/service-status-api.md index 0d2da88932f..59e2b19c3fb 100644 --- a/docs/api-reference/service-status-api.md +++ b/docs/api-reference/service-status-api.md @@ -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 -GET /status +`GET` `/status` #### Responses @@ -99,7 +99,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -207,7 +207,7 @@ Additional checks for readiness should use the [Historical segment readiness](#g #### URL -GET /status/health +`GET` `/status/health` #### Responses @@ -249,7 +249,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json true @@ -266,7 +266,7 @@ Modify the host and port for the endpoint to match the service to query. Refer t #### URL -GET /status/properties +`GET` `/status/properties` #### Responses @@ -308,7 +308,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -409,7 +409,6 @@ Host: http://ROUTER_IP:ROUTER_PORT
- ### 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 -GET /status/selfDiscovered/status +`GET` `/status/selfDiscovered/status` #### Responses @@ -461,7 +460,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -479,7 +478,7 @@ Use this endpoint for monitoring checks that are unable to examine the response #### URL -GET /status/selfDiscovered +`GET` `/status/selfDiscovered` #### Responses @@ -538,7 +537,7 @@ Retrieves the address of the current leader Coordinator of the cluster. If any r #### URL -GET /druid/coordinator/v1/leader +`GET` `/druid/coordinator/v1/leader` #### Responses @@ -582,7 +581,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json http://localhost:8081 @@ -598,7 +597,7 @@ Use this endpoint as a load balancer status check when you only want the active #### URL -GET /druid/coordinator/v1/isLeader +`GET` `/druid/coordinator/v1/isLeader` #### Responses @@ -650,7 +649,7 @@ Host: http://COORDINATOR_IP:COORDINATOR_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -668,7 +667,7 @@ Retrieves the address of the current leader Overlord of the cluster. In a cluste #### URL -GET /druid/indexer/v1/leader +`GET` `/druid/indexer/v1/leader` #### Responses @@ -712,7 +711,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json http://localhost:8081 @@ -729,7 +728,7 @@ Use this endpoint as a load balancer status check when you only want the active #### URL -GET /druid/indexer/v1/isLeader +`GET` `/druid/indexer/v1/isLeader` #### Responses @@ -781,7 +780,7 @@ Host: http://OVERLORD_IP:OVERLORD_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -800,7 +799,7 @@ Retrieves the enabled state of the MiddleManager. Returns JSON object keyed by t #### URL -GET /druid/worker/v1/enabled +`GET` `/druid/worker/v1/enabled` #### Responses @@ -844,7 +843,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -860,7 +859,7 @@ Retrieves a list of active tasks being run on MiddleManager. Returns JSON list o #### URL -GET /druid/worker/v1/tasks +`GET` `/druid/worker/v1/tasks` #### Responses @@ -904,7 +903,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -921,16 +920,16 @@ Retrieves task log output stream by task ID. For normal usage, you should use th #### URL -GET /druid/worker/v1/task/:taskId/log +`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 -POST /druid/worker/v1/task/:taskId/shutdown +`POST` `/druid/worker/v1/task/{taskId}/shutdown` #### Responses @@ -975,7 +974,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -992,7 +991,7 @@ keyed by the combined `druid.host` and `druid.port`. #### URL -POST /druid/worker/v1/disable +`POST` `/druid/worker/v1/disable` #### Responses @@ -1034,7 +1033,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT #### Sample response
- Click to show sample response + View the response ```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 -POST /druid/worker/v1/enable +`POST` `/druid/worker/v1/enable` #### Responses @@ -1093,7 +1091,7 @@ Host: http://MIDDLEMANAGER_IP:MIDDLEMANAGER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1113,7 +1111,7 @@ Use this endpoint to know when a Broker service is ready to accept queries after #### URL -GET /druid/historical/v1/loadstatus +`GET` `/druid/historical/v1/loadstatus` #### Responses @@ -1155,7 +1153,7 @@ Host: http://HISTORICAL_IP:HISTORICAL_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1171,7 +1169,7 @@ Retrieves a status code to indicate if all segments in the local cache have been #### URL -GET /druid/historical/v1/readiness +`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 -GET /druid/broker/v1/loadstatus +`GET` `/druid/broker/v1/loadstatus` #### Responses @@ -1272,7 +1270,7 @@ Host: http://: #### Sample response
- Click to show sample response + View the response ```json { @@ -1288,7 +1286,7 @@ Retrieves a status code to indicate Broker readiness. Readiness signifies the Br #### URL -GET /druid/broker/v1/readiness +`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. \ No newline at end of file diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index 8cc17bc0641..bf58d236426 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -44,7 +44,7 @@ Each query has an associated SQL query ID. You can set this ID manually using th #### URL -POST /druid/v2/sql +`POST` `/druid/v2/sql` #### Request body @@ -198,7 +198,7 @@ Content-Length: 192 #### Sample response
- Click to show sample response + View the response ```json [ @@ -320,7 +320,7 @@ Cancellation requests require READ permission on all resources used in the SQL q #### URL -DELETE /druid/v2/sql/:sqlQueryId +`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 -POST /druid/v2/sql/statements +`POST` `/druid/v2/sql/statements` #### Request body @@ -505,7 +505,7 @@ Content-Length: 134 #### Sample response
- Click to show sample response + View the response ```json { @@ -631,7 +631,7 @@ Retrieves information about the query associated with the given query ID. The re #### URL -GET /druid/v2/sql/statements/:queryId +`GET` `/druid/v2/sql/statements/{queryId}` #### Responses @@ -690,7 +690,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```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 -GET /druid/v2/sql/statements/:queryId/results +`GET` `/druid/v2/sql/statements/{queryId}/results` #### Query parameters * `page` (optional) @@ -944,7 +943,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -1178,7 +1177,7 @@ Cancels a running or accepted query. #### URL -DELETE /druid/v2/sql/statements/:queryId +`DELETE` `/druid/v2/sql/statements/{queryId}` #### Responses diff --git a/docs/api-reference/sql-ingestion-api.md b/docs/api-reference/sql-ingestion-api.md index 67a6ccf9588..1b587cf4bac 100644 --- a/docs/api-reference/sql-ingestion-api.md +++ b/docs/api-reference/sql-ingestion-api.md @@ -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 - + -``` -POST /druid/v2/sql/task -``` +*Successfully submitted query* + + + + + +*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." +} +``` + + + + +*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." +} +``` + + + + +--- + +### Sample request + +The following example shows a query that fetches data from an external JSON source and inserts it into a table named `wikipedia`. + + + + + + +```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 - + -```bash -# Make sure you replace `username`, `password`, `your-instance`, and `port` with the values for your deployment. -curl --location --request POST 'https://:@:/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://:@:

- + ```python import json import requests -# Make sure you replace `your-instance`, and `port` with the values for your deployment. -url = "https://:/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) -#### Response +### Sample response + +

+ View the response ```json { @@ -131,49 +178,78 @@ print(response.text) "state": "RUNNING", } ``` +
**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 - + -``` -GET /druid/indexer/v1/task//status +
+ +*Successfully retrieved task status* + + + + + +
+ +*Cannot find task with ID* + + + + +--- + +### Sample request + +The following example shows how to retrieve the status of a task with the ID `query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e`. + + + + + +```HTTP +GET /druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/status HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT ``` - + -```bash -# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment. -curl --location --request GET 'https://:@:/druid/indexer/v1/task//status' +```shell +curl --location --request GET 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/status' ``` - + ```python import requests -# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment. -url = "https://:/druid/indexer/v1/task//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) -#### Response +### Sample response -``` +
+ View the response + +```json { "task": "query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e", "status": { @@ -212,55 +291,76 @@ print(response.text) } } ``` +
## 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 - + -``` -GET /druid/indexer/v1/task//reports +
+ +*Successfully retrieved task report* + + + + +--- + +### Sample request + +The following example shows how to retrieve the report for a query with the task ID `query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e`. + + + + + +```HTTP +GET /druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/reports HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT ``` - + -```bash -# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment. -curl --location --request GET 'https://:@:/druid/indexer/v1/task//reports' +```shell +curl --location --request GET 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-3dc0c45d-34d7-4b15-86c9-cdb2d3ebfc4e/reports' ``` - + ```python import requests -# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment. -url = "https://:/druid/indexer/v1/task//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) -#### Response +### Sample response The response shows an example report for a query. -
Show the response +
View the response ```json { @@ -608,7 +708,7 @@ The response shows an example report for a query. -The following table describes the response fields when you retrieve a report for a MSQ task engine using the `/druid/indexer/v1/task//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 - + -``` -POST /druid/indexer/v1/task//shutdown +
+ +*Successfully shut down task* + + + + + +
+ +*Cannot find task with ID or task is no longer running* + + + + +--- + +### Sample request + +The following example shows how to cancel a query task with the ID `query-655efe33-781a-4c50-ae84-c2911b42d63c`. + + + + + + +```HTTP +POST /druid/indexer/v1/task/query-655efe33-781a-4c50-ae84-c2911b42d63c/shutdown HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT ``` - + -```bash -# Make sure you replace `username`, `password`, `your-instance`, `port`, and `taskId` with the values for your deployment. -curl --location --request POST 'https://:@:/druid/indexer/v1/task//shutdown' +```shell +curl --location --request POST 'http://ROUTER_IP:ROUTER_PORT/druid/indexer/v1/task/query-655efe33-781a-4c50-ae84-c2911b42d63c/shutdown' ``` - + ```python import requests -# Make sure you replace `your-instance`, `port`, and `taskId` with the values for your deployment. -url = "https://:/druid/indexer/v1/task//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) -#### Response +### Sample response -``` +The response shows the ID of the task that was canceled. + +```json { "task": "query-655efe33-781a-4c50-ae84-c2911b42d63c" } diff --git a/docs/api-reference/sql-jdbc.md b/docs/api-reference/sql-jdbc.md index 0d8d85c5db6..8223e764ed4 100644 --- a/docs/api-reference/sql-jdbc.md +++ b/docs/api-reference/sql-jdbc.md @@ -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: diff --git a/docs/api-reference/supervisor-api.md b/docs/api-reference/supervisor-api.md index 2e63b69c07f..59980f2cc12 100644 --- a/docs/api-reference/supervisor-api.md +++ b/docs/api-reference/supervisor-api.md @@ -48,7 +48,7 @@ Returns an array of strings representing the names of active supervisors. If the #### URL -GET /druid/indexer/v1/supervisor +`GET` `/druid/indexer/v1/supervisor` #### Responses @@ -90,7 +90,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -106,7 +106,7 @@ Retrieves an array of active supervisor objects. If there are no active supervis #### URL -GET /druid/indexer/v1/supervisor?full +`GET` `/druid/indexer/v1/supervisor?full` #### Responses @@ -148,7 +148,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -774,7 +774,7 @@ Retrieves an array of objects representing active supervisors and their current #### URL -GET /druid/indexer/v1/supervisor?state=true +`GET` `/druid/indexer/v1/supervisor?state=true` #### Responses @@ -816,7 +816,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -845,7 +845,7 @@ Retrieves the specification for a single supervisor. The returned specification #### URL -GET /druid/indexer/v1/supervisor/:supervisorId +`GET` `/druid/indexer/v1/supervisor/{supervisorId}` #### Responses @@ -896,7 +896,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1209,7 +1209,7 @@ For additional information about the status report, see [Supervisor reference](. #### URL -GET /druid/indexer/v1/supervisor/:supervisorId/status +`GET` `/druid/indexer/v1/supervisor/{supervisorId}/status` #### Responses @@ -1259,7 +1259,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1313,7 +1313,7 @@ Retrieves the current health report for a single supervisor. The health of a sup #### URL -GET /druid/indexer/v1/supervisor/:supervisorId/health +`GET` `/druid/indexer/v1/supervisor/{supervisorId}/health` #### Responses @@ -1367,7 +1367,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1382,7 +1382,7 @@ Returns a snapshot of the current ingestion row counters for each task being man #### URL -GET /druid/indexer/v1/supervisor/:supervisorId/stats +`GET` `/druid/indexer/v1/supervisor/{supervisorId}/stats` #### Responses @@ -1432,7 +1432,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1488,7 +1488,7 @@ Retrieves an audit history of specs for all supervisors. #### URL -GET /druid/indexer/v1/supervisor/history +`GET` `/druid/indexer/v1/supervisor/history` #### Responses @@ -1530,7 +1530,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1848,7 +1848,7 @@ Retrieves an audit history of specs for a single supervisor. #### URL -GET /druid/indexer/v1/supervisor/:supervisorId/history +`GET` `/druid/indexer/v1/supervisor/{supervisorId}/history` #### Responses @@ -1899,7 +1899,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -2232,7 +2232,7 @@ This way, you can apply configuration changes without a pause in ingestion. #### URL -POST /druid/indexer/v1/supervisor +`POST` `/druid/indexer/v1/supervisor` #### Responses @@ -2385,7 +2385,7 @@ Content-Length: 1359 #### Sample response
- Click to show sample response + View the response ```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 -POST /druid/indexer/v1/supervisor/:supervisorId/suspend + +`POST` `/druid/indexer/v1/supervisor/{supervisorId}/suspend` #### Responses @@ -2456,7 +2457,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```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 -POST /druid/indexer/v1/supervisor/suspendAll + +`POST` `/druid/indexer/v1/supervisor/suspendAll` #### Responses @@ -2808,7 +2810,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -2823,7 +2825,7 @@ Resumes indexing tasks for a supervisor. Returns an updated supervisor spec with #### URL -POST /druid/indexer/v1/supervisor/:supervisorId/resume +`POST` `/druid/indexer/v1/supervisor/{supervisorId}/resume` #### Responses @@ -2879,7 +2881,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -3190,7 +3192,7 @@ Resumes all supervisors. Note that this endpoint returns an HTTP `200 Success` c #### URL -POST /druid/indexer/v1/supervisor/resumeAll +`POST` `/druid/indexer/v1/supervisor/resumeAll` #### Responses @@ -3232,7 +3234,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -3255,7 +3257,7 @@ The indexing service keeps track of the latest persisted offsets in Kafka or seq #### URL -POST /druid/indexer/v1/supervisor/:supervisorId/reset +`POST` `/druid/indexer/v1/supervisor/{supervisorId}/reset` #### Responses @@ -3305,7 +3307,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -3330,7 +3332,7 @@ Use this endpoint with caution. It can cause skipped messages, leading to data l #### URL -POST /druid/indexer/v1/supervisor/:supervisorId/resetOffsets +`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
- Click to show sample response + View the response ```json { @@ -3433,7 +3435,7 @@ The terminated supervisor still exists in the metadata store and its history can #### URL -POST /druid/indexer/v1/supervisor/:supervisorId/terminate +`POST` `/druid/indexer/v1/supervisor/{supervisorId}/terminate` #### Responses @@ -3481,7 +3483,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -3496,7 +3498,7 @@ Terminates all supervisors. Terminated supervisors still exist in the metadata s #### URL -POST /druid/indexer/v1/supervisor/terminateAll +`POST` `/druid/indexer/v1/supervisor/terminateAll` #### Responses @@ -3538,7 +3540,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -3553,4 +3555,4 @@ Shuts down a supervisor. This endpoint is deprecated and will be removed in futu #### URL -POST /druid/indexer/v1/supervisor/:supervisorId/shutdown +`POST` `/druid/indexer/v1/supervisor/{supervisorId}/shutdown` diff --git a/docs/api-reference/tasks-api.md b/docs/api-reference/tasks-api.md index 4856e6ddf90..b5f56434654 100644 --- a/docs/api-reference/tasks-api.md +++ b/docs/api-reference/tasks-api.md @@ -39,7 +39,7 @@ Retrieves an array of all tasks in the Druid cluster. Each task object includes #### URL -GET /druid/indexer/v1/tasks +`GET` `/druid/indexer/v1/tasks` #### Query parameters @@ -118,7 +118,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -187,7 +187,7 @@ Retrieves an array of completed tasks in the Druid cluster. This is functionally #### URL -GET /druid/indexer/v1/completeTasks +`GET` `/druid/indexer/v1/completeTasks` #### Query parameters @@ -250,7 +250,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -301,7 +301,7 @@ Retrieves an array of running task objects in the Druid cluster. It is functiona #### URL -GET /druid/indexer/v1/runningTasks +`GET` `/druid/indexer/v1/runningTasks` #### Query parameters @@ -357,7 +357,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -390,7 +390,7 @@ Retrieves an array of waiting tasks in the Druid cluster. It is functionally equ #### URL -GET /druid/indexer/v1/waitingTasks +`GET` `/druid/indexer/v1/waitingTasks` #### Query parameters @@ -445,7 +445,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -514,7 +514,7 @@ Retrieves an array of pending tasks in the Druid cluster. It is functionally equ #### URL -GET /druid/indexer/v1/pendingTasks +`GET` `/druid/indexer/v1/pendingTasks` #### Query parameters @@ -569,7 +569,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json [ @@ -620,7 +620,7 @@ Retrieves the payload of a task given the task ID. It returns a JSON object with #### URL -GET /druid/indexer/v1/task/:taskId +`GET` `/druid/indexer/v1/task/{taskId}` #### Responses @@ -675,7 +675,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -835,7 +835,7 @@ Retrieves the status of a task given the task ID. It returns a JSON object with #### URL -GET /druid/indexer/v1/task/:taskId/status +`GET` `/druid/indexer/v1/task/{taskId}/status` #### Responses @@ -890,7 +890,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -926,7 +926,7 @@ In addition to enabling audit logs, configure a cleanup strategy to prevent over #### URL -GET /druid/indexer/v1/task/:taskId/segments +`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 -GET /druid/indexer/v1/task/:taskId/log - -#### URL - -GET /druid/indexer/v1/task/:taskId/log +`GET` `/druid/indexer/v1/task/{taskId}/log` #### Query parameters @@ -1037,7 +1033,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```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 -GET /druid/indexer/v1/task/:taskId/reports +`GET` `/druid/indexer/v1/task/{taskId}/reports` #### Responses @@ -1155,7 +1151,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1201,7 +1197,7 @@ Note that for most batch ingestion use cases, you should use the [SQL-ingestion #### URL -POST /druid/indexer/v1/task +`POST` `/druid/indexer/v1/task` #### Responses @@ -1355,7 +1351,7 @@ Content-Length: 952 #### Sample response
- Click to show sample response + View the response ```json { @@ -1371,7 +1367,7 @@ Shuts down a task if it not already complete. Returns a JSON object with the ID #### URL -POST /druid/indexer/v1/task/:taskId/shutdown +`POST` `/druid/indexer/v1/task/{taskId}/shutdown` #### Responses @@ -1425,7 +1421,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1441,7 +1437,7 @@ Shuts down all tasks for a specified datasource. If successful, it returns a JSO #### URL -POST /druid/indexer/v1/datasources/:datasource/shutdownAllTasks +`POST` `/druid/indexer/v1/datasources/{datasource}/shutdownAllTasks` #### Responses @@ -1495,7 +1491,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { @@ -1513,7 +1509,7 @@ Retrieves list of task status objects for list of task ID strings in request bod #### URL -POST /druid/indexer/v1/taskStatus +`POST` `/druid/indexer/v1/taskStatus` #### Responses @@ -1574,7 +1570,7 @@ Content-Length: 134 #### Sample response
- Click to show sample response + View the response ```json { @@ -1614,7 +1610,7 @@ which automates this operation to perform periodically. #### URL -DELETE /druid/indexer/v1/pendingSegments/:datasource +`DELETE` `/druid/indexer/v1/pendingSegments/{datasource}` #### Responses @@ -1660,7 +1656,7 @@ Host: http://ROUTER_IP:ROUTER_PORT #### Sample response
- Click to show sample response + View the response ```json { diff --git a/docs/ingestion/tasks.md b/docs/ingestion/tasks.md index aaed12d7f4d..3291abb01a0 100644 --- a/docs/ingestion/tasks.md +++ b/docs/ingestion/tasks.md @@ -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://:/druid/indexer/v1/task//reports +http://:/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://:/druid/indexer/v1/task//reports +http://:/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://:/druid/worker/v1/chat//rowStats +http://:/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://:/druid/indexer/v1/supervisor//stats +http://:/druid/indexer/v1/supervisor/{supervisorId}/stats ``` ### Unparseable events @@ -318,7 +318,7 @@ http://:/druid/indexer/v1/supervisor/:/druid/worker/v1/chat//unparseableEvents +http://:/druid/worker/v1/chat/{taskId}/unparseableEvents ``` Note that this functionality is not supported by all task types. Currently, it is only supported by the