Skip to content

[DOCS] SQL: Document null handling for functions #74444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jun 23, 2021
Merged

[DOCS] SQL: Document null handling for functions #74444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
6da6017
[DOCS] SQL: Document `null` handling for aggregate functions
jrodewig Jun 22, 2021
c537efb
grouping functions
jrodewig Jun 22, 2021
6e26f6c
date functions
jrodewig Jun 22, 2021
74f18b4
type conversion functions
jrodewig Jun 22, 2021
729cd47
math functions
jrodewig Jun 23, 2021
37734ec
geo functions
jrodewig Jun 23, 2021
1f9209a
Remove date/time null statements. Other fixups
jrodewig Jun 23, 2021
dcc5808
Fix typo
jrodewig Jun 23, 2021
46b6efa
Note empty string handling for several date fns
jrodewig Jun 23, 2021
651b6fe
Remove empty string note for date exp
jrodewig Jun 23, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 41 additions & 25 deletions docs/reference/sql/functions/aggs.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ AVG(numeric_field) <1>

*Input*:

<1> numeric field
<1> numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand All @@ -48,16 +49,14 @@ COUNT(expression) <1>

*Input*:

<1> a field name, wildcard (`*`) or any numeric value
<1> a field name, wildcard (`*`) or any numeric value. For `COUNT(*)` or
`COUNT(<literal>)`, all values are considered, including `null` or missing
ones. For `COUNT(<field_name>)`, `null` values are not considered.

*Output*: numeric value

*Description*: Returns the total number (count) of input values.

In case of `COUNT(*)` or `COUNT(<literal>)`, _all_ values are considered (including `null` or missing ones).

In case of `COUNT(<field_name>)` `null` values are not considered.


["source","sql",subs="attributes,macros"]
--------------------------------------------------
Expand All @@ -76,7 +75,8 @@ COUNT(ALL field_name) <1>

*Input*:

<1> a field name
<1> a field name. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: numeric value

Expand Down Expand Up @@ -105,7 +105,8 @@ COUNT(DISTINCT field_name) <1>

<1> a field name

*Output*: numeric value
*Output*: numeric value. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Description*: Returns the total number of _distinct non-null_ values in input values.

Expand Down Expand Up @@ -137,7 +138,7 @@ FIRST(

*Output*: same type as the input

*Description*: Returns the first **non-NULL** value (if such exists) of the `field_name` input column sorted by
*Description*: Returns the first non-`null` value (if such exists) of the `field_name` input column sorted by
the `ordering_field_name` column. If `ordering_field_name` is not provided, only the `field_name`
column is used for the sorting. E.g.:

Expand Down Expand Up @@ -237,7 +238,7 @@ LAST(

*Output*: same type as the input

*Description*: It's the inverse of <<sql-functions-aggs-first>>. Returns the last **non-NULL** value (if such exists) of the
*Description*: It's the inverse of <<sql-functions-aggs-first>>. Returns the last non-`null` value (if such exists) of the
`field_name` input column sorted descending by the `ordering_field_name` column. If `ordering_field_name` is not
provided, only the `field_name` column is used for the sorting. E.g.:

Expand Down Expand Up @@ -330,7 +331,8 @@ MAX(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: same type as the input

Expand Down Expand Up @@ -361,7 +363,8 @@ MIN(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: same type as the input

Expand All @@ -387,7 +390,8 @@ SUM(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `bigint` for integer input, `double` for floating points

Expand Down Expand Up @@ -418,7 +422,8 @@ KURTOSIS(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -452,7 +457,8 @@ MAD(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -485,8 +491,10 @@ PERCENTILE(

*Input*:

<1> a numeric field
<2> a numeric expression (must be a constant and not based on a field)
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.
<2> a numeric expression (must be a constant and not based on a field). If
`null`, the function returns `null`.
<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
<4> optional numeric literal that configures the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm.

Expand Down Expand Up @@ -527,8 +535,10 @@ PERCENTILE_RANK(

*Input*:

<1> a numeric field
<2> a numeric expression (must be a constant and not based on a field)
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.
<2> a numeric expression (must be a constant and not based on a field). If
`null`, the function returns `null`.
<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
<4> optional numeric literal that configures the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Configures `compression` for `tdigest` or `number_of_significant_value_digits` for `hdr`. The default is the same as that of the backing algorithm.

Expand Down Expand Up @@ -566,7 +576,8 @@ SKEWNESS(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -600,7 +611,8 @@ STDDEV_POP(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -629,7 +641,8 @@ STDDEV_SAMP(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -658,7 +671,8 @@ SUM_OF_SQUARES(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -687,7 +701,8 @@ VAR_POP(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down Expand Up @@ -717,7 +732,8 @@ VAR_SAMP(field_name) <1>

*Input*:

<1> a numeric field
<1> a numeric field. If this field contains only `null` values, the function
returns `null`. Otherwise, the function ignores `null` values in this field.

*Output*: `double` numeric value

Expand Down
Loading