vtlim commented on code in PR #18101:
URL: https://github.com/apache/druid/pull/18101#discussion_r2167440593
##########
docs/api-reference/sql-api.md:
##########
@@ -86,7 +86,7 @@ The request body takes the following properties:
* The `header` property is set to true.
* The version of Druid supports `typesHeader` and `sqlTypesHeader`,
regardless of whether either property is set.
-* `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.
+* `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.
You can also set the context through `SET` command. For how to using `SET`
Command in your Druid SQL query, see [SET statement](../querying/sql.md#set)
for more information.
Review Comment:
```suggestion
* `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.
You can also set the context through the SQL SET command. For more information,
see [Druid SQL overview](../querying/sql.md#set).
```
##########
docs/multi-stage-query/reference.md:
##########
@@ -381,21 +381,14 @@ For more information about clustering, see
[Clustering](concepts.md#clustering).
## Context parameters
-In addition to the Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine accepts certain context parameters that are specific to it.
-
-Use context parameters alongside your queries to customize the behavior of the
query. If you're using the API, include the context parameters in the query
context when you submit a query:
-
-```json
-{
- "query": "SELECT 1 + 1",
- "context": {
- "<key>": "<value>",
- "maxNumTasks": 3
- }
-}
-```
+Along with the standard Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine also supports its own set of specific context parameters. These
parameters can be used with your queries to tailor how they are executed.
+
+For detailed instructions on configuring query context parameters, refer to
the [query context parameters](../querying/query-context.md) documentation.
+
+Beyond that, you can also define context parameters using `SET` statements
directly within your SQL query. This method is especially useful for quick,
inline parameter configuration.
+For how to using `SET` command, See [SET Command](../querying/sql.md#set).
Review Comment:
```suggestion
```
This should be covered by the previous line and upcoming doc reorg
##########
docs/multi-stage-query/reference.md:
##########
@@ -381,21 +381,14 @@ For more information about clustering, see
[Clustering](concepts.md#clustering).
## Context parameters
-In addition to the Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine accepts certain context parameters that are specific to it.
-
-Use context parameters alongside your queries to customize the behavior of the
query. If you're using the API, include the context parameters in the query
context when you submit a query:
-
-```json
-{
- "query": "SELECT 1 + 1",
- "context": {
- "<key>": "<value>",
- "maxNumTasks": 3
- }
-}
-```
+Along with the standard Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine also supports its own set of specific context parameters. These
parameters can be used with your queries to tailor how they are executed.
+
+For detailed instructions on configuring query context parameters, refer to
the [query context parameters](../querying/query-context.md) documentation.
Review Comment:
```suggestion
For detailed instructions on configuring query context parameters, refer to
[Query context](../querying/query-context.md).
```
##########
docs/multi-stage-query/reference.md:
##########
@@ -381,21 +381,14 @@ For more information about clustering, see
[Clustering](concepts.md#clustering).
## Context parameters
-In addition to the Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine accepts certain context parameters that are specific to it.
-
-Use context parameters alongside your queries to customize the behavior of the
query. If you're using the API, include the context parameters in the query
context when you submit a query:
-
-```json
-{
- "query": "SELECT 1 + 1",
- "context": {
- "<key>": "<value>",
- "maxNumTasks": 3
- }
-}
-```
+Along with the standard Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine also supports its own set of specific context parameters. These
parameters can be used with your queries to tailor how they are executed.
+
+For detailed instructions on configuring query context parameters, refer to
the [query context parameters](../querying/query-context.md) documentation.
+
+Beyond that, you can also define context parameters using `SET` statements
directly within your SQL query. This method is especially useful for quick,
inline parameter configuration.
+For how to using `SET` command, See [SET Command](../querying/sql.md#set).
-If you're using the web console, you can specify the context parameters
through various UI options.
+Note: While the examples above use the `SELECT` statement, you can also
specify context parameters in Druid SQL queries that use `INSERT` or `REPLACE`.
Review Comment:
Move this before "For detailed instruction" since it's more important.
Suggested revision:
```
You can specify the context parameters in SELECT, INSERT, or REPLACE
statements.
```
##########
docs/querying/sql.md:
##########
@@ -379,24 +379,11 @@ documentation for more information on the output of
EXPLAIN PLAN.
Request logs show the exact native query that will be run. Alternatively, to
see the native query plan, set `useNativeQueryExplain` to true in the query
context.
:::
-## Identifiers and literals
+## SET
-Identifiers like datasource and column names can optionally be quoted using
double quotes. To escape a double quote
-inside an identifier, use another double quote, like `"My ""very own""
identifier"`. All identifiers are case-sensitive
-and no implicit case conversions are performed.
+`SET` statements allow you to specify SQL query context parameters that modify
the behavior of a Druid SQL query. These statements can be included before the
main SQL query and are supported in multiple query interfaces, including the
The Druid SQL [JSON API](../api-reference/sql-api.md) and the Druid Web
Console.
Review Comment:
```suggestion
SET statements allow you 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. Druid supports using SET in the Druid SQL [JSON
API](../api-reference/sql-api.md) and the web console.
```
##########
docs/multi-stage-query/reference.md:
##########
@@ -381,21 +381,14 @@ For more information about clustering, see
[Clustering](concepts.md#clustering).
## Context parameters
-In addition to the Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine accepts certain context parameters that are specific to it.
-
-Use context parameters alongside your queries to customize the behavior of the
query. If you're using the API, include the context parameters in the query
context when you submit a query:
-
-```json
-{
- "query": "SELECT 1 + 1",
- "context": {
- "<key>": "<value>",
- "maxNumTasks": 3
- }
-}
-```
+Along with the standard Druid SQL [context
parameters](../querying/sql-query-context.md), the multi-stage query task
engine also supports its own set of specific context parameters. These
parameters can be used with your queries to tailor how they are executed.
Review Comment:
```suggestion
The multi-stage query task engine supports the [SQL context
parameters](../querying/sql-query-context.md), as well as its own set of
specific context parameters. Use these parameters to tailor how Druid executes
your query.
```
##########
docs/querying/sql.md:
##########
@@ -413,6 +400,29 @@ SET timeout = 90000;
SELECT some_column, COUNT(*) FROM druid.foo WHERE other_column = 'foo' GROUP
BY 1 ORDER BY 2 DESC
```
+If present, these `SET` statements assign [SQL query context
parameter](../querying/sql-query-context.md) which only apply to the non-`SET`
statement of the same request and subsequent requests are not affected.
Review Comment:
```suggestion
SET statements only apply to the query in the same request. Subsequent
requests are not affected.
```
##########
docs/querying/sql.md:
##########
@@ -379,24 +379,11 @@ documentation for more information on the output of
EXPLAIN PLAN.
Request logs show the exact native query that will be run. Alternatively, to
see the native query plan, set `useNativeQueryExplain` to true in the query
context.
:::
-## Identifiers and literals
+## SET
-Identifiers like datasource and column names can optionally be quoted using
double quotes. To escape a double quote
-inside an identifier, use another double quote, like `"My ""very own""
identifier"`. All identifiers are case-sensitive
-and no implicit case conversions are performed.
+`SET` statements allow you to specify SQL query context parameters that modify
the behavior of a Druid SQL query. These statements can be included before the
main SQL query and are supported in multiple query interfaces, including the
The Druid SQL [JSON API](../api-reference/sql-api.md) and the Druid Web
Console.
Review Comment:
Also add a link to web console:
https://druid.apache.org/docs/latest/operations/web-console
##########
docs/querying/sql.md:
##########
@@ -413,6 +400,29 @@ SET timeout = 90000;
SELECT some_column, COUNT(*) FROM druid.foo WHERE other_column = 'foo' GROUP
BY 1 ORDER BY 2 DESC
```
+If present, these `SET` statements assign [SQL query context
parameter](../querying/sql-query-context.md) which only apply to the non-`SET`
statement of the same request and subsequent requests are not affected.
+
+You can mix `SET` statement and [Context
Parameter](../querying/query-context.md) with `SET` overriding on key conflicts.
+
+### Current limitations
+
+- `SET` statements currently support literal values only. For example,
numbers, strings, booleans.
+- You must still provide arrays or JSON objects via the `context` field.
+
+
Review Comment:
This is really two ways to say the same thing. We don't need to create a new
section for just one limitation.
```suggestion
Note that you can only use SET to assign literal values, such as numbers,
strings, or Booleans. To set a query context parameter to an array or JSON
object, use the `context` field rather than SET.
```
##########
docs/querying/sql.md:
##########
@@ -379,24 +379,11 @@ documentation for more information on the output of
EXPLAIN PLAN.
Request logs show the exact native query that will be run. Alternatively, to
see the native query plan, set `useNativeQueryExplain` to true in the query
context.
:::
-## Identifiers and literals
+## SET
-Identifiers like datasource and column names can optionally be quoted using
double quotes. To escape a double quote
-inside an identifier, use another double quote, like `"My ""very own""
identifier"`. All identifiers are case-sensitive
-and no implicit case conversions are performed.
+`SET` statements allow you to specify SQL query context parameters that modify
the behavior of a Druid SQL query. These statements can be included before the
main SQL query and are supported in multiple query interfaces, including the
The Druid SQL [JSON API](../api-reference/sql-api.md) and the Druid Web
Console.
-Literal strings should be quoted with single quotes, like `'foo'`. Literal
strings with Unicode escapes can be written
-like `U&'fo\00F6'`, where character codes in hex are prefixed by a backslash.
Literal numbers can be written in forms
-like `100` (denoting an integer), `100.0` (denoting a floating point value),
or `1.0e5` (scientific notation). Literal
-timestamps can be written like `TIMESTAMP '2000-01-01 00:00:00'`. Literal
intervals, used for time arithmetic, can be
-written like `INTERVAL '1' HOUR`, `INTERVAL '1 02:03' DAY TO MINUTE`,
`INTERVAL '1-2' YEAR TO MONTH`, and so on.
-
-## SET statements
-
-The Druid SQL [JSON API](../api-reference/sql-api.md) supports including 0 or
more `SET` statements separated by `;`
-preceding a statement to execute in the `query` string of the request. If
present, these `SET` statements
-assign [SQL query context parameter values](../querying/sql-query-context.md)
which only apply to the non-`SET`
-statement of the same request (subsequent requests are not affected).
+You can include 0 or more `SET` statements, each separated by a semicolon `;`,
preceding a statement to execute in the `query` string of the request.
Review Comment:
This is now covered by information in the preceding and following sections.
```suggestion
```
##########
docs/querying/sql.md:
##########
@@ -413,6 +400,29 @@ SET timeout = 90000;
SELECT some_column, COUNT(*) FROM druid.foo WHERE other_column = 'foo' GROUP
BY 1 ORDER BY 2 DESC
```
+If present, these `SET` statements assign [SQL query context
parameter](../querying/sql-query-context.md) which only apply to the non-`SET`
statement of the same request and subsequent requests are not affected.
+
+You can mix `SET` statement and [Context
Parameter](../querying/query-context.md) with `SET` overriding on key conflicts.
Review Comment:
```suggestion
If you use the [JSON API](../api-reference/sql-api.md), you can also include
query context parameters using the `context` field. If you include both, the
parameter value in SET takes precedence over the parameter value in `context`.
```
--
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]
