This is an automated email from the ASF dual-hosted git repository.
lakshsingla pushed a commit to branch 29.0.0
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/29.0.0 by this push:
new bed658074e4 start process of deprecating non-sql compatible legacy
configurations (#15713) (#15895)
bed658074e4 is described below
commit bed658074e4b05949ca4f5693f86d77ac212db05
Author: Laksh Singla <[email protected]>
AuthorDate: Tue Feb 13 16:08:52 2024 +0530
start process of deprecating non-sql compatible legacy configurations
(#15713) (#15895)
Starting the process to officially deprecate non SQL compatible modes by
updating docs to aggressively call out that Druids non SQL compliant modes are
deprecated and will go away someday. There are no code or behavior changes at
this PR.
Co-authored-by: Clint Wylie <[email protected]>
---
docs/configuration/index.md | 13 +++++---
docs/design/segments.md | 2 +-
docs/querying/math-expr.md | 4 +--
docs/querying/sql-aggregations.md | 40 ++++++++++++------------
docs/querying/sql-array-functions.md | 4 +--
docs/querying/sql-data-types.md | 22 ++++++++-----
docs/querying/sql-functions.md | 4 +--
docs/querying/sql-multivalue-string-functions.md | 4 +--
8 files changed, 51 insertions(+), 42 deletions(-)
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 2e4d1f99722..b5fd567c9dc 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -803,14 +803,16 @@ Support for 64-bit floating point columns was released in
Druid 0.11.0, so if yo
|`druid.indexing.doubleStorage`|Set to "float" to use 32-bit double
representation for double columns.|double|
### SQL compatible null handling
+These configurations are deprecated and will be removed in a future release at
which point Druid will always have SQl compatible null handling.
Prior to version 0.13.0, Druid string columns treated `''` and `null` values
as interchangeable, and numeric columns were unable to represent `null` values,
coercing `null` to `0`. Druid 0.13.0 introduced a mode which enabled SQL
compatible null handling, allowing string columns to distinguish empty strings
from nulls, and numeric columns to contain null rows.
|Property|Description|Default|
|--------|-----------|-------|
-|`druid.generic.useDefaultValueForNull`|Set to `false` to store and query data
in SQL compatible mode. When set to `true` (legacy mode), `null` values will be
stored as `''` for string columns and `0` for numeric columns.|`false`|
-|`druid.generic.useThreeValueLogicForNativeFilters`|Set to `true` to use SQL
compatible three-value logic when processing native Druid filters when
`druid.generic.useDefaultValueForNull=false` and
`druid.expressions.useStrictBooleans=true`. When set to `false` Druid uses 2
value logic for filter processing, even when
`druid.generic.useDefaultValueForNull=false` and
`druid.expressions.useStrictBooleans=true`. See [boolean
handling](../querying/sql-data-types.md#boolean-logic) for more det [...]
-|`druid.generic.ignoreNullsForStringCardinality`|When set to `true`, `null`
values will be ignored for the built-in cardinality aggregator over string
columns. Set to `false` to include `null` values while estimating cardinality
of only string columns using the built-in cardinality aggregator. This setting
takes effect only when `druid.generic.useDefaultValueForNull` is set to `true`
and is ignored in SQL compatibility mode. Additionally, empty strings
(equivalent to null) are not counte [...]
+|`druid.generic.useDefaultValueForNull`|Set to `false` to store and query data
in SQL compatible mode. This configuration has been deprecated and will be
removed in a future release, taking on the `false` behavior. When set to `true`
(deprecated legacy mode), `null` values will be stored as `''` for string
columns and `0` for numeric columns.|`false`|
+|`druid.generic.useThreeValueLogicForNativeFilters`|Set to `true` to use SQL
compatible three-value logic when processing native Druid filters when
`druid.generic.useDefaultValueForNull=false` and
`druid.expressions.useStrictBooleans=true`. This configuration has been
deprecated and will be removed in a future release, taking on the `true`
behavior. When set to `false` Druid uses 2 value logic for filter processing,
even when `druid.generic.useDefaultValueForNull=false` and `druid.expres [...]
+|`druid.generic.ignoreNullsForStringCardinality`|When set to `true`, `null`
values will be ignored for the built-in cardinality aggregator over string
columns. Set to `false` to include `null` values while estimating cardinality
of only string columns using the built-in cardinality aggregator. This setting
takes effect only when `druid.generic.useDefaultValueForNull` is set to `true`
and is ignored in SQL compatibility mode. Additionally, empty strings
(equivalent to null) are not counte [...]
+
This mode does have a storage size and query performance cost, see [segment
documentation](../design/segments.md#handling-null-values) for more details.
### HTTP client
@@ -2196,8 +2198,9 @@ Supported query contexts:
|Key|Description|Default|
|---|-----------|-------|
-|`druid.expressions.useStrictBooleans`|Controls the behavior of Druid boolean
operators and functions, if set to `true` all boolean values are either `1` or
`0`. See [expression
documentation](../querying/math-expr.md#logical-operator-modes) for more
information.|true|
-|`druid.expressions.allowNestedArrays`|If enabled, Druid array expressions can
create nested arrays.|true|
+|`druid.expressions.useStrictBooleans`|Controls the behavior of Druid boolean
operators and functions, if set to `true` all boolean values are either `1` or
`0`. This configuration has been deprecated and will be removed in a future
release, taking on the `true` behavior. See [expression
documentation](../querying/math-expr.md#logical-operator-modes) for more
information.|true|
+|`druid.expressions.allowNestedArrays`|If enabled, Druid array expressions can
create nested arrays. This configuration has been deprecated and will be
removed in a future release, taking on the `true` behavior.|true|
+
### Router
#### Router process configs
diff --git a/docs/design/segments.md b/docs/design/segments.md
index 194520045aa..b6d3d16a3ae 100644
--- a/docs/design/segments.md
+++ b/docs/design/segments.md
@@ -84,7 +84,7 @@ For each row in the list of column data, there is only a
single bitmap that has
By default Druid stores segments in a SQL compatible null handling mode.
String columns always store the null value as id 0, the first position in the
value dictionary and an associated entry in the bitmap value indexes used to
filter null values. Numeric columns also store a null value bitmap index to
indicate the null valued rows, which is used to null check aggregations and for
filter matching null values.
-Druid also has a legacy mode which uses default values instead of nulls, which
was the default prior to Druid 28.0.0. This legacy mode can be enabled by
setting `druid.generic.useDefaultValueForNull=true`.
+Druid also has a legacy mode which uses default values instead of nulls, which
was the default prior to Druid 28.0.0. This legacy mode is deprecated and will
be removed in a future release, but can be enabled by setting
`druid.generic.useDefaultValueForNull=true`.
In legacy mode, Druid segments created _at ingestion time_ have the following
characteristics:
diff --git a/docs/querying/math-expr.md b/docs/querying/math-expr.md
index c8dfeaf253f..ee47fc7c2db 100644
--- a/docs/querying/math-expr.md
+++ b/docs/querying/math-expr.md
@@ -184,8 +184,8 @@ See javadoc of java.lang.Math for detailed explanation for
each function.
| array_ordinal(arr,long) | returns the array element at the 1 based index
supplied, or null for an out of range index |
| array_contains(arr,expr) | returns 1 if the array contains the element
specified by expr, or contains all elements specified by expr if expr is an
array, else 0 |
| array_overlap(arr1,arr2) | returns 1 if arr1 and arr2 have any elements in
common, else 0 |
-| array_offset_of(arr,expr) | returns the 0 based index of the first
occurrence of expr in the array, or `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (legacy mode) if no matching
elements exist in the array. |
-| array_ordinal_of(arr,expr) | returns the 1 based index of the first
occurrence of expr in the array, or `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (legacy mode) if no matching
elements exist in the array. |
+| array_offset_of(arr,expr) | returns the 0 based index of the first
occurrence of expr in the array, or `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode) if no
matching elements exist in the array. |
+| array_ordinal_of(arr,expr) | returns the 1 based index of the first
occurrence of expr in the array, or `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode) if no
matching elements exist in the array. |
| array_prepend(expr,arr) | adds expr to arr at the beginning, the resulting
array type determined by the type of the array |
| array_append(arr,expr) | appends expr to arr, the resulting array type
determined by the type of the first array |
| array_concat(arr1,arr2) | concatenates 2 arrays, the resulting array type
determined by the type of the first array |
diff --git a/docs/querying/sql-aggregations.md
b/docs/querying/sql-aggregations.md
index 5124b75c779..3f6e7466649 100644
--- a/docs/querying/sql-aggregations.md
+++ b/docs/querying/sql-aggregations.md
@@ -71,36 +71,36 @@ In the aggregation functions supported by Druid, only
`COUNT`, `ARRAY_AGG`, and
|--------|-----|-------|
|`COUNT(*)`|Counts the number of rows.|`0`|
|`COUNT([DISTINCT] expr)`|Counts the values of `expr`.<br /><br />By default,
using DISTINCT serves as an alias for `APPROX_COUNT_DISTINCT`
(`useApproximateCountDistinct=true`). The specific algorithm depends on the
value of
[`druid.sql.approxCountDistinct.function`](../configuration/index.md#sql). In
this mode, you can use strings, numbers, or prebuilt sketches. If counting
prebuilt sketches, the prebuilt sketch type must match the selected
algorithm.<br /><br />When `useApproximateCoun [...]
-|`SUM(expr)`|Sums numbers.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`MIN(expr)`|Takes the minimum of numbers.|`null` or `9223372036854775807`
(maximum LONG value) if `druid.generic.useDefaultValueForNull=true` (legacy
mode)|
-|`MAX(expr)`|Takes the maximum of numbers.|`null` or `-9223372036854775808`
(minimum LONG value) if `druid.generic.useDefaultValueForNull=true` (legacy
mode)|
-|`AVG(expr)`|Averages numbers.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
+|`SUM(expr)`|Sums numbers.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`MIN(expr)`|Takes the minimum of numbers.|`null` or `9223372036854775807`
(maximum LONG value) if `druid.generic.useDefaultValueForNull=true` (deprecated
legacy mode)|
+|`MAX(expr)`|Takes the maximum of numbers.|`null` or `-9223372036854775808`
(minimum LONG value) if `druid.generic.useDefaultValueForNull=true` (deprecated
legacy mode)|
+|`AVG(expr)`|Averages numbers.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
|`APPROX_COUNT_DISTINCT(expr)`|Counts distinct values of `expr` using an
approximate algorithm. The `expr` can be a regular column or a prebuilt sketch
column.<br /><br />The specific algorithm depends on the value of
[`druid.sql.approxCountDistinct.function`](../configuration/index.md#sql). By
default, this is `APPROX_COUNT_DISTINCT_BUILTIN`. If the [DataSketches
extension](../development/extensions-core/datasketches-extension.md) is loaded,
you can set it to `APPROX_COUNT_DISTINCT_DS_H [...]
|`APPROX_COUNT_DISTINCT_BUILTIN(expr)`|_Usage note:_ consider using
`APPROX_COUNT_DISTINCT_DS_HLL` instead, which offers better accuracy in many
cases.<br/><br/>Counts distinct values of `expr` using Druid's built-in
"cardinality" or "hyperUnique" aggregators, which implement a variant of
[HyperLogLog](http://algo.inria.fr/flajolet/Publications/FlFuGaMe07.pdf). The
`expr` can be a string, a number, or a prebuilt hyperUnique column. Results are
always approximate, regardless of the value [...]
|`APPROX_QUANTILE(expr, probability, [resolution])`|_Deprecated._ Use
`APPROX_QUANTILE_DS` instead, which provides a superior
distribution-independent algorithm with formal error
guarantees.<br/><br/>Computes approximate quantiles on numeric or
[approxHistogram](../development/extensions-core/approximate-histograms.md#approximate-histogram-aggregator)
expressions. `probability` should be between 0 and 1, exclusive. `resolution`
is the number of centroids to use for the computation. Highe [...]
|`APPROX_QUANTILE_FIXED_BUCKETS(expr, probability, numBuckets, lowerLimit,
upperLimit, [outlierHandlingMode])`|Computes approximate quantiles on numeric
or [fixed buckets
histogram](../development/extensions-core/approximate-histograms.md#fixed-buckets-histogram)
expressions. `probability` should be between 0 and 1, exclusive. The
`numBuckets`, `lowerLimit`, `upperLimit`, and `outlierHandlingMode` parameters
are described in the fixed buckets histogram documentation. Load the
[approximat [...]
|`BLOOM_FILTER(expr, numEntries)`|Computes a bloom filter from values produced
by `expr`, with `numEntries` maximum number of distinct values before false
positive rate increases. See [bloom filter
extension](../development/extensions-core/bloom-filter.md) documentation for
additional details.|Empty base64 encoded bloom filter STRING|
-|`VAR_POP(expr)`|Computes variance population of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`VAR_SAMP(expr)`|Computes variance sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`VARIANCE(expr)`|Computes variance sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`STDDEV_POP(expr)`|Computes standard deviation population of `expr`. See
[stats extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`STDDEV_SAMP(expr)`|Computes standard deviation sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`STDDEV(expr)`|Computes standard deviation sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`EARLIEST(expr, [maxBytesPerValue])`|Returns the earliest value of `expr`.<br
/>If `expr` comes from a relation with a timestamp column (like `__time` in a
Druid datasource), the "earliest" is taken from the row with the overall
earliest non-null value of the timestamp column.<br />If the earliest non-null
value of the timestamp column appears in multiple rows, the `expr` may be taken
from any of those rows. If `expr` does not come from a relation with a
timestamp, then it is simply the [...]
-|`EARLIEST_BY(expr, timestampExpr, [maxBytesPerValue])`|Returns the earliest
value of `expr`.<br />The earliest value of `expr` is taken from the row with
the overall earliest non-null value of `timestampExpr`. <br />If the earliest
non-null value of `timestampExpr` appears in multiple rows, the `expr` may be
taken from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of space is allocated for the aggregation. Strings
longer than this limit ar [...]
-|`LATEST(expr, [maxBytesPerValue])`|Returns the latest value of `expr`<br
/>The `expr` must come from a relation with a timestamp column (like `__time`
in a Druid datasource) and the "latest" is taken from the row with the overall
latest non-null value of the timestamp column.<br />If the latest non-null
value of the timestamp column appears in multiple rows, the `expr` may be taken
from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of spac [...]
-|`LATEST_BY(expr, timestampExpr, [maxBytesPerValue])`|Returns the latest value
of `expr`.<br />The latest value of `expr` is taken from the row with the
overall latest non-null value of `timestampExpr`.<br />If the overall latest
non-null value of `timestampExpr` appears in multiple rows, the `expr` may be
taken from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of space is allocated for the aggregation. Strings
longer than this limit are t [...]
-|`ANY_VALUE(expr, [maxBytesPerValue, [aggregateMultipleValues]])`|Returns any
value of `expr` including null. This aggregator can simplify and optimize the
performance by returning the first encountered value (including `null`).<br
/><br />If `expr` is a string or complex type `maxBytesPerValue` amount of
space is allocated for the aggregation. Strings longer than this limit are
truncated. The `maxBytesPerValue` parameter should be set as low as possible,
since high values will lead to w [...]
+|`VAR_POP(expr)`|Computes variance population of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`VAR_SAMP(expr)`|Computes variance sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`VARIANCE(expr)`|Computes variance sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`STDDEV_POP(expr)`|Computes standard deviation population of `expr`. See
[stats extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`STDDEV_SAMP(expr)`|Computes standard deviation sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`STDDEV(expr)`|Computes standard deviation sample of `expr`. See [stats
extension](../development/extensions-core/stats.md) documentation for
additional details.|`null` or `0` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`EARLIEST(expr, [maxBytesPerValue])`|Returns the earliest value of `expr`.<br
/>If `expr` comes from a relation with a timestamp column (like `__time` in a
Druid datasource), the "earliest" is taken from the row with the overall
earliest non-null value of the timestamp column.<br />If the earliest non-null
value of the timestamp column appears in multiple rows, the `expr` may be taken
from any of those rows. If `expr` does not come from a relation with a
timestamp, then it is simply the [...]
+|`EARLIEST_BY(expr, timestampExpr, [maxBytesPerValue])`|Returns the earliest
value of `expr`.<br />The earliest value of `expr` is taken from the row with
the overall earliest non-null value of `timestampExpr`. <br />If the earliest
non-null value of `timestampExpr` appears in multiple rows, the `expr` may be
taken from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of space is allocated for the aggregation. Strings
longer than this limit ar [...]
+|`LATEST(expr, [maxBytesPerValue])`|Returns the latest value of `expr`<br
/>The `expr` must come from a relation with a timestamp column (like `__time`
in a Druid datasource) and the "latest" is taken from the row with the overall
latest non-null value of the timestamp column.<br />If the latest non-null
value of the timestamp column appears in multiple rows, the `expr` may be taken
from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of spac [...]
+|`LATEST_BY(expr, timestampExpr, [maxBytesPerValue])`|Returns the latest value
of `expr`.<br />The latest value of `expr` is taken from the row with the
overall latest non-null value of `timestampExpr`.<br />If the overall latest
non-null value of `timestampExpr` appears in multiple rows, the `expr` may be
taken from any of those rows.<br /><br />If `expr` is a string or complex type
`maxBytesPerValue` amount of space is allocated for the aggregation. Strings
longer than this limit are t [...]
+|`ANY_VALUE(expr, [maxBytesPerValue, [aggregateMultipleValues]])`|Returns any
value of `expr` including null. This aggregator can simplify and optimize the
performance by returning the first encountered value (including `null`).<br
/><br />If `expr` is a string or complex type `maxBytesPerValue` amount of
space is allocated for the aggregation. Strings longer than this limit are
truncated. The `maxBytesPerValue` parameter should be set as low as possible,
since high values will lead to w [...]
|`GROUPING(expr, expr...)`|Returns a number to indicate which groupBy
dimension is included in a row, when using `GROUPING SETS`. Refer to
[additional documentation](aggregations.md#grouping-aggregator) on how to infer
this number.|N/A|
|`ARRAY_AGG(expr, [size])`|Collects all values of `expr` into an ARRAY,
including null values, with `size` in bytes limit on aggregation size (default
of 1024 bytes). If the aggregated array grows larger than the maximum size in
bytes, the query will fail. Use of `ORDER BY` within the `ARRAY_AGG` expression
is not currently supported, and the ordering of results within the output array
may vary depending on processing order.|`null`|
|`ARRAY_AGG(DISTINCT expr, [size])`|Collects all distinct values of `expr`
into an ARRAY, including null values, with `size` in bytes limit on aggregation
size (default of 1024 bytes) per aggregate. If the aggregated array grows
larger than the maximum size in bytes, the query will fail. Use of `ORDER BY`
within the `ARRAY_AGG` expression is not currently supported, and the ordering
of results will be based on the default for the element type.|`null`|
|`ARRAY_CONCAT_AGG(expr, [size])`|Concatenates all array `expr` into a single
ARRAY, with `size` in bytes limit on aggregation size (default of 1024 bytes).
Input `expr` _must_ be an array. Null `expr` will be ignored, but any null
values within an `expr` _will_ be included in the resulting array. If the
aggregated array grows larger than the maximum size in bytes, the query will
fail. Use of `ORDER BY` within the `ARRAY_CONCAT_AGG` expression is not
currently supported, and the orderi [...]
|`ARRAY_CONCAT_AGG(DISTINCT expr, [size])`|Concatenates all distinct values of
all array `expr` into a single ARRAY, with `size` in bytes limit on aggregation
size (default of 1024 bytes) per aggregate. Input `expr` _must_ be an array.
Null `expr` will be ignored, but any null values within an `expr` _will_ be
included in the resulting array. If the aggregated array grows larger than the
maximum size in bytes, the query will fail. Use of `ORDER BY` within the
`ARRAY_CONCAT_AGG` expressio [...]
-|`STRING_AGG([DISTINCT] expr, [separator, [size]])`|Collects all values (or
all distinct values) of `expr` into a single STRING, ignoring null values. Each
value is joined by an optional `separator`, which must be a literal STRING. If
the `separator` is not provided, strings are concatenated without a
separator.<br /><br />An optional `size` in bytes can be supplied to limit
aggregation size (default of 1024 bytes). If the aggregated string grows larger
than the maximum size in bytes, th [...]
-|`LISTAGG([DISTINCT] expr, [separator, [size]])`|Synonym for
`STRING_AGG`.|`null` or `''` if `druid.generic.useDefaultValueForNull=true`
(legacy mode)|
-|`BIT_AND(expr)`|Performs a bitwise AND operation on all input values.|`null`
or `0` if `druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`BIT_OR(expr)`|Performs a bitwise OR operation on all input values.|`null` or
`0` if `druid.generic.useDefaultValueForNull=true` (legacy mode)|
-|`BIT_XOR(expr)`|Performs a bitwise XOR operation on all input values.|`null`
or `0` if `druid.generic.useDefaultValueForNull=true` (legacy mode)|
+|`STRING_AGG([DISTINCT] expr, [separator, [size]])`|Collects all values (or
all distinct values) of `expr` into a single STRING, ignoring null values. Each
value is joined by an optional `separator`, which must be a literal STRING. If
the `separator` is not provided, strings are concatenated without a
separator.<br /><br />An optional `size` in bytes can be supplied to limit
aggregation size (default of 1024 bytes). If the aggregated string grows larger
than the maximum size in bytes, th [...]
+|`LISTAGG([DISTINCT] expr, [separator, [size]])`|Synonym for
`STRING_AGG`.|`null` or `''` if `druid.generic.useDefaultValueForNull=true`
(deprecated legacy mode)|
+|`BIT_AND(expr)`|Performs a bitwise AND operation on all input values.|`null`
or `0` if `druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`BIT_OR(expr)`|Performs a bitwise OR operation on all input values.|`null` or
`0` if `druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
+|`BIT_XOR(expr)`|Performs a bitwise XOR operation on all input values.|`null`
or `0` if `druid.generic.useDefaultValueForNull=true` (deprecated legacy mode)|
## Sketch functions
diff --git a/docs/querying/sql-array-functions.md
b/docs/querying/sql-array-functions.md
index 89607e9f085..203b0e0980e 100644
--- a/docs/querying/sql-array-functions.md
+++ b/docs/querying/sql-array-functions.md
@@ -54,8 +54,8 @@ The following table describes array functions. To learn more
about array aggrega
|`ARRAY_ORDINAL(arr, long)`|Returns the array element at the 1-based index
supplied, or null for an out of range index.|
|`ARRAY_CONTAINS(arr, expr)`|If `expr` is a scalar type, returns 1 if `arr`
contains `expr`. If `expr` is an array, returns 1 if `arr` contains all
elements of `expr`. Otherwise returns 0.|
|`ARRAY_OVERLAP(arr1, arr2)`|Returns 1 if `arr1` and `arr2` have any elements
in common, else 0.|
-|`ARRAY_OFFSET_OF(arr, expr)`|Returns the 0-based index of the first
occurrence of `expr` in the array. If no matching elements exist in the array,
returns `null` or `-1` if `druid.generic.useDefaultValueForNull=true` (legacy
mode).|
-|`ARRAY_ORDINAL_OF(arr, expr)`|Returns the 1-based index of the first
occurrence of `expr` in the array. If no matching elements exist in the array,
returns `null` or `-1` if `druid.generic.useDefaultValueForNull=true` (legacy
mode).|
+|`ARRAY_OFFSET_OF(arr, expr)`|Returns the 0-based index of the first
occurrence of `expr` in the array. If no matching elements exist in the array,
returns `null` or `-1` if `druid.generic.useDefaultValueForNull=true`
(deprecated legacy mode).|
+|`ARRAY_ORDINAL_OF(arr, expr)`|Returns the 1-based index of the first
occurrence of `expr` in the array. If no matching elements exist in the array,
returns `null` or `-1` if `druid.generic.useDefaultValueForNull=true`
(deprecated legacy mode).|
|`ARRAY_PREPEND(expr, arr)`|Adds `expr` to the beginning of `arr`, the
resulting array type determined by the type of `arr`.|
|`ARRAY_APPEND(arr, expr)`|Appends `expr` to `arr`, the resulting array type
determined by the type of `arr`.|
|`ARRAY_CONCAT(arr1, arr2)`|Concatenates `arr2` to `arr1`. The resulting array
type is determined by the type of `arr1`.|
diff --git a/docs/querying/sql-data-types.md b/docs/querying/sql-data-types.md
index 6ef91a6b9fd..2586149d0a0 100644
--- a/docs/querying/sql-data-types.md
+++ b/docs/querying/sql-data-types.md
@@ -66,14 +66,17 @@ The following table describes how Druid maps SQL types onto
native types when ru
|ARRAY|ARRAY|`NULL`|Druid native array types work as SQL arrays, and
multi-value strings can be converted to arrays. See [Arrays](#arrays) for more
information.|
|OTHER|COMPLEX|none|May represent various Druid column types such as
hyperUnique, approxHistogram, etc.|
-<sup>*</sup> The default value is `NULL` for all types, except in legacy mode
(`druid.generic.useDefaultValueForNull = true`) which initialize a default
value.
+<sup>*</sup>
+The default value is <code>NULL</code> for all types, except in the deprecated
legacy mode (<code>druid.generic.useDefaultValueForNull = true</code>) which
initialize a default value.
+<br /><br />
+For casts between two SQL types, the behavior depends on the runtime type:
Casts between two SQL types with the same Druid runtime type have no effect
other than the exceptions noted in the table.
Casts between two SQL types that have different Druid runtime types generate a
runtime cast in Druid.
If a value cannot be cast to the target type, as in `CAST('foo' AS BIGINT)`,
Druid a substitutes [NULL](#null-values).
-When `druid.generic.useDefaultValueForNull = true` (legacy mode), Druid
instead substitutes a default value, including when NULL values cast to
non-nullable types. For example, if `druid.generic.useDefaultValueForNull =
true`, a null VARCHAR cast to BIGINT is converted to a zero.
+When `druid.generic.useDefaultValueForNull = true` (deprecated legacy mode),
Druid instead substitutes a default value, including when NULL values cast to
non-nullable types. For example, if `druid.generic.useDefaultValueForNull =
true`, a null VARCHAR cast to BIGINT is converted to a zero.
## Arrays
@@ -146,13 +149,14 @@ affects both storage and querying, and must be set on all
Druid service types to
and query time. There is some overhead associated with the ability to handle
NULLs; see
the [segment internals](../design/segments.md#handling-null-values)
documentation for more details.
-When `druid.generic.useDefaultValueForNull = true` (legacy mode), Druid treats
NULLs and empty strings
+When `druid.generic.useDefaultValueForNull = true` (deprecated legacy mode),
Druid treats NULLs and empty strings
interchangeably, rather than according to the SQL standard. In this mode Druid
SQL only has partial support for NULLs.
-For example, the expressions `col IS NULL` and `col = ''` are equivalent, and
both evaluate to true if `col`
-contains an empty string. Similarly, the expression `COALESCE(col1, col2)`
returns `col2` if `col1` is an empty
-string. While the `COUNT(*)` aggregator counts all rows, the `COUNT(expr)`
aggregator counts the number of rows
-where `expr` is neither null nor the empty string. Numeric columns in this
mode are not nullable; any null or missing
-values are treated as zeroes. This was the default prior to Druid 28.0.0.
+For example, the expressions `col IS NULL` and `col = ''` are equivalent, and
both evaluate to true if `col` contains
+an empty string. Similarly, the expression `COALESCE(col1, col2)` returns
`col2` if `col1` is an empty string. While
+the `COUNT(*)` aggregator counts all rows, the `COUNT(expr)` aggregator counts
the number of rows where `expr` is
+neither null nor the empty string. Numeric columns in this mode are not
nullable; any null or missing values are
+treated as zeroes. This was the default prior to Druid 28.0.0, but will be
removed in a future release so that Druid
+always behaves in an SQL compatible manner.
## Boolean logic
@@ -165,6 +169,8 @@ and boolean expression evaluation. This behavior relies on
three settings:
If any of these settings is configured with a non-default value, Druid will
use two-valued logic for non-expression based filters. Expression based filters
are controlled independently with `druid.expressions.useStrictBooleans`, which
if set to false Druid will use two-valued logic for expressions.
+These configurations have been deprecated and will be removed in a future
release so that Druid always has SQL compliant behavior.
+
## Nested columns
Druid supports storing nested data structures in segments using the native
`COMPLEX<json>` type. See [Nested columns](./nested-columns.md) for more
information.
diff --git a/docs/querying/sql-functions.md b/docs/querying/sql-functions.md
index a5f1bbbbea7..2d0c51f6c12 100644
--- a/docs/querying/sql-functions.md
+++ b/docs/querying/sql-functions.md
@@ -181,7 +181,7 @@ Returns the array element at the 0-based index supplied, or
null for an out of r
**Function type:** [Array](./sql-array-functions.md)
-Returns the 0-based index of the first occurrence of `expr` in the array. If
no matching elements exist in the array, returns `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)..
+Returns the 0-based index of the first occurrence of `expr` in the array. If
no matching elements exist in the array, returns `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode).
## ARRAY_ORDINAL
@@ -196,7 +196,7 @@ Returns the array element at the 1-based index supplied, or
null for an out of r
**Function type:** [Array](./sql-array-functions.md)
-Returns the 1-based index of the first occurrence of `expr` in the array. If
no matching elements exist in the array, returns `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (legacy mode)..|
+Returns the 1-based index of the first occurrence of `expr` in the array. If
no matching elements exist in the array, returns `null` or `-1` if
`druid.generic.useDefaultValueForNull=true` (deprecated legacy mode).
## ARRAY_OVERLAP
diff --git a/docs/querying/sql-multivalue-string-functions.md
b/docs/querying/sql-multivalue-string-functions.md
index 8b4a17c7b5e..c2eaadc0976 100644
--- a/docs/querying/sql-multivalue-string-functions.md
+++ b/docs/querying/sql-multivalue-string-functions.md
@@ -55,8 +55,8 @@ All array references in the multi-value string function
documentation can refer
|`MV_ORDINAL(arr, long)`|Returns the array element at the 1-based index
supplied, or null for an out of range index.|
|`MV_CONTAINS(arr, expr)`|If `expr` is a scalar type, returns 1 if `arr`
contains `expr`. If `expr` is an array, returns 1 if `arr` contains all
elements of `expr`. Otherwise returns 0.|
|`MV_OVERLAP(arr1, arr2)`|Returns 1 if `arr1` and `arr2` have any elements in
common, else 0.|
-|`MV_OFFSET_OF(arr, expr)`|Returns the 0-based index of the first occurrence
of `expr` in the array. If no matching elements exist in the array, returns
`null` or -1 if `druid.generic.useDefaultValueForNull=true` (legacy mode).|
-|`MV_ORDINAL_OF(arr, expr)`|Returns the 1-based index of the first occurrence
of `expr` in the array. If no matching elements exist in the array, returns
`null` or `-1` if `druid.generic.useDefaultValueForNull=true` (legacy mode).|
+|`MV_OFFSET_OF(arr, expr)`|Returns the 0-based index of the first occurrence
of `expr` in the array. If no matching elements exist in the array, returns
`null` or -1 if `druid.generic.useDefaultValueForNull=true` (deprecated legacy
mode).|
+|`MV_ORDINAL_OF(arr, expr)`|Returns the 1-based index of the first occurrence
of `expr` in the array. If no matching elements exist in the array, returns
`null` or `-1` if `druid.generic.useDefaultValueForNull=true` (deprecated
legacy mode).|
|`MV_PREPEND(expr, arr)`|Adds `expr` to the beginning of `arr`, the resulting
array type determined by the type `arr`.|
|`MV_APPEND(arr, expr)`|Appends `expr` to `arr`, the resulting array type
determined by the type of `arr`.|
|`MV_CONCAT(arr1, arr2)`|Concatenates `arr2` to `arr1`. The resulting array
type is determined by the type of `arr1`.|
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
