From f95447070ed2ccfa45c44075b2b5e94dfd175369 Mon Sep 17 00:00:00 2001 From: Victoria Lim Date: Thu, 21 Apr 2022 11:19:39 -0700 Subject: [PATCH] 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 +- ...ection-context.md => sql-query-context.md} | 47 +++++++++---------- website/sidebars.json | 2 +- 6 files changed, 35 insertions(+), 33 deletions(-) rename docs/querying/{sql-connection-context.md => sql-query-context.md} (76%) diff --git a/docs/querying/query-context.md b/docs/querying/query-context.md index b1ae3fc5930..158b59bd044 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:
- 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 running queries that have prohibitively long segment processing times. The optimal limit requires some trial and error; we recommend starting with 100. Users who submit a query that exceeds the limit of `maxNumericInFilters` should instead rewrite their queries to use strings in the `WHERE` clause instead of numbers. For example, `WHERE someString IN (‘123’, ‘456’)`. This value cannot exceed the set system configuration `druid.sql.planner.maxNumericInFilters`. This value is ignored if `druid.sql.planner.maxNumericInFilters` is not set explicitly.| |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 9ecbbb5378a..527324b4dc6 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 HLL sketch documentation. See also `COUNT(DISTINCT expr)`.|`0`| +|`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 sketch documentation. See also `COUNT(DISTINCT expr)`.|`0`| |`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 ca9fe93abfd..1c5a82f2ee6 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 df433454336..3e0dead7a2d 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" ---