You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@druid.apache.org by te...@apache.org on 2022/04/21 18:19:46 UTC
[druid] branch master updated: updated docs for sql query context (#12406)
This is an automated email from the ASF dual-hosted git repository.
techdocsmith 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 f95447070e updated docs for sql query context (#12406)
f95447070e is described below
commit f95447070ed2ccfa45c44075b2b5e94dfd175369
Author: Victoria Lim <vt...@users.noreply.github.com>
AuthorDate: Thu Apr 21 11:19:39 2022 -0700
updated docs for sql query context (#12406)
---
docs/querying/query-context.md | 5 +++
docs/querying/sql-aggregations.md | 4 +-
docs/querying/sql-api.md | 6 +--
docs/querying/sql-jdbc.md | 4 +-
...-connection-context.md => sql-query-context.md} | 47 ++++++++++------------
website/sidebars.json | 2 +-
6 files changed, 35 insertions(+), 33 deletions(-)
diff --git a/docs/querying/query-context.md b/docs/querying/query-context.md
index b1ae3fc593..158b59bd04 100644
--- a/docs/querying/query-context.md
+++ b/docs/querying/query-context.md
@@ -64,6 +64,11 @@ Unless otherwise noted, the following parameters apply to all query types.
|debug| `false` | Flag indicating whether to enable debugging outputs for the query. When set to false, no additional logs will be produced (logs produced will be entirely dependent on your logging level). When set to true, the following addition logs will be produced:<br />- Log the stack trace of the exception (if any) produced by the query |
|maxNumericInFilters|`-1`|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 property to a smaller value to prevent Druid from runni [...]
|inSubQueryThreshold|`2147483647`| Threshold for minimum number of values in an IN clause to convert the query to a JOIN operation on an inlined table rather than a predicate. A threshold of 0 forces usage of an inline table in all cases; a threshold of [Integer.MAX_VALUE] forces usage of OR in all cases. |
+
+## Druid SQL parameters
+
+See [SQL query context](sql-query-context.md) for query context parameters specific to Druid SQL queries.
+
## Parameters by query type
Some query types offer context parameters specific to that query type.
diff --git a/docs/querying/sql-aggregations.md b/docs/querying/sql-aggregations.md
index 9ecbbb5378..527324b4dc 100644
--- a/docs/querying/sql-aggregations.md
+++ b/docs/querying/sql-aggregations.md
@@ -114,7 +114,7 @@ Load the [DataSketches extension](../development/extensions-core/datasketches-ex
|Function|Notes|Default|
|--------|-----|-------|
-|`APPROX_COUNT_DISTINCT_DS_HLL(expr, [lgK, tgtHllType])`|Counts distinct values of `expr`, which can be a regular column or an [HLL sketch](../development/extensions-core/datasketches-hll.md) column. Results are always approximate, regardless of the value of [`useApproximateCountDistinct`](sql-connection-context.md). The `lgK` and `tgtHllType` parameters here are, like the equivalents in the [aggregator](../development/extensions-core/datasketches-hll.md#aggregators), described in the HL [...]
+|`APPROX_COUNT_DISTINCT_DS_HLL(expr, [lgK, tgtHllType])`|Counts distinct values of `expr`, which can be a regular column or an [HLL sketch](../development/extensions-core/datasketches-hll.md) column. Results are always approximate, regardless of the value of [`useApproximateCountDistinct`](sql-query-context.md). The `lgK` and `tgtHllType` parameters here are, like the equivalents in the [aggregator](../development/extensions-core/datasketches-hll.md#aggregators), described in the HLL ske [...]
|`DS_HLL(expr, [lgK, tgtHllType])`|Creates an [HLL sketch](../development/extensions-core/datasketches-hll.md) on the values of `expr`, which can be a regular column or a column containing HLL sketches. The `lgK` and `tgtHllType` parameters are described in the HLL sketch documentation.|`'0'` (STRING)|
@@ -124,7 +124,7 @@ Load the [DataSketches extension](../development/extensions-core/datasketches-ex
|Function|Notes|Default|
|--------|-----|-------|
-|`APPROX_COUNT_DISTINCT_DS_THETA(expr, [size])`|Counts distinct values of `expr`, which can be a regular column or a [Theta sketch](../development/extensions-core/datasketches-theta.md) column. Results are always approximate, regardless of the value of [`useApproximateCountDistinct`](sql-connection-context.md). The `size` parameter is described in the Theta sketch documentation. See also `COUNT(DISTINCT expr)`.|`0`|
+|`APPROX_COUNT_DISTINCT_DS_THETA(expr, [size])`|Counts distinct values of `expr`, which can be a regular column or a [Theta sketch](../development/extensions-core/datasketches-theta.md) column. Results are always approximate, regardless of the value of [`useApproximateCountDistinct`](sql-query-context.md). The `size` parameter is described in the Theta sketch documentation. See also `COUNT(DISTINCT expr)`.|`0`|
|`DS_THETA(expr, [size])`|Creates a [Theta sketch](../development/extensions-core/datasketches-theta.md) on the values of `expr`, which can be a regular column or a column containing Theta sketches. The `size` parameter is described in the Theta sketch documentation.|`'0.0'` (STRING)|
diff --git a/docs/querying/sql-api.md b/docs/querying/sql-api.md
index ca9fe93abf..1c5a82f2ee 100644
--- a/docs/querying/sql-api.md
+++ b/docs/querying/sql-api.md
@@ -50,7 +50,7 @@ Submit your query as the value of a "query" field in the JSON object within the
|`header`|Whether or not to include a header row for the query result. See [Responses](#responses) for details.|`false`|
|`typesHeader`|Whether or not to include type information in the header. Can only be set when `header` is also `true`. See [Responses](#responses) for details.|`false`|
|`sqlTypesHeader`|Whether or not to include SQL type information in the header. Can only be set when `header` is also `true`. See [Responses](#responses) for details.|`false`|
-|`context`|JSON object containing [connection context parameters](sql-connection-context.md).|`{}` (empty)|
+|`context`|JSON object containing [SQL query context parameters](sql-query-context.md).|`{}` (empty)|
|`parameters`|List of query parameters for parameterized queries. Each parameter in the list should be a JSON object like `{"type": "VARCHAR", "value": "foo"}`. The type should be a SQL type; see [Data types](sql-data-types.md) for a list of supported SQL types.|`[]` (empty)|
You can use _curl_ to send SQL queries from the command-line:
@@ -63,7 +63,7 @@ $ curl -XPOST -H'Content-Type: application/json' http://ROUTER:8888/druid/v2/sql
[{"TheCount":24433}]
```
-There are a variety of [connection context parameters](sql-connection-context.md) you can provide by adding a "context" map,
+There are a variety of [SQL query context parameters](sql-query-context.md) you can provide by adding a "context" map,
like:
```json
@@ -140,7 +140,7 @@ understands the `typesHeader` and `sqlTypesHeader` parameters. This HTTP respons
whether `typesHeader` or `sqlTypesHeader` are set or not.
Druid returns the SQL query identifier in the `X-Druid-SQL-Query-Id` HTTP header.
-This query id will be assigned the value of `sqlQueryId` from the [connection context parameters](sql-connection-context.md)
+This query id will be assigned the value of `sqlQueryId` from the [query context parameters](sql-query-context.md)
if specified, else Druid will generate a SQL query id for you.
#### Errors
diff --git a/docs/querying/sql-jdbc.md b/docs/querying/sql-jdbc.md
index df43345433..3e0dead7a2 100644
--- a/docs/querying/sql-jdbc.md
+++ b/docs/querying/sql-jdbc.md
@@ -1,7 +1,7 @@
---
id: sql-jdbc
-title: "SQL JDBC Driver API"
-sidebar_label: "JDBC Driver API"
+title: "SQL JDBC driver API"
+sidebar_label: "JDBC driver API"
---
<!--
diff --git a/docs/querying/sql-connection-context.md b/docs/querying/sql-query-context.md
similarity index 76%
rename from docs/querying/sql-connection-context.md
rename to docs/querying/sql-query-context.md
index dc6d7faaf1..59b2f74a95 100644
--- a/docs/querying/sql-connection-context.md
+++ b/docs/querying/sql-query-context.md
@@ -1,7 +1,7 @@
---
-id: sql-connection-context
-title: "SQL connection context"
-sidebar_label: "SQL connection context"
+id: sql-query-context
+title: "SQL query context"
+sidebar_label: "SQL query context"
---
<!--
@@ -26,14 +26,27 @@ sidebar_label: "SQL connection context"
> Apache Druid supports two query languages: Druid SQL and [native queries](querying.md).
> This document describes the SQL language.
-Druid SQL supports setting connection parameters on the client, which affect SQL planning.
-All other context parameters you provide will be attached to Druid queries and can affect how they run.
-See [Query context](query-context.md) for details on the possible options.
+Druid supports query context parameters which affect SQL planning.
+See [Query context](query-context.md) for general query context parameters for all query types.
-The connection context can be specified as a "context" object in the [JSON API](sql-api.md) or as a JDBC connection properties object.
+## SQL query context parameters
+
+Configure Druid SQL query planning using the parameters in the table below.
+
+|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 (default: 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)|
+
+## Setting the query context
+The query context parameters can be specified as a "context" object in the [JSON API](sql-api.md) or as a [JDBC connection properties object](sql-jdbc.md).
See examples for each option below.
-## Example using JSON API
+### Example using JSON API
```
{
@@ -44,7 +57,7 @@ See examples for each option below.
}
```
-## Example using JDBC
+### Example using JDBC
```java
String url = "jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/";
@@ -59,19 +72,3 @@ try (Connection connection = DriverManager.getConnection(url, connectionProperti
}
```
-## Connection context parameters
-
-Configure Druid SQL query planning using the parameters in the table below.
-
-Note that to specify an unique identifier for SQL query, use `sqlQueryId` instead of `queryId`, described in [Query context](query-context.md).
-Setting `queryId` for a SQL request has no effect, all native queries underlying SQL will use an auto-generated `queryId`.
-
-|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.|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 (default: 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)|
-
diff --git a/website/sidebars.json b/website/sidebars.json
index f9e16c60bd..3389e3e19c 100644
--- a/website/sidebars.json
+++ b/website/sidebars.json
@@ -109,7 +109,7 @@
"ids": [
"querying/sql-api",
"querying/sql-jdbc",
- "querying/sql-connection-context"
+ "querying/sql-query-context"
]
},
{
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org