Skip to content

Commit 4bec6ca

Browse files
jrodewigjrodewig
authored
[DOCS] SQL: Document null handling for functions (#74444) (#74496)
Closes #74193.
1 parent ae96371 commit 4bec6ca

File tree

6 files changed

+156
-128
lines changed

6 files changed

+156
-128
lines changed

‎docs/reference/sql/functions/aggs.asciidoc‎

Lines changed: 41 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,8 @@ AVG(numeric_field) <1>
2121

2222
*Input*:
2323

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

2627
*Output*: `double` numeric value
2728

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

4950
*Input*:
5051

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

5356
*Output*: numeric value
5457

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

57-
In case of `COUNT(*)` or `COUNT(<literal>)`, _all_ values are considered (including `null` or missing ones).
58-
59-
In case of `COUNT(<field_name>)` `null` values are not considered.
60-
6160

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

7776
*Input*:
7877

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

8181
*Output*: numeric value
8282

@@ -105,7 +105,8 @@ COUNT(DISTINCT field_name) <1>
105105

106106
<1> a field name
107107

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

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

@@ -137,7 +138,7 @@ FIRST(
137138

138139
*Output*: same type as the input
139140

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

@@ -237,7 +238,7 @@ LAST(
237238

238239
*Output*: same type as the input
239240

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

@@ -330,7 +331,8 @@ MAX(field_name) <1>
330331

331332
*Input*:
332333

333-
<1> a numeric field
334+
<1> a numeric field. If this field contains only `null` values, the function
335+
returns `null`. Otherwise, the function ignores `null` values in this field.
334336

335337
*Output*: same type as the input
336338

@@ -361,7 +363,8 @@ MIN(field_name) <1>
361363

362364
*Input*:
363365

364-
<1> a numeric field
366+
<1> a numeric field. If this field contains only `null` values, the function
367+
returns `null`. Otherwise, the function ignores `null` values in this field.
365368

366369
*Output*: same type as the input
367370

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

388391
*Input*:
389392

390-
<1> a numeric field
393+
<1> a numeric field. If this field contains only `null` values, the function
394+
returns `null`. Otherwise, the function ignores `null` values in this field.
391395

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

@@ -418,7 +422,8 @@ KURTOSIS(field_name) <1>
418422

419423
*Input*:
420424

421-
<1> a numeric field
425+
<1> a numeric field. If this field contains only `null` values, the function
426+
returns `null`. Otherwise, the function ignores `null` values in this field.
422427

423428
*Output*: `double` numeric value
424429

@@ -452,7 +457,8 @@ MAD(field_name) <1>
452457

453458
*Input*:
454459

455-
<1> a numeric field
460+
<1> a numeric field. If this field contains only `null` values, the function
461+
returns `null`. Otherwise, the function ignores `null` values in this field.
456462

457463
*Output*: `double` numeric value
458464

@@ -485,8 +491,10 @@ PERCENTILE(
485491

486492
*Input*:
487493

488-
<1> a numeric field
489-
<2> a numeric expression (must be a constant and not based on a field)
494+
<1> a numeric field. If this field contains only `null` values, the function
495+
returns `null`. Otherwise, the function ignores `null` values in this field.
496+
<2> a numeric expression (must be a constant and not based on a field). If
497+
`null`, the function returns `null`.
490498
<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
491499
<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.
492500

@@ -527,8 +535,10 @@ PERCENTILE_RANK(
527535

528536
*Input*:
529537

530-
<1> a numeric field
531-
<2> a numeric expression (must be a constant and not based on a field)
538+
<1> a numeric field. If this field contains only `null` values, the function
539+
returns `null`. Otherwise, the function ignores `null` values in this field.
540+
<2> a numeric expression (must be a constant and not based on a field). If
541+
`null`, the function returns `null`.
532542
<3> optional string literal for the <<search-aggregations-metrics-percentile-aggregation-approximation,percentile algorithm>>. Possible values: `tdigest` or `hdr`. Defaults to `tdigest`.
533543
<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.
534544

@@ -566,7 +576,8 @@ SKEWNESS(field_name) <1>
566576

567577
*Input*:
568578

569-
<1> a numeric field
579+
<1> a numeric field. If this field contains only `null` values, the function
580+
returns `null`. Otherwise, the function ignores `null` values in this field.
570581

571582
*Output*: `double` numeric value
572583

@@ -600,7 +611,8 @@ STDDEV_POP(field_name) <1>
600611

601612
*Input*:
602613

603-
<1> a numeric field
614+
<1> a numeric field. If this field contains only `null` values, the function
615+
returns `null`. Otherwise, the function ignores `null` values in this field.
604616

605617
*Output*: `double` numeric value
606618

@@ -629,7 +641,8 @@ STDDEV_SAMP(field_name) <1>
629641

630642
*Input*:
631643

632-
<1> a numeric field
644+
<1> a numeric field. If this field contains only `null` values, the function
645+
returns `null`. Otherwise, the function ignores `null` values in this field.
633646

634647
*Output*: `double` numeric value
635648

@@ -658,7 +671,8 @@ SUM_OF_SQUARES(field_name) <1>
658671

659672
*Input*:
660673

661-
<1> a numeric field
674+
<1> a numeric field. If this field contains only `null` values, the function
675+
returns `null`. Otherwise, the function ignores `null` values in this field.
662676

663677
*Output*: `double` numeric value
664678

@@ -687,7 +701,8 @@ VAR_POP(field_name) <1>
687701

688702
*Input*:
689703

690-
<1> a numeric field
704+
<1> a numeric field. If this field contains only `null` values, the function
705+
returns `null`. Otherwise, the function ignores `null` values in this field.
691706

692707
*Output*: `double` numeric value
693708

@@ -717,7 +732,8 @@ VAR_SAMP(field_name) <1>
717732

718733
*Input*:
719734

720-
<1> a numeric field
735+
<1> a numeric field. If this field contains only `null` values, the function
736+
returns `null`. Otherwise, the function ignores `null` values in this field.
721737

722738
*Output*: `double` numeric value
723739

0 commit comments

Comments
 (0)