You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@druid.apache.org by "demo-kratia (via GitHub)" <gi...@apache.org> on 2023/07/14 22:24:13 UTC
[PR] Fill info for Submit a query (druid)
demo-kratia opened a new pull request, #14589:
URL: https://github.com/apache/druid/pull/14589
Reorganize the JSON-querying API documentation.
This PR has:
- [x] been self-reviewed.
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "vtlim (via GitHub)" <gi...@apache.org>.
vtlim commented on code in PR #14589:
URL: https://github.com/apache/druid/pull/14589#discussion_r1277755680
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,876 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query with the request body.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+Druid supports different types of queries for different use cases. All queries require the following properties:
+* `queryType`: A string representing type of query. Druid supports the following native query types: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`.
Review Comment:
```suggestion
* `queryType`: A string representing the type of query. Druid supports the following native query types: `timeseries`, `topN`, `groupBy`, `timeBoundaries`, `segmentMetadata`, `datasourceMetadata`, `scan`, and `search`.
```
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "vtlim (via GitHub)" <gi...@apache.org>.
vtlim commented on code in PR #14589:
URL: https://github.com/apache/druid/pull/14589#discussion_r1276834939
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,872 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response in a pretty-printed format using indentation and line breaks.
+
+### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+
+*Successfully submitted query*
+
+<!--400 BAD REQUEST-->
+
+*Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
+
+```json
+{
+ "error": "A well-defined error code.",
+ "errorMessage": "A message with additional details about the error.",
+ "errorClass": "Class of exception that caused this error.",
+ "host": "The host on which the error occurred."
+}
+```
+For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+### Sample request: `topN`
Review Comment:
What if we made the request/response a single subheading since they're more closely related than the other stuff in this section?
So we could call this one:
```suggestion
### Example query: `topN`
```
And then either remove the response subheading or make it an H4 (####)
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,872 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response in a pretty-printed format using indentation and line breaks.
+
+### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+
+*Successfully submitted query*
+
+<!--400 BAD REQUEST-->
+
+*Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
+
+```json
+{
+ "error": "A well-defined error code.",
+ "errorMessage": "A message with additional details about the error.",
+ "errorClass": "Class of exception that caused this error.",
+ "host": "The host on which the error occurred."
+}
+```
+For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+### Sample request: `topN`
+
+The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views.
Review Comment:
```suggestion
The following example shows a `topN` query. The query analyzes the `social_media` datasource to return the top five users from the `username` dimension with the highest number of views from the `views` metric..
```
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,872 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
Review Comment:
>Queries are composed of various JSON properties
Hm, I feel like this doesn't say much since the request body can include different types of properties.
Could we give light guidance on what is required for a request body. For example:
```
All queries require the following properties:
* `queryType`: A string representing type of query. Druid supports the following native query types: <LIST>
* `dataSource`: A string or object defining the source of data to query.
The most common value is the name of the datasource to query.
For more information, see [Datasources](../querying/datasources.md).
For additional properties based on your query type or use case, see [available native queries](../querying/querying.md#available-queries).
```
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,872 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response in a pretty-printed format using indentation and line breaks.
+
+### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+
+*Successfully submitted query*
+
+<!--400 BAD REQUEST-->
+
+*Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
+
+```json
+{
+ "error": "A well-defined error code.",
+ "errorMessage": "A message with additional details about the error.",
+ "errorClass": "Class of exception that caused this error.",
+ "host": "The host on which the error occurred."
+}
+```
+For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+### Sample request: `topN`
+
+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-->
+
+### Sample response: `topN`
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```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"
+ }
+ ]
+ }
+]
+ ```
+</details>
+
+### Sample request: `groupBy`
+
+The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest votes 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 `upvoteSum` and the `postCount`, divided to calculate the ratio.
+* The result is sorted based on the `upvoteToPostRatio` and in descending order.
Review Comment:
```suggestion
* The result is sorted based on the `upvoteToPostRatio` in descending order.
```
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] Fill info for Submit a query (druid)
Posted by "writer-jill (via GitHub)" <gi...@apache.org>.
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "vtlim (via GitHub)" <gi...@apache.org>.
vtlim merged PR #14589:
URL: https://github.com/apache/druid/pull/14589
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "vtlim (via GitHub)" <gi...@apache.org>.
vtlim commented on code in PR #14589:
URL: https://github.com/apache/druid/pull/14589#discussion_r1277778800
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,876 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query with the request body.
Review Comment:
```suggestion
Submits a JSON-based native query. The body of the request is the native query itself.
```
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "writer-jill (via GitHub)" <gi...@apache.org>.
writer-jill commented on code in PR #14589:
URL: https://github.com/apache/druid/pull/14589#discussion_r1276496155
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,880 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response 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: `topN` query
Review Comment:
```suggestion
### Sample request: `topN`
```
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,880 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response 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: `topN` query
+
+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-->
+
+### Sample response: `topN` query
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```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"
+ }
+ ]
+ }
+]
+ ```
+</details>
+
+### Sample request: `groupBy` query
Review Comment:
```suggestion
### Sample request: `groupBy`
```
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,880 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response 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: `topN` query
+
+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-->
+
+### Sample response: `topN` query
Review Comment:
```suggestion
### Sample response: `topN`
```
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,880 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response 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: `topN` query
+
+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-->
+
+### Sample response: `topN` query
+
+<details>
+ <summary>Click to show sample response</summary>
+
+ ```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"
+ }
+ ]
+ }
+]
+ ```
+</details>
+
+### Sample request: `groupBy` query
+
+The following example submits a JSON query of the `groupBy` type to retrieve the `username` with the highest votes 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 `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" \
+--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: `groupBy` query
Review Comment:
```suggestion
### Sample response: `groupBy`
```
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org
Re: [PR] JSON-querying API documentation refactor (druid)
Posted by "vtlim (via GitHub)" <gi...@apache.org>.
vtlim commented on code in PR #14589:
URL: https://github.com/apache/druid/pull/14589#discussion_r1276828469
##########
docs/api-reference/json-querying-api.md:
##########
@@ -23,14 +23,872 @@ sidebar_label: JSON querying
~ under the License.
-->
-This document describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
+This topic describes the API endpoints to submit JSON-based [native queries](../querying/querying.md) to Apache Druid.
-## Queries
+In this topic, `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`.
-`POST /druid/v2/`
-The endpoint for submitting queries. Accepts an option `?pretty` that pretty prints the results.
+## Submit a query
-`POST /druid/v2/candidates/`
+Submits a JSON-based native query.
-Returns segment information lists including server locations for the given query.
\ No newline at end of file
+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`. For guidance on constructing the requests and choosing query types, see [available native queries](../querying/querying.md#available-queries).
+
+### URL
+
+<code class="postAPI">POST</code> <code>/druid/v2/</code>
+
+### Query parameters
+
+* `pretty` (optional)
+ * Druid returns the response in a pretty-printed format using indentation and line breaks.
+
+### Responses
+
+<!--DOCUSAURUS_CODE_TABS-->
+
+<!--200 SUCCESS-->
+
+*Successfully submitted query*
+
+<!--400 BAD REQUEST-->
+
+*Error thrown due to bad query. Returns a JSON object detailing the error with the following format:*
+
+```json
+{
+ "error": "A well-defined error code.",
+ "errorMessage": "A message with additional details about the error.",
+ "errorClass": "Class of exception that caused this error.",
+ "host": "The host on which the error occurred."
+}
+```
+For more information on possible error messages, see [query execution failures](../querying/querying.md#query-execution-failures).
+
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+---
+
+### Sample request: `topN`
+
+The following example submits a JSON query of the `topN` type to retrieve a ranked list of users and their post views.
Review Comment:
```suggestion
The following example shows a `topN` query. The query analyzes the `social_media` datasource to return the top five users from the `username` dimension with the highest number of views from the `views` metric.
```
--
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: commits-unsubscribe@druid.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org