vtlim commented on code in PR #15087: URL: https://github.com/apache/druid/pull/15087#discussion_r1388625923
########## docs/api-reference/data-management-api.md: ########## @@ -23,59 +23,518 @@ sidebar_label: Data management ~ under the License. --> -This document describes the data management API endpoints for Apache Druid. This includes information on how to mark segments as `used` or `unused` and delete them from Druid. +This topic describes the data management API endpoints for Apache Druid. +This includes information on how to mark segments as used or unused and delete them from Druid. -## Note for Coordinator's POST and DELETE APIs - -While segments may be enabled by issuing POST requests for the datasources, the Coordinator may again disable segments if they match any configured [drop rules](../operations/rule-configuration.md#drop-rules). Even if segments are enabled by these APIs, you must configure a [load rule](../operations/rule-configuration.md#load-rules) to load them onto Historical processes. If an indexing or kill task runs at the same time these APIs are invoked, the behavior is undefined. Some segments might be killed and others might be enabled. It's also possible that all segments might be disabled, but the indexing task can still read data from those segments and succeed. +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. :::info - Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk. +Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk. ::: -`POST /druid/coordinator/v1/datasources/{dataSourceName}` +## Segment management + +You can mark segments as used by sending POST requests to the datasource, but the Coordinator may subsequently mark segments as unused if they meet any configured [drop rules](../operations/rule-configuration.md#drop-rules). +Even if these API requests update segments to used, you still need to configure a [load rule](../operations/rule-configuration.md#load-rules) to load them onto Historical processes. + +When you use these APIs concurrently with an indexing task or a kill task, the behavior is undefined. +Druid terminates some segments and marks others as used. +Furthermore, it is possible that all segments could be unused, yet an indexing task might still be able to read data from these segments and complete successfully. + +### Segment IDs + +You must provide segment IDs when using many of the endpoints described in this topic. +For information on segment IDs, see [Segment identification](../design/segments.md#segment-identification). +For information on finding segment IDs in the web console, see [Segments](../operations/web-console.md#segments). + +### Mark a single segment unused + +Marks the state of a segment as unused, using the segment ID. +This is a "soft delete" of the segment from Historicals. +To undo this action, mark the segments used. Review Comment: ```suggestion To undo this action, [mark the segment used](#mark-a-single-segment-as-used). ``` ########## docs/api-reference/data-management-api.md: ########## @@ -23,59 +23,518 @@ sidebar_label: Data management ~ under the License. --> -This document describes the data management API endpoints for Apache Druid. This includes information on how to mark segments as `used` or `unused` and delete them from Druid. +This topic describes the data management API endpoints for Apache Druid. +This includes information on how to mark segments as used or unused and delete them from Druid. -## Note for Coordinator's POST and DELETE APIs - -While segments may be enabled by issuing POST requests for the datasources, the Coordinator may again disable segments if they match any configured [drop rules](../operations/rule-configuration.md#drop-rules). Even if segments are enabled by these APIs, you must configure a [load rule](../operations/rule-configuration.md#load-rules) to load them onto Historical processes. If an indexing or kill task runs at the same time these APIs are invoked, the behavior is undefined. Some segments might be killed and others might be enabled. It's also possible that all segments might be disabled, but the indexing task can still read data from those segments and succeed. +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. :::info - Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk. +Avoid using indexing or kill tasks and these APIs at the same time for the same datasource and time chunk. ::: -`POST /druid/coordinator/v1/datasources/{dataSourceName}` +## Segment management + +You can mark segments as used by sending POST requests to the datasource, but the Coordinator may subsequently mark segments as unused if they meet any configured [drop rules](../operations/rule-configuration.md#drop-rules). +Even if these API requests update segments to used, you still need to configure a [load rule](../operations/rule-configuration.md#load-rules) to load them onto Historical processes. + +When you use these APIs concurrently with an indexing task or a kill task, the behavior is undefined. +Druid terminates some segments and marks others as used. +Furthermore, it is possible that all segments could be unused, yet an indexing task might still be able to read data from these segments and complete successfully. + +### Segment IDs + +You must provide segment IDs when using many of the endpoints described in this topic. +For information on segment IDs, see [Segment identification](../design/segments.md#segment-identification). +For information on finding segment IDs in the web console, see [Segments](../operations/web-console.md#segments). + +### Mark a single segment unused + +Marks the state of a segment as unused, using the segment ID. +This is a "soft delete" of the segment from Historicals. +To undo this action, mark the segments used. + +Note that this endpoint returns an HTTP `200 OK` response code even if the segment ID or datasource doesn't exist. + +#### URL + +<code class="deleteAPI">DELETE</code> <code>/druid/coordinator/v1/datasources/:datasource/segments/:segmentId</code> + +#### Header + +The following headers are required for this request: + +```json +Content-Type: application/json +Accept: application/json, text/plain +``` + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> + +*Successfully updated segment* + +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example updates the segment `wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z` from datasource `wikipedia_hour` as `unused`. -Marks as used all segments belonging to a datasource. Returns a JSON object of the form -`{"numChangedSegments": <number>}` with the number of segments in the database whose state has been changed (that is, -the segments were marked as used) as the result of this API call. +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> + +```shell +curl --request DELETE "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z"; \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json, text/plain' +``` + +<!--HTTP--> + +```HTTP +DELETE /druid/coordinator/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T16:00:00.000Z_2015-09-12T17:00:00.000Z_2023-08-10T04:12:03.860Z HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT +Content-Type: application/json +Accept: application/json, text/plain +``` + +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Show sample response</summary> + +```json +{ + "segmentStateChanged": true +} +``` +</details> + +### Mark a single segment as used + +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> + +#### Header + +The following headers are required for this request: + +```json +Content-Type: application/json +Accept: application/json, text/plain +``` + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> + +*Successfully updated segments* + +<!--END_DOCUSAURUS_CODE_TABS--> + +--- -`POST /druid/coordinator/v1/datasources/{dataSourceName}/segments/{segmentId}` +#### Sample request -Marks as used a segment of a datasource. Returns a JSON object of the form `{"segmentStateChanged": <boolean>}` with -the boolean indicating if the state of the segment has been changed (that is, the segment was marked as used) as the -result of this API call. +The following example updates the segment with ID `wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z` to used. -`POST /druid/coordinator/v1/datasources/{dataSourceName}/markUsed` +<!--DOCUSAURUS_CODE_TABS--> -`POST /druid/coordinator/v1/datasources/{dataSourceName}/markUnused` +<!--cURL--> -Marks segments (un)used for a datasource by interval or set of segment Ids. When marking used only segments that are not overshadowed will be updated. +```shell +curl --request POST "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z"; \ +--header 'Content-Type: application/json' \ +--header 'Accept: application/json, text/plain' +``` -The request payload contains the interval or set of segment IDs to be marked unused. -Either interval or segment IDs should be provided, if both or none are provided in the payload, the API would throw an error (400 BAD REQUEST). +<!--HTTP--> -Interval specifies the start and end times as IS0 8601 strings. `interval=(start/end)` where start and end both are inclusive and only the segments completely contained within the specified interval will be disabled, partially overlapping segments will not be affected. +```HTTP +POST /druid/coordinator/v1/datasources/wikipedia_hour/segments/wikipedia_hour_2015-09-12T18:00:00.000Z_2015-09-12T19:00:00.000Z_2023-08-10T04:12:03.860Z HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT +Content-Type: application/json +Accept: application/json, text/plain +``` -JSON Request Payload: +<!--END_DOCUSAURUS_CODE_TABS--> - |Key|Description|Example| +#### Sample response + +<details> + <summary>Show sample response</summary> + +```json +{ + "segmentStateChanged": true +} +``` +</details> + +### Mark a group of segments unused + +Marks the state of a group of segments as unused, using an array of segment IDs or an interval. +Pass the array of segment IDs or interval as a JSON object in the request body. + +For the interval, specify the start and end times as ISO 8601 strings to identify segments inclusive of the start time and exclusive of the end time. +Druid only updates the segments completely contained within the specified interval; partially overlapping segments are not affected. + +#### URL + +<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/:datasource/markUnused</code> + +#### Request body + +The group of segments is sent as a JSON request payload that accepts one of the following properties: + +|Property|Description|Example| |----------|-------------|---------| -|`interval`|The interval for which to mark segments unused|`"2015-09-12T03:00:00.000Z/2015-09-12T05:00:00.000Z"`| -|`segmentIds`|Set of segment IDs to be marked unused|`["segmentId1", "segmentId2"]`| +|`interval`|The interval of segments.|`"2015-09-12T03:00:00.000Z/2015-09-12T05:00:00.000Z"`| +|`segmentIds`|Array of segment IDs.|`["segmentId1", "segmentId2"]`| + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> + +*Successfully updated segments* + +<!--204 NO CONTENT--> + +*Invalid datasource name* + +<!--400 BAD REQUEST--> + +*Invalid request payload* + +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example marks two segments from the `wikipedia_hour` datasource unused based on their segment IDs. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> + +```shell +curl "http://ROUTER_IP:ROUTER_PORT/druid/coordinator/v1/datasources/wikipedia_hour/markUnused"; \ +--header 'Content-Type: application/json' \ +--data '{ + "segmentIds": [ + "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z", + "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z" + ] +}' +``` + +<!--HTTP--> + +```HTTP +POST /druid/coordinator/v1/datasources/wikipedia_hour/markUnused HTTP/1.1 +Host: http://ROUTER_IP:ROUTER_PORT +Content-Type: application/json +Content-Length: 230 + +{ + "segmentIds": [ + "wikipedia_hour_2015-09-12T14:00:00.000Z_2015-09-12T15:00:00.000Z_2023-08-10T04:12:03.860Z", + "wikipedia_hour_2015-09-12T04:00:00.000Z_2015-09-12T05:00:00.000Z_2023-08-10T04:12:03.860Z" + ] +} +``` + +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Show sample response</summary> + +```json +{ + "numChangedSegments": 2 +} +``` +</details> + +### Mark a group of segments used + +Marks the state of a group of segments as used, using an array of segment IDs or an interval. +Pass the array of segment IDs or interval as a JSON object in the request body. + +For the interval, specify the start and end times as ISO 8601 strings to identify segments inclusive of the start time and exclusive of the end time. +Druid only updates the segments completely contained within the specified interval; partially overlapping segments are not affected. + +#### URL + +<code class="postAPI">POST</code> <code>/druid/coordinator/v1/datasources/:datasource/markUsed</code> + +#### Request body + +The group of segments is sent as a JSON request payload that accepts the following properties: + +|Property|Type|Description|Example| +|----------|---|-------------|---------| +|`interval`|ISO-8601| The interval of segments.|`"2015-09-12T03:00:00.000Z/2015-09-12T05:00:00.000Z"`| +|`segmentIds`|String|Array of segment IDs.|`["segmentId1", "segmentId2"]`| Review Comment: If we want to include the type column, `interval` should technically be string, and the format (ISO 8601) can be specified in the description. `segmentIds` type should be an array. The example is also clear in itself, so you could not have this column like in line 205 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
