Skip to content

Docs: Add SQL query example #17593

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
vtlim merged 4 commits into from
Mar 11, 2025
+13 −17
Merged

Docs: Add SQL query example #17593

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a17a253
Docs: Add query example
ektravel Dec 20, 2024
58fc598
Update after review
ektravel Dec 20, 2024
47f73e0
Update query
ektravel Mar 10, 2025
c3e62b4
Update docs/api-reference/sql-api.md
vtlim Mar 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 9 additions & 12 deletions docs/api-reference/sql-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,20 +85,18 @@ 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\", \"stringColumn\" FROM \"array_example\" WHERE ARRAY_CONTAINS(\"arrayDouble\", ?) AND \"stringColumn\" = ?",
"parameters": [
{"type": "ARRAY", "value": [999.0, null, 5.5]},
{"type": "VARCHAR", "value": "bar"}
]
}
```

#### Responses
Expand Down Expand Up @@ -155,7 +153,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.
Expand Down
9 changes: 4 additions & 5 deletions docs/querying/sql.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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 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, ?)
```

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:
Expand Down