writer-jill commented on code in PR #15087: URL: https://github.com/apache/druid/pull/15087#discussion_r1347344259
########## docs/api-reference/data-management-api.md: ########## @@ -23,59 +23,497 @@ 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 +Note that while you can mark segments as `used` by sending POST requests to the datasource, 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. -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. +When you use these APIs concurrently with an indexing task or a kill task, the behavior is undefined. Some segments may be terminated, while others are marked 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. + +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 -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. +### Update a group of segments as `unused` Review Comment: I like "mark" instead of "update" but I kept the section titles brief. I don't think the title needs to include the mechanism. ########## docs/api-reference/data-management-api.md: ########## @@ -23,59 +23,497 @@ 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 +Note that while you can mark segments as `used` by sending POST requests to the datasource, 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. -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. +When you use these APIs concurrently with an indexing task or a kill task, the behavior is undefined. Some segments may be terminated, while others are marked 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. + +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 -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. +### Update a group of segments as `unused` Review Comment: Reordered. I like "mark" instead of "update" but I kept the section titles brief. I don't think the title needs to include the mechanism. -- 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]
