vtlim commented on code in PR #18179:
URL: https://github.com/apache/druid/pull/18179#discussion_r2178692657
##########
docs/querying/sql-query-context.md:
##########
@@ -63,47 +63,6 @@ For more information, see [Overriding default query context
values](../configura
How query context parameters are set differs depending on whether you are
using the [JSON API](../api-reference/sql-api.md) or
[JDBC](../api-reference/sql-jdbc.md).
Review Comment:
> How query context parameters are set differs depending on whether you are
using the [JSON API](../api-reference/sql-api.md) or
[JDBC](../api-reference/sql-jdbc.md).
Remove this sentence and follow existing format for "Learn more" sections
##########
docs/querying/querying.md:
##########
@@ -152,3 +152,6 @@ Possible Druid error codes for the `error` field include:
|`Query cancelled`|500|The query was cancelled through the query cancellation
API.|
|`Truncated response context`|500|An intermediate response context for the
query exceeded the built-in limit of 7KiB.<br/><br/>The response context is an
internal data structure that Druid servers use to share out-of-band information
when sending query results to each other. It is serialized in an HTTP header
with a maximum length of 7KiB. This error occurs when an intermediate response
context sent from a data server (like a Historical) to the Broker exceeds this
limit.<br/><br/>The response context is used for a variety of purposes, but the
one most likely to generate a large context is sharing details about segments
that move during a query. That means this error can potentially indicate that a
very large number of segments moved in between the time a Broker issued a query
and the time it was processed on Historicals. This should rarely, if ever,
occur during normal operation.|
|`Unknown exception`|500|Some other exception occurred. Check errorMessage and
errorClass for details, although keep in mind that the contents of those fields
are free-form and may change from release to release.|
+
+## Learn more
+[Set the Query Context](./set-query-context.md) on how the different
approaches for set query context.
Review Comment:
Fix casing and title
##########
docs/querying/sql-query-context.md:
##########
@@ -63,47 +63,6 @@ For more information, see [Overriding default query context
values](../configura
How query context parameters are set differs depending on whether you are
using the [JSON API](../api-reference/sql-api.md) or
[JDBC](../api-reference/sql-jdbc.md).
Review Comment:
Rename `## Set the query context` to `## Learn more`
Link to how to set query context (again) and query context reference (again)
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
Review Comment:
```suggestion
This reference contains context parameters organized by their scope:
```
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
Review Comment:
We should test/clarify if setting query context parameters here apply to
both Druid SQL _and_ native queries
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
+
+- **General parameters**: Apply to all query types and control execution
behavior, resource limits, and caching
+- **Query type-specific parameters**: Available only for certain query types
like TopN, Timeseries, or GroupBy
+- **Vectorization parameters**: Control vectorized query execution for
supported query types
Review Comment:
```suggestion
- **General parameters**: Applies to all query types.
- **Parameters by query type**: Applies to the specific type of query, such
as TopN, Timeseries, or GroupBy.
- **Vectorization parameters**: Controls vectorized query execution for
supported query types.
```
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
+
+- **General parameters**: Apply to all query types and control execution
behavior, resource limits, and caching
+- **Query type-specific parameters**: Available only for certain query types
like TopN, Timeseries, or GroupBy
+- **Vectorization parameters**: Control vectorized query execution for
supported query types
+
Review Comment:
Below this list, we should move the line referencing sql-query-context.md to
here
##########
docs/querying/sql-query-context.md:
##########
@@ -29,7 +29,7 @@ sidebar_label: "SQL query context"
:::
Druid supports query context parameters which affect [SQL query](./sql.md)
planning.
Review Comment:
Suggest putting together a more coherent introduction:
Ex. paragraph 1
* what are they
* (what does that mean)
* link to how to set it
* link to reference page
Ex. paragraph 2: "you can override"
Ex. paragraph 3: "the following table lists"
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
Review Comment:
Consider rephrasing this section, since there's not really multiple
approaches by the way you send your query, but rather the way you send your
query has 1-2 options. Suggest making it more general.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
+
+Druid uses the Avatica JDBC driver (version 1.23.0 or later recommended). Note
that Avatica does not support passing connection context parameters from the
JDBC connection string—you must use a `Properties` object instead.
+
+**Basic example:**
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+// Connect to /druid/v2/sql/avatica/ on your Broker
+String url =
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";;
+
+// Set any query context parameters you need here
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+connectionProperties.setProperty("priority", "100");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ try (
+ final Statement statement = connection.createStatement();
+ final ResultSet resultSet = statement.executeQuery("SELECT COUNT(*)
FROM data_source WHERE foo = 'bar'")
+ ) {
+ while (resultSet.next()) {
+ // Process result set
+ System.out.println("Count: " + resultSet.getLong(1));
+ }
+ }
+}
+```
+
+**With authentication:**
+
+If your Druid cluster requires authentication, you can include both context
parameters and credentials in the same Properties object:
+
+```java
+Properties connectionProperties = new Properties();
+// Query context parameters
+connectionProperties.setProperty("sqlTimeZone", "Etc/UTC");
+connectionProperties.setProperty("useCache", "false");
+
+// Authentication parameters
+connectionProperties.setProperty("user", "admin");
+connectionProperties.setProperty("password", "password1");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ // Execute queries with both context and authentication
+}
+```
+
+For more details on how to use JDBC driver API, see [Druid SQL JDBC driver
API](../api-reference/sql-jdbc.md).
+
+### SET statements
+
+Beyond using the `context` parameter, you can use `SET` command to specify SQL
query context parameters that modify the behavior of a Druid SQL query. You can
include one or more SET statements before the main SQL query. You can use `SET`
in the both web console and Druid SQL HTTP API.
Review Comment:
Stay consistent with code font style (don't use code font for SET)
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
+
+Druid uses the Avatica JDBC driver (version 1.23.0 or later recommended). Note
that Avatica does not support passing connection context parameters from the
JDBC connection string—you must use a `Properties` object instead.
+
+**Basic example:**
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+// Connect to /druid/v2/sql/avatica/ on your Broker
+String url =
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";;
+
+// Set any query context parameters you need here
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+connectionProperties.setProperty("priority", "100");
Review Comment:
```suggestion
```
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
+
+- **General parameters**: Apply to all query types and control execution
behavior, resource limits, and caching
+- **Query type-specific parameters**: Available only for certain query types
like TopN, Timeseries, or GroupBy
+- **Vectorization parameters**: Control vectorized query execution for
supported query types
+
+For instructions on how the different approaches for set query context in your
queries, see [Set the Query Context](./set-query-context.md).
Review Comment:
```suggestion
To learn how to set the query context, see [Set query
context](./set-query-context.md).
```
##########
docs/querying/sql-query-context.md:
##########
@@ -63,47 +63,6 @@ For more information, see [Overriding default query context
values](../configura
How query context parameters are set differs depending on whether you are
using the [JSON API](../api-reference/sql-api.md) or
[JDBC](../api-reference/sql-jdbc.md).
-### Set the query context when using JSON API
-When using the JSON API, you can configure query context parameters in the
`context` object of the request.
-
-For example:
-
-```
-{
- "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time >
TIMESTAMP '2000-01-01 00:00:00'",
- "context" : {
- "sqlTimeZone" : "America/Los_Angeles",
- "useCache": false
- }
-}
-```
-
-Context parameters can also be set by including [SET](./sql.md#set) as part of
the `query`
-string in the request, separated from the query by `;`. Context parameters set
by `SET` statements take priority over
-values set in `context`.
-
-The following example expresses the previous example in this form:
-
-```
-{
- "query" : "SET sqlTimeZone = 'America/Los_Angeles'; SET useCache = false;
SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'"
-}
-```
-
-### Set the query context when using JDBC
If using JDBC, context parameters can be set using [connection properties
object](../api-reference/sql-jdbc.md).
Review Comment:
```suggestion
```
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
Review Comment:
```suggestion
When connecting to Druid through JDBC, you set query context parameters a
JDBC connection properties object. This approach is useful when integrating
Druid with BI tools or Java applications.
```
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
Review Comment:
suggest removing
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
+
+- **General parameters**: Apply to all query types and control execution
behavior, resource limits, and caching
+- **Query type-specific parameters**: Available only for certain query types
like TopN, Timeseries, or GroupBy
+- **Vectorization parameters**: Control vectorized query execution for
supported query types
+
Review Comment:
Also link to the MSQ context parameters table:
https://druid.apache.org/docs/latest/multi-stage-query/reference#context-parameters
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
Review Comment:
Check capitalization!
##########
docs/querying/query-context-reference.md:
##########
@@ -33,6 +34,14 @@ HTTP POST API, or as properties to the JDBC connection.
Note that setting query context will override both the default value and the
runtime properties value in the format of
`druid.query.default.context.{property_key}` (if set).
+This reference contains all available context parameters organized by their
scope:
+
+- **General parameters**: Apply to all query types and control execution
behavior, resource limits, and caching
+- **Query type-specific parameters**: Available only for certain query types
like TopN, Timeseries, or GroupBy
+- **Vectorization parameters**: Control vectorized query execution for
supported query types
+
+For instructions on how the different approaches for set query context in your
queries, see [Set the Query Context](./set-query-context.md).
Review Comment:
Suggest re-reviewing all references to the new doc to ensure
1. correct title
2. correct capitalization
##########
docs/querying/query-context-reference.md:
##########
@@ -23,8 +23,9 @@ sidebar_label: "Query context"
~ under the License.
-->
-The query context is used for various query configuration parameters. Query
context parameters can be specified in
-the following ways:
+Query context provides runtime configuration for individual queries in Apache
Druid. You can configure query context through context parameters. Each
parameter in the query context controls a specific aspect of query
behavior—from execution timeouts and resource limits to caching policies and
processing strategies.
Review Comment:
```suggestion
The query context provides runtime configuration for individual queries in
Apache Druid. Each parameter in the query context controls a specific aspect of
query behavior—from execution timeouts and resource limits to caching policies
and processing strategies.
```
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
+
+Druid uses the Avatica JDBC driver (version 1.23.0 or later recommended). Note
that Avatica does not support passing connection context parameters from the
JDBC connection string—you must use a `Properties` object instead.
+
+**Basic example:**
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+// Connect to /druid/v2/sql/avatica/ on your Broker
+String url =
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";;
+
+// Set any query context parameters you need here
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+connectionProperties.setProperty("priority", "100");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ try (
+ final Statement statement = connection.createStatement();
+ final ResultSet resultSet = statement.executeQuery("SELECT COUNT(*)
FROM data_source WHERE foo = 'bar'")
+ ) {
+ while (resultSet.next()) {
+ // Process result set
+ System.out.println("Count: " + resultSet.getLong(1));
+ }
+ }
+}
+```
+
+**With authentication:**
+
+If your Druid cluster requires authentication, you can include both context
parameters and credentials in the same Properties object:
+
+```java
+Properties connectionProperties = new Properties();
+// Query context parameters
+connectionProperties.setProperty("sqlTimeZone", "Etc/UTC");
+connectionProperties.setProperty("useCache", "false");
+
+// Authentication parameters
+connectionProperties.setProperty("user", "admin");
+connectionProperties.setProperty("password", "password1");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ // Execute queries with both context and authentication
+}
+```
+
+For more details on how to use JDBC driver API, see [Druid SQL JDBC driver
API](../api-reference/sql-jdbc.md).
+
+### SET statements
+
+Beyond using the `context` parameter, you can use `SET` command to specify SQL
query context parameters that modify the behavior of a Druid SQL query. You can
include one or more SET statements before the main SQL query. You can use `SET`
in the both web console and Druid SQL HTTP API.
+
+**Using SET in the Web Console:**
+
+In the Query tab of web console, you can write your `SET` statements followed
by your query directly. For example,
+
+```sql
+SET useApproximateTopN = false;
+SET sqlTimeZone = 'America/Los_Angeles';
+SET timeout = 90000;
+SELECT some_column, COUNT(*)
+FROM druid.foo
+WHERE other_column = 'foo'
+GROUP BY 1
+ORDER BY 2 DESC
+```
+
+**Using SET via the HTTP API:**
+
+You can also include your `SET` statements as part of the query string in your
API call. For example,
+
+```bash
+curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SET useApproximateTopN = false; SET sqlTimeZone =
'\''America/Los_Angeles'\''; SET timeout = 90000; SELECT some_column, COUNT(*)
FROM druid.foo WHERE other_column = '\''foo'\'' GROUP BY 1 ORDER BY 2 DESC"
+ }'
+```
+
+You can also combine `SET` statements with the `context` field. If you include
both, the parameter value in SET takes precedence:
+
+```json
+{
+ "query": "SET timeout = 90000; SELECT COUNT(*) FROM data_source",
+ "context": {
+ "timeout": 30000, // This will be overridden by SET
+ "priority": 100 // This will still apply
+ }
+}
+```
+
+`SET` statements only apply to the query in the same request. Subsequent
requests are not affected.
+
+`SET` statements work with `SELECT`, `INSERT`, and `REPLACE` queries.
+
+For more details on how to use the `SET` command in your SQL query, see
[SET](sql.md#set).
+
+:::info
+ You cannot use `SET` statements when using Druid SQL JDBC connections.
+:::
+
+
+## Native queries
+
+For native queries, you can include query context parameters in a JSON object
named `context` within your query structure.
+
+Native queries in Druid are JSON objects that you typically send to the Broker
or Router processes. You can submit native queries in two ways:
+
+**Using curl with a query file:**
+
+First, you need to create a JSON file with your query and context parameters.
The following example is the content from `query.json` file.
+
+```json
+{
+ "queryType": "timeseries",
+ "dataSource": "sample_datasource",
+ "granularity": "day",
+ "descending": "true",
+ "filter": {
+ "type": "and",
+ "fields": [
+ { "type": "selector", "dimension": "sample_dimension1", "value":
"sample_value1" },
+ { "type": "or",
+ "fields": [
+ { "type": "selector", "dimension": "sample_dimension2", "value":
"sample_value2" },
+ { "type": "selector", "dimension": "sample_dimension3", "value":
"sample_value3" }
+ ]
+ }
+ ]
+ },
+ "aggregations": [
+ { "type": "longSum", "name": "sample_name1", "fieldName":
"sample_fieldName1" },
+ { "type": "doubleSum", "name": "sample_name2", "fieldName":
"sample_fieldName2" }
+ ],
+ "postAggregations": [
+ { "type": "arithmetic",
+ "name": "sample_divide",
+ "fn": "/",
+ "fields": [
+ { "type": "fieldAccess", "name": "postAgg__sample_name1", "fieldName":
"sample_name1" },
+ { "type": "fieldAccess", "name": "postAgg__sample_name2", "fieldName":
"sample_name2" }
+ ]
+ }
+ ],
+ "intervals": [ "2012-01-01T00:00:00.000/2012-01-03T00:00:00.000" ],
+ // Add context parameters here
+ "context": {
+ "timeout": 30000, // Query timeout in milliseconds
+ "priority": 100, // Higher priority queries get more resources
+ "useCache": false, // Disable cache for testing
+ "finalize": true // Finalize aggregation results
+ }
+}
+```
+
+Then you can submit the query using curl:
Review Comment:
suggest removing
##########
docs/querying/sql-query-context.md:
##########
@@ -29,7 +29,7 @@ sidebar_label: "SQL query context"
:::
Druid supports query context parameters which affect [SQL query](./sql.md)
planning.
-See [Query context](query-context.md) for general query context parameters for
all query types.
+See [Query context](query-context-reference.md) for general query context
parameters for all query types.
## SQL query context parameters
Review Comment:
Remove this heading since it's now the only one. Check for any links that
point to this specific section. Also check for links to
`sql-query-context.md#set-the-query-context` since that will be removed too.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
+
+Druid uses the Avatica JDBC driver (version 1.23.0 or later recommended). Note
that Avatica does not support passing connection context parameters from the
JDBC connection string—you must use a `Properties` object instead.
+
+**Basic example:**
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+// Connect to /druid/v2/sql/avatica/ on your Broker
+String url =
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";;
+
+// Set any query context parameters you need here
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+connectionProperties.setProperty("priority", "100");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
Review Comment:
Since this includes new code not in the [original
example](https://druid.apache.org/docs/latest/querying/sql-query-context#set-the-query-context),
let's be sure to test that it works
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,310 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
+
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+The query context gives you fine-grained control over how Apache Druid
executes your individual queries. While the default settings in Druid work well
for most queries, you can set the query context to handle specific requirements
and optimize performance.
+
+Common use cases for the query context include:
+- Override default timeouts for long-running queries or complex aggregations.
+- Control resource usage to prevent expensive queries from overwhelming your
cluster.
+- Debug query performance by disabling caching during testing.
+- Configure SQL-specific behaviors like time zones for accurate time-based
analysis.
+- Set priorities to ensure critical queries get computational resources first.
+- Adjust memory limits for queries that process large datasets.
+
+Druid offers multiple approaches for you to set up your query context. This
guide covers all the approaches—from the web console to programmatic APIs with
practical examples you can adapt for your use case.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as context carriers. For a complete list
of available parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The easiest way to set query context is through the Druid web console. You can
define context parameters using the Query context editor with these steps:
+
+1. Open the **Query** tab in the Web Console.
+2. Write your SQL query in the query editor. For example:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source
+ WHERE foo = 'bar' AND __time >= CURRENT_TIMESTAMP - INTERVAL '1' DAY
+ ```
+3. Click the **Engine: native, sql-native** selector (or current engine) next
to the **Run** button.
+4. Select **Edit context** from the menu.
+5. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "priority": 100,
+ "useCache": false
+ }
+ ```
+6. Click **Save** to apply the context to your query.
+7. Click **Run** to execute your query with the specified context parameters.
+
+The web console validates your JSON and highlights any syntax errors before
you run the query.
+
+For more information about using the Druid SQL Web Console Query view, see
[Query view](../operations/web-console.md#query).
+
+## Druid SQL
+
+When you use Druid SQL programmatically—such as in applications, automated
scripts, or database tools, you can set query context using three different
methods depending on how you execute your queries beyond web console.
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+To set query context via the HTTP API, You can start with your SQL query:
+
+ ```sql
+ SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time > TIMESTAMP
'2000-01-01 00:00:00'
+ ```
+
+Then you need to create a JSON request with your query and context parameters.
The following example sets the `sqlTimeZone` parameter:
+
+ ```json
+ {
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar' AND __time
> TIMESTAMP '2000-01-01 00:00:00'",
+ "context" : {
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+ }
+ ```
+
+You can then send the request to Druid's SQL API HTTP endpoint:
+
+ ```bash
+ curl -X POST 'http://localhost:8888/druid/v2/sql' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "query": "SELECT COUNT(*) FROM data_source WHERE foo = '\''bar'\'' AND
__time > TIMESTAMP '\''2000-01-01 00:00:00'\''",
+ "context": {
+ "sqlTimeZone": "America/Los_Angeles"
+ }
+ }'
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
+
+You can set multiple context parameters in a single request:
+
+```json
+{
+ "query" : "SELECT COUNT(*) FROM data_source WHERE foo = 'bar'",
+ "context" : {
+ "timeout" : 30000,
+ "priority" : 100,
+ "useCache" : false,
+ "sqlTimeZone" : "America/Los_Angeles"
+ }
+}
+```
+For more information on how to format Druid SQL API requests and handle
responses, see [Druid SQL API](../api-reference/sql-api.md).
+
+
+### JDBC driver API
+
+When connecting to Druid through JDBC, you set query context parameters as
connection properties. This approach is useful when integrating Druid with BI
tools or Java applications.
+
+Druid uses the Avatica JDBC driver (version 1.23.0 or later recommended). Note
that Avatica does not support passing connection context parameters from the
JDBC connection string—you must use a `Properties` object instead.
+
+**Basic example:**
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+// Connect to /druid/v2/sql/avatica/ on your Broker
+String url =
"jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";;
+
+// Set any query context parameters you need here
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+connectionProperties.setProperty("priority", "100");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ try (
+ final Statement statement = connection.createStatement();
+ final ResultSet resultSet = statement.executeQuery("SELECT COUNT(*)
FROM data_source WHERE foo = 'bar'")
+ ) {
+ while (resultSet.next()) {
+ // Process result set
+ System.out.println("Count: " + resultSet.getLong(1));
+ }
+ }
+}
+```
+
+**With authentication:**
Review Comment:
Suggest removing this if it's already covered; if you want, you can mention
it in a line and link to the specific spot
##########
docs/querying/query-context-reference.md:
##########
@@ -23,8 +23,9 @@ sidebar_label: "Query context"
~ under the License.
-->
-The query context is used for various query configuration parameters. Query
context parameters can be specified in
-the following ways:
+Query context provides runtime configuration for individual queries in Apache
Druid. You can configure query context through context parameters. Each
parameter in the query context controls a specific aspect of query
behavior—from execution timeouts and resource limits to caching policies and
processing strategies.
+
+Query context parameters can be specified in the following ways:
Review Comment:
Lines 28-32 can be removed since it's now covered in the new doc
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
