writer-jill commented on code in PR #14589: URL: https://github.com/apache/druid/pull/14589#discussion_r1265476415
########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query Review Comment: Avoid entering a subheading after a heading with preliminary text. Do you even need the Queries heading? I think you could just have headings "Submit a query" and "Get segments information for a query". ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. Review Comment: ```suggestion * Druid returns the response in a pretty-printed format using indentation and line breaks. ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. + + ```json +[ + { + "timestamp": "2023-07-03T18:49:54.848Z", + "result": [ + { + "views": 11591218026, + "username": "gus" + }, + { + "views": 11578638578, + "username": "miette" + }, + { + "views": 11561618880, + "username": "leon" + }, + { + "views": 11552609824, + "username": "mia" + }, + { + "views": 11551537517, + "username": "milton" + } + ] + } +] + ``` + + + The following is a sample response of the second query, retrieving the user with the highest upvotes to posts ratio. + + ```json +[ + { + "version": "v1", + "timestamp": "2022-01-01T00:00:00.000Z", + "event": { + "upvoteSum": 8.0419541E7, + "upvoteToPostRatio": 69.53014661762697, + "postCount": 1156614, + "username": "miette" + } + } +] + ``` +</details> + +### Get segment information for query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/candidates/` Review Comment: Why is it a POST and not a GET request? ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> Review Comment: ```suggestion Host: http://ROUTER_IP:ROUTER_PORT ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ Review Comment: ```suggestion curl "http://ROUTER_IP:ROUTER_PORT/druid/v2?pretty=null"; \ ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. Review Comment: We put the API description directly after the heading, then the URL - like this example: https://docs.imply.io/latest/pivot-alerts-api/ ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. + + ```json +[ + { + "timestamp": "2023-07-03T18:49:54.848Z", + "result": [ + { + "views": 11591218026, + "username": "gus" + }, + { + "views": 11578638578, + "username": "miette" + }, + { + "views": 11561618880, + "username": "leon" + }, + { + "views": 11552609824, + "username": "mia" + }, + { + "views": 11551537517, + "username": "milton" + } + ] + } +] + ``` + + + The following is a sample response of the second query, retrieving the user with the highest upvotes to posts ratio. + + ```json +[ + { + "version": "v1", + "timestamp": "2022-01-01T00:00:00.000Z", + "event": { + "upvoteSum": 8.0419541E7, + "upvoteToPostRatio": 69.53014661762697, + "postCount": 1156614, + "username": "miette" + } + } +] + ``` +</details> + +### Get segment information for query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/candidates/` + +Retrieves an array that contains objects with segment information, including the server locations associated with the provided query. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully retrieved segment information* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2/candidates" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2020-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2/candidates HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> Review Comment: ```suggestion Host: http://ROUTER_IP:ROUTER_PORT ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ Review Comment: Where is the POST part of the curl request? Shouldn't it be `curl -X POST` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. + + ```json +[ + { + "timestamp": "2023-07-03T18:49:54.848Z", + "result": [ + { + "views": 11591218026, + "username": "gus" + }, + { + "views": 11578638578, + "username": "miette" + }, + { + "views": 11561618880, + "username": "leon" + }, + { + "views": 11552609824, + "username": "mia" + }, + { + "views": 11551537517, + "username": "milton" + } + ] + } +] + ``` + + + The following is a sample response of the second query, retrieving the user with the highest upvotes to posts ratio. + + ```json +[ + { + "version": "v1", + "timestamp": "2022-01-01T00:00:00.000Z", + "event": { + "upvoteSum": 8.0419541E7, + "upvoteToPostRatio": 69.53014661762697, + "postCount": 1156614, + "username": "miette" + } + } +] + ``` +</details> + +### Get segment information for query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/candidates/` + +Retrieves an array that contains objects with segment information, including the server locations associated with the provided query. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully retrieved segment information* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2/candidates" \ Review Comment: Where is the POST part of the curl request? Shouldn't it be `curl -X POST` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses Review Comment: I would list the sample request first, then the responses. ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. Review Comment: ```suggestion In this document, `http://SERVICE_IP:SERVICE_PORT` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://ROUTER_IP:ROUTER_PORT` with `http://localhost:8888`. ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. Review Comment: In the data object, do you have to include all of these properties or are just some of them compulsory? Are the properties the same for all query types? In the Pivot API guide I used wording like... "At a minimum, you must provide `x`, `y`, and `z` in the body of the request." https://docs.imply.io/latest/pivot-alerts-api/#sample-request-3 ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. Review Comment: I would group the responses together with the requests. Example first request followed by its response, example second request followed by its response. ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> Review Comment: ```suggestion Host: http://ROUTER_IP:ROUTER_PORT ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. + + ```json +[ + { + "timestamp": "2023-07-03T18:49:54.848Z", + "result": [ + { + "views": 11591218026, + "username": "gus" + }, + { + "views": 11578638578, + "username": "miette" + }, + { + "views": 11561618880, + "username": "leon" + }, + { + "views": 11552609824, + "username": "mia" + }, + { + "views": 11551537517, + "username": "milton" + } + ] + } +] + ``` + + + The following is a sample response of the second query, retrieving the user with the highest upvotes to posts ratio. + + ```json +[ + { + "version": "v1", + "timestamp": "2022-01-01T00:00:00.000Z", + "event": { + "upvoteSum": 8.0419541E7, + "upvoteToPostRatio": 69.53014661762697, + "postCount": 1156614, + "username": "miette" + } + } +] + ``` +</details> + +### Get segment information for query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/candidates/` + +Retrieves an array that contains objects with segment information, including the server locations associated with the provided query. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully retrieved segment information* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2/candidates" \ Review Comment: ```suggestion curl "http://ROUTER_IP:ROUTER_PORT/druid/v2/candidates"; \ ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ Review Comment: ```suggestion curl "http://ROUTER_IP:ROUTER_PORT/druid/v2?pretty=null"; \ ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. + ## Queries -`POST /druid/v2/` +### Submit a query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/` + +Submits a JSON-based native query. + +Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The possible types of queries are: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. + +#### Responses + +<!--DOCUSAURUS_CODE_TABS--> + +<!--200 SUCCESS--> +<br/> +*Successfully submitted query* +<!--400 BAD REQUEST--> +<br/> +*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." +} +``` +For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures). +<!--END_DOCUSAURUS_CODE_TABS--> + +--- + +#### Sample request + +The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"topN\", + \"dataSource\": \"social_media\", + \"dimension\": \"username\", + \"threshold\": 5, + \"metric\": \"views\", + \"granularity\": \"all\", + + \"aggregations\": [ + { + \"type\": \"longSum\", + \"name\": \"views\", + \"fieldName\": \"views\" + } + ], + \"intervals\": [ + \"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\" + ] +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 336 + +{ + "queryType": "topN", + "dataSource": "social_media", + "dimension": "username", + "threshold": 5, + "metric": "views", + "granularity": "all", + + "aggregations": [ + { + "type": "longSum", + "name": "views", + "fieldName": "views" + } + ], + "intervals": [ + "2022-01-01T00:00:00.000/2024-01-01T00:00:00.000" + ] +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest upvotes to posts ratio from the `social_media` datasource. + +In this query: +* The `upvoteSum` aggregation calculates the sum of the `upvotes` for each user. +* The `postCount` aggregation calculates the sum of posts for each user. +* The `upvoteToPostRatio` is a post-aggregation of the the `upvoteSum` and the `postCount`, divided to calculate the ratio. +* The result is sorted based on the `upvoteToPostRatio` and in descending order. + +<!--DOCUSAURUS_CODE_TABS--> + +<!--cURL--> +```shell +curl "http://<ROUTER_IP>:<ROUTER_PORT>/druid/v2?pretty=null" \ +--header "Content-Type: application/json" \ +--data "{ + \"queryType\": \"groupBy\", + \"dataSource\": \"social_media\", + \"dimensions\": [\"username\"], + \"granularity\": \"all\", + \"aggregations\": [ + { \"type\": \"doubleSum\", \"name\": \"upvoteSum\", \"fieldName\": \"upvotes\" }, + { \"type\": \"count\", \"name\": \"postCount\", \"fieldName\": \"post_title\" } + ], + \"postAggregations\": [ + { + \"type\": \"arithmetic\", + \"name\": \"upvoteToPostRatio\", + \"fn\": \"/\", + \"fields\": [ + { \"type\": \"fieldAccess\", \"name\": \"upvoteSum\", \"fieldName\": \"upvoteSum\" }, + { \"type\": \"fieldAccess\", \"name\": \"postCount\", \"fieldName\": \"postCount\" } + ] + } + ], + \"intervals\": [\"2022-01-01T00:00:00.000/2024-01-01T00:00:00.000\"], + \"limitSpec\": { + \"type\": \"default\", + \"limit\": 1, + \"columns\": [ + { \"dimension\": \"upvoteToPostRatio\", \"direction\": \"descending\" } + ] + } +}" +``` +<!--HTTP--> +```HTTP +POST /druid/v2?pretty=null HTTP/1.1 +Host: http://<ROUTER_IP>:<ROUTER_PORT> +Content-Type: application/json +Content-Length: 817 + +{ + "queryType": "groupBy", + "dataSource": "social_media", + "dimensions": ["username"], + "granularity": "all", + "aggregations": [ + { "type": "doubleSum", "name": "upvoteSum", "fieldName": "upvotes" }, + { "type": "count", "name": "postCount", "fieldName": "post_title" } + ], + "postAggregations": [ + { + "type": "arithmetic", + "name": "upvoteToPostRatio", + "fn": "/", + "fields": [ + { "type": "fieldAccess", "name": "upvoteSum", "fieldName": "upvoteSum" }, + { "type": "fieldAccess", "name": "postCount", "fieldName": "postCount" } + ] + } + ], + "intervals": ["2022-01-01T00:00:00.000/2024-01-01T00:00:00.000"], + "limitSpec": { + "type": "default", + "limit": 1, + "columns": [ + { "dimension": "upvoteToPostRatio", "direction": "descending" } + ] + } +} +``` +<!--END_DOCUSAURUS_CODE_TABS--> + +#### Sample response + +<details> + <summary>Click to show sample response</summary> + The following is a sample response of the first query, retrieving a ranked list of users and post views. + + ```json +[ + { + "timestamp": "2023-07-03T18:49:54.848Z", + "result": [ + { + "views": 11591218026, + "username": "gus" + }, + { + "views": 11578638578, + "username": "miette" + }, + { + "views": 11561618880, + "username": "leon" + }, + { + "views": 11552609824, + "username": "mia" + }, + { + "views": 11551537517, + "username": "milton" + } + ] + } +] + ``` + + + The following is a sample response of the second query, retrieving the user with the highest upvotes to posts ratio. + + ```json +[ + { + "version": "v1", + "timestamp": "2022-01-01T00:00:00.000Z", + "event": { + "upvoteSum": 8.0419541E7, + "upvoteToPostRatio": 69.53014661762697, + "postCount": 1156614, + "username": "miette" + } + } +] + ``` +</details> + +### Get segment information for query + +#### URL +<code class="postAPI">POST</code> `/druid/v2/candidates/` + +Retrieves an array that contains objects with segment information, including the server locations associated with the provided query. + +#### Query parameters +* `pretty` (optional) + * The response is returned in a pretty-printed format using indentation and line breaks. Review Comment: ```suggestion * Druid returns the response in a pretty-printed format using indentation and line breaks. ``` ########## docs/api-reference/json-querying-api.md: ########## @@ -25,12 +25,853 @@ sidebar_label: JSON querying This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid. +In this document, `http://<SERVICE_IP>:<SERVICE_PORT>` is a placeholder for the server address of deployment and the service port. For example, on the quickstart configuration, replace `http://<ROUTER_IP>:<ROUTER_PORT>` with `http://localhost:8888`. Review Comment: The angled brackets can cause confusion so it's best to avoid them. -- 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]
