This is an automated email from the ASF dual-hosted git repository.
vogievetsky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new 75d9ece6654 Docs: update descriptions and default values (#17473)
75d9ece6654 is described below
commit 75d9ece665460fdfab119576bae707ba7f60bbcd
Author: Katya Macedo <[email protected]>
AuthorDate: Wed Nov 13 18:29:27 2024 -0600
Docs: update descriptions and default values (#17473)
---
docs/querying/sql-query-context.md | 50 ++++++++++++++++++++------------------
1 file changed, 26 insertions(+), 24 deletions(-)
diff --git a/docs/querying/sql-query-context.md
b/docs/querying/sql-query-context.md
index e003ceec69d..775bd4ca48f 100644
--- a/docs/querying/sql-query-context.md
+++ b/docs/querying/sql-query-context.md
@@ -33,34 +33,36 @@ See [Query context](query-context.md) for general query
context parameters for a
## SQL query context parameters
-Configure Druid SQL query planning using the parameters in the table below.
+The following table lists query context parameters you can use to configure
Druid SQL planning.
+You can override a parameter's default value by setting a runtime property in
the format `druid.query.default.context.{query_context_key}`.
+For more information, see [Overriding default query context
values](../configuration/index.md#overriding-default-query-context-values).
|Parameter|Description|Default value|
|---------|-----------|-------------|
-|`sqlQueryId`|Unique identifier given to this SQL query. For HTTP client, it
will be returned in `X-Druid-SQL-Query-Id` header.<br/><br/>To specify a unique
identifier for SQL query, use `sqlQueryId` instead of
[`queryId`](query-context.md). Setting `queryId` for a SQL request has no
effect. All native queries underlying SQL use an auto-generated
`queryId`.|auto-generated|
-|`sqlTimeZone`|Sets the time zone for this connection, which will affect how
time functions and timestamp literals behave. Should be a time zone name like
"America/Los_Angeles" or offset like "-08:00".|`druid.sql.planner.sqlTimeZone`
on the Broker (default: UTC)|
-|`sqlStringifyArrays`|When set to true, result columns which return array
values will be serialized into a JSON string in the response instead of as an
array|true, except for JDBC connections, where it is always false|
-|`useApproximateCountDistinct`|Whether to use an approximate cardinality
algorithm for `COUNT(DISTINCT
foo)`.|`druid.sql.planner.useApproximateCountDistinct` on the Broker (default:
true)|
-|`useGroupingSetForExactDistinct`|Whether to use grouping sets to execute
queries with multiple exact distinct
aggregations.|`druid.sql.planner.useGroupingSetForExactDistinct` on the Broker
(default: false)|
-|`useApproximateTopN`|Whether to use approximate [TopN queries](topnquery.md)
when a SQL query could be expressed as such. If false, exact [GroupBy
queries](groupbyquery.md) will be used
instead.|`druid.sql.planner.useApproximateTopN` on the Broker (default: true)|
-|`enableTimeBoundaryPlanning`|If true, SQL queries will get converted to
TimeBoundary queries wherever possible. TimeBoundary queries are very efficient
for min-max calculation on `__time` column in a datasource
|`druid.query.default.context.enableTimeBoundaryPlanning` on the Broker
(default: false)|
-|`useNativeQueryExplain`|If true, `EXPLAIN PLAN FOR` will return the explain
plan as a JSON representation of equivalent native query(s), else it will
return the original version of explain plan generated by Calcite.<br /><br
/>This property is provided for backwards compatibility. It is not recommended
to use this parameter unless you were depending on the older
behavior.|`druid.sql.planner.useNativeQueryExplain` on the Broker (default:
true)|
-|`sqlFinalizeOuterSketches`|If false (default behavior in Druid 25.0.0 and
later), `DS_HLL`, `DS_THETA`, and `DS_QUANTILES_SKETCH` return sketches in
query results, as documented. If true (default behavior in Druid 24.0.1 and
earlier), sketches from these functions are finalized when they appear in query
results.<br /><br />This property is provided for backwards compatibility with
behavior in Druid 24.0.1 and earlier. It is not recommended to use this
parameter unless you were depending [...]
-|`sqlUseBoundAndSelectors`|If false (default behavior if
`druid.generic.useDefaultValueForNull=false` in Druid 27.0.0 and later), the
SQL planner will use [equality](./filters.md#equality-filter),
[null](./filters.md#null-filter), and [range](./filters.md#range-filter)
filters instead of [selector](./filters.md#selector-filter) and
[bounds](./filters.md#bound-filter). This value must be set to `false` for
correct behavior for filtering `ARRAY` typed values. | Defaults to same value
as `d [...]
-|`sqlReverseLookup`|Whether to consider the [reverse-lookup
rewrite](lookups.md#reverse-lookup) of the `LOOKUP` function during SQL
planning.<br /><br />Calls to `LOOKUP` are only reversed when the number of
matching keys is lower than both `inSubQueryThreshold` and
`sqlReverseLookupThreshold`.|true|
-|`sqlReverseLookupThreshold`|Maximum size of `IN` filter to create when
applying a [reverse-lookup rewrite](lookups.md#reverse-lookup). If a `LOOKUP`
call matches more keys than this threshold, it is left as-is.<br /><br />If
`inSubQueryThreshold` is lower than `sqlReverseLookupThreshold`, the
`inSubQueryThreshold` is used as the threshold instead.|10000|
-|`sqlPullUpLookup`|Whether to consider the [pull-up
rewrite](lookups.md#pull-up) of the `LOOKUP` function during SQL planning.|true|
-|`enableJoinLeftTableScanDirect`|This flag applies to queries which have
joins. For joins, where left child is a simple scan with a filter, by default,
druid will run the scan as a query and the join the results to the right child
on broker. Setting this flag to true overrides that behavior and druid will
attempt to push the join to data servers instead. Please note that the flag
could be applicable to queries even if there is no explicit join. since queries
can internally translated in [...]
-|`maxNumericInFilters`|Max limit for the amount of numeric values that can be
compared for a string type dimension when the entire SQL WHERE clause of a
query translates only to an [OR](../querying/filters.md#or) of [Bound
filter](../querying/filters.md#bound-filter). By default, Druid does not
restrict the amount of of numeric Bound Filters on String columns, although
this situation may block other queries from running. Set this parameter to a
smaller value to prevent Druid from running [...]
-|`inFunctionThreshold`| At or beyond this threshold number of values, SQL `IN`
is converted to [`SCALAR_IN_ARRAY`](sql-functions.md#scalar_in_array). A
threshold of 0 forces this conversion in all cases. A threshold of
[Integer.MAX_VALUE] disables this conversion. The converted function is
eligible for fewer planning-time optimizations, which speeds up planning, but
may prevent certain planning-time optimizations.| `100`|
-|`inFunctionExprThreshold`|At or beyond this threshold number of values, SQL
`IN` is eligible for execution using the native function `scalar_in_array`
rather than an <code>||</code> of `==`, even if the number of values
is below `inFunctionThreshold`. This property only affects translation of SQL
`IN` to a [native expression](math-expr.md). It does not affect translation of
SQL `IN` to a [native filter](filters.md). This property is provided for
backwards compatibility purpose [...]
-|`inSubQueryThreshold`|At or beyond this threshold number of values, SQL `IN`
is converted to `JOIN` on an inline table. `inFunctionThreshold` takes priority
over this setting. A threshold of 0 forces usage of an inline table in all
cases where the size of a SQL `IN` is larger than `inFunctionThreshold`. A
threshold of `2147483647` disables the rewrite of SQL `IN` to `JOIN`.
|`2147483647`|
+|`sqlQueryId`|SQL query ID. For HTTP client, Druid returns it in the
`X-Druid-SQL-Query-Id` header.<br/><br/>To specify a SQL query ID, use
`sqlQueryId` instead of [`queryId`](query-context.md). Setting `queryId` for a
SQL request has no effect. All native queries underlying SQL use an
auto-generated `queryId`.|auto-generated|
+|`sqlTimeZone`|Time zone for a connection. For example, "America/Los_Angeles"
or an offset like "-08:00". This parameter affects how time functions and
timestamp literals behave. |UTC|
+|`sqlStringifyArrays`|If `true`, Druid serializes result columns with array
values as JSON strings in the response instead of arrays.|`true`, except for
JDBC connections, where it's always `false`|
+|`useApproximateCountDistinct`|Whether to use an approximate cardinality
algorithm for `COUNT(DISTINCT foo)`.|`true`|
+|`useGroupingSetForExactDistinct`|Whether to use grouping sets to execute
queries with multiple exact distinct aggregations.|`false`|
+|`useApproximateTopN`|If `true`, Druid converts SQL queries to approximate
[TopN queries](topnquery.md) wherever possible. If `false`, Druid uses exact
[GroupBy queries](groupbyquery.md) instead.|`true`|
+|`enableTimeBoundaryPlanning`|If `true`, Druid converts SQL queries to [time
boundary queries](timeboundaryquery.md) wherever possible. Time boundary
queries are very efficient for min-max calculation on the `__time` column in a
datasource. |`false`|
+|`useNativeQueryExplain`|If `true`, `EXPLAIN PLAN FOR` returns the explain
plan as a JSON representation of equivalent native query, else it returns the
original version of explain plan generated by Calcite.<br /><br />This property
is provided for backwards compatibility. We don't recommend setting this
parameter unless your application depends on the older behavior.|`true`|
+|`sqlFinalizeOuterSketches`|If `false` (default behavior in Druid 25.0.0 and
later), `DS_HLL`, `DS_THETA`, and `DS_QUANTILES_SKETCH` return sketches in
query results. If `true` (default behavior in Druid 24.0.1 and earlier), Druid
finalizes sketches from these functions when they appear in query results.<br
/><br />This property is provided for backwards compatibility with behavior in
Druid 24.0.1 and earlier. We don't recommend setting this parameter unless your
application uses Druid 2 [...]
+|`sqlUseBoundAndSelectors`|If `false` (default behavior if
`druid.generic.useDefaultValueForNull=false` in Druid 27.0.0 and later), the
SQL planner uses [equality](./filters.md#equality-filter),
[null](./filters.md#null-filter), and [range](./filters.md#range-filter)
filters instead of [selector](./filters.md#selector-filter) and
[bounds](./filters.md#bound-filter). For filtering `ARRAY` typed values,
`sqlUseBoundAndSelectors` must be `false`. | Defaults to same value as
`druid.generic.u [...]
+|`sqlReverseLookup`|Whether to consider the [reverse-lookup
rewrite](lookups.md#reverse-lookup) of the `LOOKUP` function during SQL
planning.<br /><br />Druid reverses calls to `LOOKUP` only when the number of
matching keys is lower than both `inSubQueryThreshold` and
`sqlReverseLookupThreshold`.|`true`|
+|`sqlReverseLookupThreshold`|Maximum size of `IN` filter to create when
applying a [reverse-lookup rewrite](lookups.md#reverse-lookup). If a `LOOKUP`
call matches more keys than the specified threshold, it remains unchanged.<br
/><br />If `inSubQueryThreshold` is lower than `sqlReverseLookupThreshold`,
Druid uses `inSubQueryThreshold` threshold instead.|10000|
+|`sqlPullUpLookup`|Whether to consider the [pull-up
rewrite](lookups.md#pull-up) of the `LOOKUP` function during SQL
planning.|`true`|
+|`enableJoinLeftTableScanDirect`|This parameter applies to queries with joins.
By default, when the left child is a simple scan with a filter, Druid runs the
scan as a query, then joins it with the right child on the Broker. Setting this
parameter to `true` overrides that behavior and pushes the join to the data
servers instead. Even if a query doesn't explicitly include a join, this
parameter may still apply since the SQL planner can translate the query into a
join internally.|`false`|
+|`maxNumericInFilters`|Max limit for the amount of numeric values that Druid
can compare for a string type dimension when the entire SQL WHERE clause of a
query translates only to an [OR](../querying/filters.md#or) of [bound
filter](../querying/filters.md#bound-filter). By default, Druid doesn't
restrict the amount of numeric bound filters on string columns, although this
situation may block other queries from running. Set this parameter to a smaller
value to prevent Druid from running q [...]
+|`inFunctionThreshold`| At or beyond this threshold number of values, Druid
converts SQL `IN` to [`SCALAR_IN_ARRAY`](sql-functions.md#scalar_in_array). A
threshold of 0 forces this conversion in all cases. A threshold of
`Integer.MAX_VALUE` disables this conversion. The converted function is
eligible for fewer planning-time optimizations, which speeds up planning, but
may prevent certain planning-time optimizations.| `100`|
+|`inFunctionExprThreshold`|At or beyond this threshold number of values, SQL
`IN` is eligible for execution using the native function `scalar_in_array`
rather than an <code>||</code> of `==`, even if the number of values
is below `inFunctionThreshold`. This property only affects translation of SQL
`IN` to a [native expression](math-expr.md). It doesn't affect translation of
SQL `IN` to a [native filter](filters.md). This property is provided for
backwards compatibility purposes [...]
+|`inSubQueryThreshold`|At or beyond this threshold number of values, Druid
converts SQL `IN` to `JOIN` on an inline table. `inFunctionThreshold` takes
priority over this setting. A threshold of 0 forces usage of an inline table in
all cases where the size of a SQL `IN` is larger than `inFunctionThreshold`. A
threshold of `2147483647` disables the rewrite of SQL `IN` to `JOIN`.
|`2147483647`|
-## Setting the query context
-The query context parameters can be specified as a "context" object in the
[JSON API](../api-reference/sql-api.md) or as a [JDBC connection properties
object](../api-reference/sql-jdbc.md).
-See examples for each option below.
+## Set the query context
-### Example using JSON API
+You can configure query context parameters in the `context` object of the
[JSON API](../api-reference/sql-api.md) or as a [JDBC connection properties
object](../api-reference/sql-jdbc.md).
+
+The following example shows how to set a query context parameter using the
JSON API:
```
{
@@ -71,7 +73,7 @@ See examples for each option below.
}
```
-### Example using JDBC
+The following example shows how to set query context parameters using JDBC:
```java
String url =
"jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/";;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
