techdocsmith commented on code in PR #18179:
URL: https://github.com/apache/druid/pull/18179#discussion_r2205835747
##########
docs/querying/query-context-reference.md:
##########
@@ -23,20 +23,26 @@ 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:
-
-- For [Druid SQL](../api-reference/sql-api.md), context parameters are
provided either in a JSON object named `context` to the
-HTTP POST API, or as properties to the JDBC connection.
-- For [native queries](querying.md), context parameters are provided in a JSON
object named `context`.
+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.
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).
Review Comment:
```suggestion
`druid.query.default.context.{property_key}`.
```
Avoid parens. Also it takes effect regardless if the property is set or not.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+id: set-query-context
+title: "Set query context"
Review Comment:
Suggest a more user-centric title:
Modify query behavior with the query context
Configure query behavior with the query context.
##########
docs/querying/query-context-reference.md:
##########
@@ -23,20 +23,26 @@ 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:
-
-- For [Druid SQL](../api-reference/sql-api.md), context parameters are
provided either in a JSON object named `context` to the
-HTTP POST API, or as properties to the JDBC connection.
-- For [native queries](querying.md), context parameters are provided in a JSON
object named `context`.
+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.
Note that setting query context will override both the default value and the
runtime properties value in the format of
Review Comment:
```suggestion
Query context overrides both the default value and the runtime properties
value in the format of
```
I would also suggest that it is not a "note'. Also avoid future.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+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 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 provides several ways to set query context, and the method you use
depends on how and where you're submitting your query.
+This guide lists how to set query context for each method of submitting
queries.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as query context carriers. For available
parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The most straightforward method to configure query context parameters is via
the Druid web console. In web console, you can set up context parameters for
both Druid SQL and native queries.
+
+The following steps outline how to define query context parameters:
+
+1. Open the **Query** tab in the web console.
+
+1. **Click** the **Engine** selector next to the **Run** button to choose the
appropriate query type:
+
+- Selects the **JSON (native) engine** for native queries.
+- Selects the **SQL (native) engine** for Druid SQL queries.
+- Selects the **SQL (task) engine** for Multi-stage queries (MSQ).
+- Selects the **Auto engine** to let the console detect the query type
automatically. You just paste your query into the **Query** view, and the web
console chooses the right engine for you.
+
+2. Enter the query you want to run in the web console.
+
+3. Select **Edit context** from the menu.
+4. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "useCache": false
+ }
+ ```
+5. Click **Save** to apply the context to your query.
+6. 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 [Druid Web
Console](./set-query-context.md#druid-web-console).
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+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"
+ }
+ }
+ ```
+
+Druid will execute your query with the specified context parameters and return
the results.
Review Comment:
```suggestion
Druid executes your query using the specified context parameters and return
the results.
```
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+id: set-query-context
+title: "Set query context"
+sidebar_label: "Set query context"
+---
Review Comment:
Suggest inclduing a `description:` front matter that summarizes the
document. Not widely used in the Druid docs right now, but it is helpful with
search results.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+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 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 provides several ways to set query context, and the method you use
depends on how and where you're submitting your query.
+This guide lists how to set query context for each method of submitting
queries.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as query context carriers. For available
parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The most straightforward method to configure query context parameters is via
the Druid web console. In web console, you can set up context parameters for
both Druid SQL and native queries.
+
+The following steps outline how to define query context parameters:
+
+1. Open the **Query** tab in the web console.
+
+1. **Click** the **Engine** selector next to the **Run** button to choose the
appropriate query type:
+
+- Selects the **JSON (native) engine** for native queries.
+- Selects the **SQL (native) engine** for Druid SQL queries.
+- Selects the **SQL (task) engine** for Multi-stage queries (MSQ).
+- Selects the **Auto engine** to let the console detect the query type
automatically. You just paste your query into the **Query** view, and the web
console chooses the right engine for you.
+
+2. Enter the query you want to run in the web console.
+
+3. Select **Edit context** from the menu.
+4. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "useCache": false
+ }
+ ```
+5. Click **Save** to apply the context to your query.
+6. 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 [Druid Web
Console](./set-query-context.md#druid-web-console).
Review Comment:
+1 to @vtlim comment, also wondering if it is necessary to mention that
these are "beyond the [W/w]eb consloe"
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+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 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 provides several ways to set query context, and the method you use
depends on how and where you're submitting your query.
+This guide lists how to set query context for each method of submitting
queries.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as query context carriers. For available
parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The most straightforward method to configure query context parameters is via
the Druid web console. In web console, you can set up context parameters for
both Druid SQL and native queries.
+
+The following steps outline how to define query context parameters:
+
+1. Open the **Query** tab in the web console.
+
+1. **Click** the **Engine** selector next to the **Run** button to choose the
appropriate query type:
+
+- Selects the **JSON (native) engine** for native queries.
+- Selects the **SQL (native) engine** for Druid SQL queries.
+- Selects the **SQL (task) engine** for Multi-stage queries (MSQ).
+- Selects the **Auto engine** to let the console detect the query type
automatically. You just paste your query into the **Query** view, and the web
console chooses the right engine for you.
Review Comment:
+1 for @vtlim 's comment here since the DART engine is coming. Maybe it is
not worth maintaining a list of engines here and just say. "Unless otherwsise
instructed, you can leave the engine as `auto` to let Druid choose the best
engine for you.
##########
docs/querying/set-query-context.md:
##########
@@ -0,0 +1,240 @@
+---
+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 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 provides several ways to set query context, and the method you use
depends on how and where you're submitting your query.
+This guide lists how to set query context for each method of submitting
queries.
+
+Before you begin, identify which context parameters you need to configure in
order to establish your query context as query context carriers. For available
parameters and their descriptions, see [Query context
reference](query-context-reference.md).
+
+## Druid web console
+
+The most straightforward method to configure query context parameters is via
the Druid web console. In web console, you can set up context parameters for
both Druid SQL and native queries.
+
+The following steps outline how to define query context parameters:
+
+1. Open the **Query** tab in the web console.
+
+1. **Click** the **Engine** selector next to the **Run** button to choose the
appropriate query type:
+
+- Selects the **JSON (native) engine** for native queries.
+- Selects the **SQL (native) engine** for Druid SQL queries.
+- Selects the **SQL (task) engine** for Multi-stage queries (MSQ).
+- Selects the **Auto engine** to let the console detect the query type
automatically. You just paste your query into the **Query** view, and the web
console chooses the right engine for you.
+
+2. Enter the query you want to run in the web console.
+
+3. Select **Edit context** from the menu.
+4. In the **Edit query context** dialog, add your context parameters as JSON
key-value pairs:
+ ```json
+ {
+ "timeout": 300000,
+ "useCache": false
+ }
+ ```
+5. Click **Save** to apply the context to your query.
+6. 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 [Druid Web
Console](./set-query-context.md#druid-web-console).
+
+### HTTP API
+
+When using the HTTP API, you include query context parameters in the `context`
object of your JSON request.
+
+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"
+ }
+ }
+ ```
+
+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,
+ "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 a JDBC
connection properties object. 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.
+
+
+You can set query context parameters when creating your JDBC connection:
+
+```java
+String url =
"jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/";;
+
+// Set any query context parameters you need here.
+Properties connectionProperties = new Properties();
+connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
+connectionProperties.setProperty("useCache", "false");
+
+try (Connection connection = DriverManager.getConnection(url,
connectionProperties)) {
+ // create and execute statements, process result sets, etc
+}
+```
+
+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:
Three senteces in a row with "you can" construction. Vary the structure for
example:
You can use the `SET` command to specify SQL query context parameters that
modify the behavior of a Druid SQL query. Druid accepts one or more SET
statements before the main SQL query. The `SET` command works in the both web
console and the Druid SQL HTTP API.
--
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]
