From a17a2534f7e32774202f3f713794d02a501057c9 Mon Sep 17 00:00:00 2001 From: Katya Macedo Date: Fri, 20 Dec 2024 13:32:39 -0600 Subject: [PATCH 1/4] Docs: Add query example --- docs/api-reference/sql-api.md | 18 ++++++------------ docs/querying/sql.md | 9 ++++----- 2 files changed, 10 insertions(+), 17 deletions(-) diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index f6a624c8ce23..39b10e76fe30 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -85,20 +85,15 @@ The request body takes the following properties: * `context`: JSON object containing optional [SQL query context parameters](../querying/sql-query-context.md), such as to set the query ID, time zone, and whether to use an approximation algorithm for distinct count. -* `parameters`: List of query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value. For a list of supported SQL types, see [Data types](../querying/sql-data-types.md). +* `parameters`: List of query parameters for parameterized queries. Each parameter in the array should be a JSON object containing the parameter's SQL data type and parameter value. For more information on using dynamic parameters, see [Dynamic parameters](../querying/sql.md#dynamic-parameters). For a list of supported SQL types, see [Data types](../querying/sql-data-types.md). For example: + ```json - "parameters": [ - { - "type": "VARCHAR", - "value": "bar" - }, - { - "type": "ARRAY", - "value": [-25.7, null, 36.85] - } - ] + { + "query": "SELECT \"arrayDouble\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?)", + "parameters": [{"type": "ARRAY", "value": [999, null, 5.5]}] + } ``` #### Responses @@ -155,7 +150,6 @@ If you detect a truncated response, treat it as an error. --- - #### Sample request The following example retrieves all rows in the `wikipedia` datasource where the `user` is `BlueMoon2662`. The query is assigned the ID `request01` using the `sqlQueryId` context parameter. The optional properties `header`, `typesHeader`, and `sqlTypesHeader` are set to `true` to include type information to the response. diff --git a/docs/querying/sql.md b/docs/querying/sql.md index 6a47ac3a4c0d..9915042a569d 100644 --- a/docs/querying/sql.md +++ b/docs/querying/sql.md @@ -403,7 +403,7 @@ The following example query uses the [ARRAY_CONTAINS](./sql-functions.md#array_c ```sql { - "query": "SELECT doubleArrayColumn from druid.table where ARRAY_CONTAINS(?, doubleArrayColumn)", + "query": "SELECT doubleArrayColumn from druid.table where ARRAY_CONTAINS(doubleArrayColumn, ?)", "parameters": [ { "type": "ARRAY", @@ -428,17 +428,16 @@ SELECT * FROM druid.foo WHERE dim1 like CONCAT('%', CAST (? AS VARCHAR), '%') Dynamic parameters can even replace arrays, reducing the parsing time. Refer to the parameters in the [API request body](../api-reference/sql-api.md#request-body) for usage. ```sql -SELECT arrayColumn from druid.table where ARRAY_CONTAINS(?, arrayColumn) +SELECT arrayColumn from druid.table where ARRAY_CONTAINS(arrayColumn, ?) ``` -With this, an IN filter being supplied with a lot of values, can be replaced by a dynamic parameter passed inside [SCALAR_IN_ARRAY](sql-functions.md#scalar_in_array) +You can replace an IN filter with many values by dynamically passing a parameter into [SCALAR_IN_ARRAY](sql-functions.md#scalar_in_array). +For sample java queries, see [Dynamic parameters](../api-reference/sql-jdbc.md#dynamic-parameters). ```sql SELECT count(city) from druid.table where SCALAR_IN_ARRAY(city, ?) ``` -sample java code using dynamic parameters is provided [here](../api-reference/sql-jdbc.md#dynamic-parameters). - ## Reserved keywords Druid SQL reserves certain keywords which are used in its query language. Apache Druid inherits all of the reserved keywords from [Apache Calcite](https://calcite.apache.org/docs/reference.html#keywords). In addition to these, the following reserved keywords are unique to Apache Druid: From 58fc598cd11ed08bbf39e70ddfeb9cdcd05f6277 Mon Sep 17 00:00:00 2001 From: Katya Macedo Date: Fri, 20 Dec 2024 15:54:03 -0600 Subject: [PATCH 2/4] Update after review --- docs/api-reference/sql-api.md | 2 +- docs/querying/sql.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index 39b10e76fe30..640edeb87d36 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -92,7 +92,7 @@ The request body takes the following properties: ```json { "query": "SELECT \"arrayDouble\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?)", - "parameters": [{"type": "ARRAY", "value": [999, null, 5.5]}] + "parameters": [{"type": "ARRAY", "value": [999.0, null, 5.5]},{"type":"VARCHAR","value":"bar"}] } ``` diff --git a/docs/querying/sql.md b/docs/querying/sql.md index 9915042a569d..881711f05771 100644 --- a/docs/querying/sql.md +++ b/docs/querying/sql.md @@ -432,7 +432,7 @@ SELECT arrayColumn from druid.table where ARRAY_CONTAINS(arrayColumn, ?) ``` You can replace an IN filter with many values by dynamically passing a parameter into [SCALAR_IN_ARRAY](sql-functions.md#scalar_in_array). -For sample java queries, see [Dynamic parameters](../api-reference/sql-jdbc.md#dynamic-parameters). +For example Java queries, see [Dynamic parameters](../api-reference/sql-jdbc.md#dynamic-parameters). ```sql SELECT count(city) from druid.table where SCALAR_IN_ARRAY(city, ?) From 47f73e007cb791328dc697a41d4158113c14918d Mon Sep 17 00:00:00 2001 From: Katya Macedo Date: Mon, 10 Mar 2025 17:04:25 -0500 Subject: [PATCH 3/4] Update query --- docs/api-reference/sql-api.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index 640edeb87d36..55dbead5e082 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -91,8 +91,11 @@ The request body takes the following properties: ```json { - "query": "SELECT \"arrayDouble\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?)", - "parameters": [{"type": "ARRAY", "value": [999.0, null, 5.5]},{"type":"VARCHAR","value":"bar"}] + "query": "SELECT \"arrayDouble\", \"stringColumn\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?) AND \"stringColumn\" = ?", + "parameters": [ + {"type": "ARRAY", "value": [999.0, null, 5.5]}, + {"type":"VARCHAR","value":"bar"} + ] } ``` From c3e62b4a85eec08c31d2c096242aebb26c85b373 Mon Sep 17 00:00:00 2001 From: Victoria Lim Date: Mon, 10 Mar 2025 15:54:41 -0700 Subject: [PATCH 4/4] Update docs/api-reference/sql-api.md --- docs/api-reference/sql-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api-reference/sql-api.md b/docs/api-reference/sql-api.md index 55dbead5e082..2b25bdd02f0b 100644 --- a/docs/api-reference/sql-api.md +++ b/docs/api-reference/sql-api.md @@ -94,7 +94,7 @@ The request body takes the following properties: "query": "SELECT \"arrayDouble\", \"stringColumn\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?) AND \"stringColumn\" = ?", "parameters": [ {"type": "ARRAY", "value": [999.0, null, 5.5]}, - {"type":"VARCHAR","value":"bar"} + {"type": "VARCHAR", "value": "bar"} ] } ```