From 6da6017547223a3af7d69e2ca078ba4f0ad8f8d7 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 13:57:35 -0400
Subject: [PATCH 01/10] [DOCS]  SQL: Document `null` handling for aggregate
 functions

Relates to #74193.
---
 docs/reference/sql/functions/aggs.asciidoc | 61 ++++++++++++++--------
 1 file changed, 40 insertions(+), 21 deletions(-)

diff --git a/docs/reference/sql/functions/aggs.asciidoc b/docs/reference/sql/functions/aggs.asciidoc
index c90ec1c6f8b3e..1963e544f75e5 100644
--- a/docs/reference/sql/functions/aggs.asciidoc
+++ b/docs/reference/sql/functions/aggs.asciidoc
@@ -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
 
@@ -50,7 +51,8 @@ COUNT(expression) <1>
 
 <1> a field name, wildcard (`*`) or any numeric value
 
-*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 (count) of input values.
 
@@ -76,7 +78,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
 
@@ -105,7 +108,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.
 
@@ -137,7 +141,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.:
 
@@ -237,7 +241,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.:
 
@@ -330,7 +334,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
 
@@ -361,7 +366,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
 
@@ -387,7 +393,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
 
@@ -418,7 +425,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
 
@@ -452,7 +460,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
 
@@ -485,8 +494,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.
 
@@ -527,8 +538,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.
 
@@ -566,7 +579,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
 
@@ -600,7 +614,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
 
@@ -629,7 +644,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
 
@@ -658,7 +674,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
 
@@ -687,7 +704,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
 
@@ -717,7 +735,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
 

From c537efbee45c4bc31faff5e37260ee6c8dc7d63e Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 16:30:16 -0400
Subject: [PATCH 02/10] grouping functions

---
 docs/reference/sql/functions/grouping.asciidoc | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/reference/sql/functions/grouping.asciidoc b/docs/reference/sql/functions/grouping.asciidoc
index 1f5b67504838d..3d490e71d5b6f 100644
--- a/docs/reference/sql/functions/grouping.asciidoc
+++ b/docs/reference/sql/functions/grouping.asciidoc
@@ -23,10 +23,15 @@ HISTOGRAM(
 
 *Input*:
 
-<1> numeric expression (typically a field)
-<2> numeric interval
-<3> date/time expression (typically a field)
-<4> date/time <<sql-functions-datetime-interval, interval>>
+<1> numeric expression (typically a field). If this field contains only `null`
+values, the function returns `null`. Otherwise, the function ignores `null`
+values in this field.
+<2> numeric interval. If `null`, the function returns `null`.
+<3> date/time expression (typically a field). If this field contains only `null`
+values, the function returns `null`. Otherwise, the function ignores `null`
+values in this field.
+<4> date/time <<sql-functions-datetime-interval, interval>>. If `null`, the
+function returns `null`.
 
 *Output*: non-empty buckets or groups of the given expression divided according to the given interval
 

From 6e26f6ce0c9af8e1eaa6d3f45f224b81efef4358 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 17:11:36 -0400
Subject: [PATCH 03/10] date functions

---
 .../sql/functions/date-time.asciidoc          | 81 ++++++++++---------
 1 file changed, 43 insertions(+), 38 deletions(-)

diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc
index f0e1e59b1e665..5c481ecb7d3ce 100644
--- a/docs/reference/sql/functions/date-time.asciidoc
+++ b/docs/reference/sql/functions/date-time.asciidoc
@@ -256,10 +256,12 @@ DATE_ADD(
 
 *Input*:
 
-<1> string expression denoting the date/time unit to add to the date/datetime
-<2> integer expression denoting how many times the above unit should be added to/from the date/datetime,
-if a negative value is used it results to a subtraction from the date/datetime
-<3> date/datetime expression
+<1> string expression denoting the date/time unit to add to the date/datetime.
+If `null`, the function returns `null`.
+<2> integer expression denoting how many times the above unit should be added
+to/from the date/datetime, if a negative value is used it results to a
+subtraction from the date/datetime. If `null`, the function returns `null`.
+<3> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: datetime
 
@@ -332,9 +334,10 @@ DATE_DIFF(
 
 *Input*:
 
-<1> string expression denoting the date/time unit difference between the following two date/datetime expressions
-<2> start date/datetime expression
-<3> end date/datetime expression
+<1> string expression denoting the date/time unit difference between the
+following two date/datetime expressions. If `null`, the function returns `null`.
+<2> start date/datetime expression. If `null`, the function returns `null`.
+<3> end date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -417,8 +420,8 @@ DATE_PARSE(
 
 *Input*:
 
-<1> date expression as a string
-<2> parsing pattern
+<1> date expression as a string. If `null`, the function returns `null`.
+<2> parsing pattern. If `null`, the function returns `null`.
 
 *Output*: date
 
@@ -461,8 +464,8 @@ DATETIME_FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression
-<2> format pattern
+<1> date/datetime/time expression. If `null`, the function returns `null`.
+<2> format pattern. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -503,8 +506,8 @@ DATETIME_PARSE(
 
 *Input*:
 
-<1> datetime expression as a string
-<2> parsing pattern
+<1> datetime expression as a string. If `null`, the function returns `null`.
+<2> parsing pattern. If `null`, the function returns `null`.
 
 *Output*: datetime
 
@@ -553,8 +556,8 @@ TIME_PARSE(
 
 *Input*:
 
-<1> time expression as a string
-<2> parsing pattern
+<1> time expression as a string. If `null`, the function returns `null`.
+<2> parsing pattern. If `null`, the function returns `null`.
 
 *Output*: time
 
@@ -603,8 +606,9 @@ DATE_PART(
 
 *Input*:
 
-<1> string expression denoting the unit to extract from the date/datetime
-<2> date/datetime expression
+<1> string expression denoting the unit to extract from the date/datetime. If
+`null`, the function returns `null`.
+<2> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -691,8 +695,9 @@ DATE_TRUNC(
 
 *Input*:
 
-<1> string expression denoting the unit to which the date/datetime/interval should be truncated to
-<2> date/datetime/interval expression
+<1> string expression denoting the unit to which the date/datetime/interval
+should be truncated to. If `null`, the function returns `null`.
+<2> date/datetime/interval expression. If `null`, the function returns `null`.
 
 *Output*: datetime/interval
 
@@ -778,8 +783,8 @@ FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression
-<2> format pattern
+<1> date/datetime/time expression. If `null`, the function returns `null`.
+<2> format pattern. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -829,8 +834,8 @@ TO_CHAR(
 
 *Input*:
 
-<1> date/datetime/time expression
-<2> format pattern
+<1> date/datetime/time expression. If `null`, the function returns `null`.
+<2> format pattern. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -875,7 +880,7 @@ DAY_OF_MONTH(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -897,7 +902,7 @@ DAY_OF_WEEK(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -919,7 +924,7 @@ DAY_OF_YEAR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -941,7 +946,7 @@ DAY_NAME(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -963,7 +968,7 @@ HOUR_OF_DAY(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -985,7 +990,7 @@ ISO_DAY_OF_WEEK(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1008,7 +1013,7 @@ ISO_WEEK_OF_YEAR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1031,7 +1036,7 @@ MINUTE_OF_DAY(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1053,7 +1058,7 @@ MINUTE_OF_HOUR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1075,7 +1080,7 @@ MONTH(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1097,7 +1102,7 @@ MONTH_NAME(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -1149,7 +1154,7 @@ SECOND_OF_MINUTE(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1171,7 +1176,7 @@ QUARTER(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1223,7 +1228,7 @@ WEEK_OF_YEAR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1245,7 +1250,7 @@ YEAR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 

From 74f18b40c1f57cb084972896e979375f4bde8747 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 17:16:47 -0400
Subject: [PATCH 04/10] type conversion functions

---
 docs/reference/sql/functions/type-conversion.asciidoc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/reference/sql/functions/type-conversion.asciidoc b/docs/reference/sql/functions/type-conversion.asciidoc
index 2f4f44698a9fc..8ae46e776bf74 100644
--- a/docs/reference/sql/functions/type-conversion.asciidoc
+++ b/docs/reference/sql/functions/type-conversion.asciidoc
@@ -16,7 +16,7 @@ CAST(
  AS data_type) <2>
 ----
 
-<1> Expression to cast
+<1> Expression to cast. If `null`, the function returns `null`.
 <2> Target data type to cast to
 
 *Description*: Casts the result of the given expression to the target <<sql-data-types, data type>>.
@@ -55,7 +55,7 @@ CONVERT(
     data_type)  <2>
 ----
 
-<1> Expression to convert
+<1> Expression to convert. If `null`, the function returns `null`.
 <2> Target data type to convert to
 
 *Description*: Works exactly like <<sql-functions-type-conversion-cast>> with slightly different syntax.

From 729cd475d3e1144be5d8a3ceb612187d1cb783e4 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 20:35:33 -0400
Subject: [PATCH 05/10] math functions

---
 docs/reference/sql/functions/math.asciidoc | 60 +++++++++++-----------
 1 file changed, 30 insertions(+), 30 deletions(-)

diff --git a/docs/reference/sql/functions/math.asciidoc b/docs/reference/sql/functions/math.asciidoc
index 25b233d697e06..194d3f700c795 100644
--- a/docs/reference/sql/functions/math.asciidoc
+++ b/docs/reference/sql/functions/math.asciidoc
@@ -21,7 +21,7 @@ ABS(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: numeric
 
@@ -43,7 +43,7 @@ CBRT(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -65,7 +65,7 @@ CEIL(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: integer or long numeric value
 
@@ -107,7 +107,7 @@ EXP(numeric_exp) <1>
 
 *Input*:
 
-<1> float numeric expression
+<1> float numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -129,7 +129,7 @@ EXPM1(numeric_exp) <1>
 
 *Input*:
 
-<1> float numeric expression
+<1> float numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -151,7 +151,7 @@ FLOOR(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: integer or long numeric value
 
@@ -173,7 +173,7 @@ LOG(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -195,7 +195,7 @@ LOG10(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -239,8 +239,8 @@ POWER(
 
 *Input*:
 
-<1> numeric expression
-<2> integer expression
+<1> numeric expression. If `null`, the function returns `null`.
+<2> integer expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -267,7 +267,7 @@ RANDOM(seed) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -290,8 +290,8 @@ ROUND(
 ----
 *Input*:
 
-<1> numeric expression
-<2> integer expression; optional
+<1> numeric expression. If `null`, the function returns `null`.
+<2> integer expression; optional. If `null`, the function returns `null`.
 
 *Output*: numeric 
 
@@ -321,7 +321,7 @@ SIGN(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: [-1, 0, 1]
 
@@ -344,7 +344,7 @@ SQRT(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -367,8 +367,8 @@ TRUNCATE(
 ----
 *Input*:
 
-<1> numeric expression
-<2> integer expression; optional
+<1> numeric expression. If `null`, the function returns `null`.
+<2> integer expression; optional. If `null`, the function returns `null`.
 
 *Output*: numeric 
 
@@ -402,7 +402,7 @@ ACOS(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -424,7 +424,7 @@ ASIN(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -446,7 +446,7 @@ ATAN(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -470,8 +470,8 @@ ATAN2(
 
 *Input*:
 
-<1> numeric expression
-<2> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
+<2> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -493,7 +493,7 @@ COS(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -515,7 +515,7 @@ COSH(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -537,7 +537,7 @@ COT(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -559,7 +559,7 @@ DEGREES(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -582,7 +582,7 @@ RADIANS(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -605,7 +605,7 @@ SIN(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -627,7 +627,7 @@ SINH(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 
@@ -649,7 +649,7 @@ TAN(numeric_exp) <1>
 
 *Input*:
 
-<1> numeric expression
+<1> numeric expression. If `null`, the function returns `null`.
 
 *Output*: double numeric value
 

From 37734ec303dee368a26de824f9eae32a429840af Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Tue, 22 Jun 2021 20:47:49 -0400
Subject: [PATCH 06/10] geo functions

---
 docs/reference/sql/functions/geo.asciidoc | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/docs/reference/sql/functions/geo.asciidoc b/docs/reference/sql/functions/geo.asciidoc
index fe1c2f28bdf9a..4f4b0f8022931 100644
--- a/docs/reference/sql/functions/geo.asciidoc
+++ b/docs/reference/sql/functions/geo.asciidoc
@@ -35,7 +35,7 @@ ST_AsWKT(
 
 *Input*:
 
-<1> geometry
+<1> geometry. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -60,7 +60,8 @@ ST_WKTToSQL(
 
 *Input*:
 
-<1> string WKT representation of geometry
+<1> string WKT representation of geometry. If `null`, the function returns
+`null`.
 
 *Output*: geometry
 
@@ -86,7 +87,7 @@ ST_GeometryType(
 
 *Input*:
 
-<1> geometry
+<1> geometry. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -110,7 +111,7 @@ ST_X(
 
 *Input*:
 
-<1> geometry
+<1> geometry. If `null`, the function returns `null`.
 
 *Output*: double
 
@@ -134,7 +135,7 @@ ST_Y(
 
 *Input*:
 
-<1> geometry
+<1> geometry. If `null`, the function returns `null`.
 
 *Output*: double
 
@@ -158,7 +159,7 @@ ST_Z(
 
 *Input*:
 
-<1> geometry
+<1> geometry. If `null`, the function returns `null`.
 
 *Output*: double
 
@@ -183,8 +184,8 @@ ST_Distance(
 
 *Input*:
 
-<1> source geometry
-<2> target geometry
+<1> source geometry. If `null`, the function returns `null`.
+<2> target geometry. If `null`, the function returns `null`.
 
 *Output*: Double
 

From 1f9209ad0604b3b5f58fd40b47b8409ad0cbf670 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 23 Jun 2021 09:19:07 -0400
Subject: [PATCH 07/10] Remove date/time null statements. Other fixups

---
 docs/reference/sql/functions/aggs.asciidoc    | 11 ++----
 .../sql/functions/date-time.asciidoc          | 38 +++++++++----------
 .../reference/sql/functions/grouping.asciidoc |  2 +-
 3 files changed, 23 insertions(+), 28 deletions(-)

diff --git a/docs/reference/sql/functions/aggs.asciidoc b/docs/reference/sql/functions/aggs.asciidoc
index 1963e544f75e5..8e4976addcf76 100644
--- a/docs/reference/sql/functions/aggs.asciidoc
+++ b/docs/reference/sql/functions/aggs.asciidoc
@@ -49,17 +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. If this field contains only `null` values, the function
-returns `null`. Otherwise, the function ignores `null` values in this field.
+*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"]
 --------------------------------------------------
diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc
index 5c481ecb7d3ce..d857fa8900754 100644
--- a/docs/reference/sql/functions/date-time.asciidoc
+++ b/docs/reference/sql/functions/date-time.asciidoc
@@ -266,7 +266,7 @@ subtraction from the date/datetime. If `null`, the function returns `null`.
 *Output*: datetime
 
 *Description*: Add the given number of date/time units to a date/datetime. If the number of units is negative then it's subtracted from
-the date/datetime. If any of the three arguments is `null` a `null` is returned.
+the date/datetime.
 
 [WARNING]
 If the second argument is a long there is possibility of truncation since an integer value will be extracted and
@@ -343,7 +343,7 @@ following two date/datetime expressions. If `null`, the function returns `null`.
 
 *Description*: Subtract the second argument from the third argument and return their difference in multiples of the unit
 specified in the first argument. If the second argument (start) is greater than the third argument (end),
-then negative values are returned. If any of the three arguments is `null`, a `null` is returned.
+then negative values are returned.
 
 [cols="^,^"]
 |===
@@ -428,7 +428,6 @@ DATE_PARSE(
 *Description*: Returns a date by parsing the 1st argument using the format specified in the 2nd argument. The parsing
 format pattern used is the one from
 https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
-If any of the two arguments is `null` or an empty string, then `null` is returned.
 
 [NOTE]
 If the parsing pattern does not contain all valid date units (e.g. 'HH:mm:ss', 'dd-MM HH:mm:ss', etc.) an error is returned
@@ -472,7 +471,6 @@ DATETIME_FORMAT(
 *Description*: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting
 pattern used is the one from
 https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
-If any of the two arguments is `null` or the pattern is an empty string `null` is returned.
 
 [NOTE]
 If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units
@@ -514,7 +512,6 @@ DATETIME_PARSE(
 *Description*: Returns a datetime by parsing the 1st argument using the format specified in the 2nd argument. The parsing
 format pattern used is the one from
 https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
-If any of the two arguments is `null` or an empty string `null` is returned.
 
 
 [NOTE]
@@ -564,7 +561,6 @@ TIME_PARSE(
 *Description*: Returns a time by parsing the 1st argument using the format specified in the 2nd argument. The parsing
 format pattern used is the one from
 https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/time/format/DateTimeFormatter.html[`java.time.format.DateTimeFormatter`].
-If any of the two arguments is `null` or an empty string `null` is returned.
 
 [NOTE]
 If the parsing pattern contains only date units (e.g. 'dd/MM/yyyy') an error is returned
@@ -612,9 +608,9 @@ DATE_PART(
 
 *Output*: integer
 
-*Description*: Extract the specified unit from a date/datetime. If any of the two arguments is `null` a `null` is returned.
-It's similar to <<sql-functions-datetime-extract>> but with different names and aliases for the units and
-provides more options (e.g.: `TZOFFSET`).
+*Description*: Extract the specified unit from a date/datetime. It's similar to
+<<sql-functions-datetime-extract>> but with different names and aliases for the
+units and provides more options (e.g.: `TZOFFSET`).
 
 [cols="^,^"]
 |===
@@ -701,9 +697,11 @@ should be truncated to. If `null`, the function returns `null`.
 
 *Output*: datetime/interval
 
-*Description*: Truncate the date/datetime/interval to the specified unit by setting all fields that are less significant than the specified
-one to zero (or one, for day, day of week and month). If any of the two arguments is `null` a `null` is returned.
-If the first argument is `week` and the second argument is of `interval` type, an error is thrown since the `interval` data type doesn't support a `week` time unit.
+*Description*: Truncate the date/datetime/interval to the specified unit by
+setting all fields that are less significant than the specified one to zero (or
+one, for day, day of week and month). If the first argument is `week` and the
+second argument is of `interval` type, an error is thrown since the `interval`
+data type doesn't support a `week` time unit.
 
 [cols="^,^"]
 |===
@@ -789,10 +787,10 @@ FORMAT(
 *Output*: string
 
 *Description*: Returns the date/datetime/time as a string using the
-https://docs.microsoft.com/en-us/sql/t-sql/functions/format-transact-sql#arguments[format] specified in the 2nd argument. The formatting
-pattern used is the one from
-https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings[Microsoft SQL Server Format Specification].
-If any of the two arguments is `null` or the pattern is an empty string `null` is returned.
+https://docs.microsoft.com/en-us/sql/t-sql/functions/format-transact-sql#arguments[format]
+specified in the 2nd argument. The formatting pattern used is the one from
+https://docs.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings[Microsoft
+SQL Server Format Specification].
 
 [NOTE]
 If the 1st argument is of type `time`, then pattern specified by the 2nd argument cannot contain date related units
@@ -839,10 +837,10 @@ TO_CHAR(
 
 *Output*: string
 
-*Description*: Returns the date/datetime/time as a string using the format specified in the 2nd argument. The formatting
-pattern conforms to
-https://www.postgresql.org/docs/13/functions-formatting.html[PostgreSQL Template Patterns for Date/Time Formatting].
-If any of the two arguments is `null` or the pattern is an empty string `null` is returned.
+*Description*: Returns the date/datetime/time as a string using the format
+specified in the 2nd argument. The formatting pattern conforms to
+https://www.postgresql.org/docs/13/functions-formatting.html[PostgreSQL Template
+Patterns for Date/Time Formatting].
 
 [NOTE]
 If the 1st argument is of type `time`, then the pattern specified by the 2nd argument cannot contain date related units
diff --git a/docs/reference/sql/functions/grouping.asciidoc b/docs/reference/sql/functions/grouping.asciidoc
index 3d490e71d5b6f..b31637f140c69 100644
--- a/docs/reference/sql/functions/grouping.asciidoc
+++ b/docs/reference/sql/functions/grouping.asciidoc
@@ -43,7 +43,7 @@ bucket_key = Math.floor(value / interval) * interval
 ----
 
 [NOTE]
-The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <<search-aggregations-bucket-histogram-aggregation, histogram>> and  <<search-aggregations-bucket-datehistogram-aggregation, date histogram>>. Such behavior does not fit conceptually in SQL which treats all missing values as `NULL`; as such the histogram places all missing values in the `NULL` group.
+The histogram in SQL does *NOT* return empty buckets for missing intervals as the traditional <<search-aggregations-bucket-histogram-aggregation, histogram>> and  <<search-aggregations-bucket-datehistogram-aggregation, date histogram>>. Such behavior does not fit conceptually in SQL which treats all missing values as `null`; as such the histogram places all missing values in the `null` group.
 
 `Histogram` can be applied on either numeric fields:
 

From dcc58083f6455859da1c8d0eb8a3301e62a0b4b7 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 23 Jun 2021 09:20:42 -0400
Subject: [PATCH 08/10] Fix typo

---
 docs/reference/sql/functions/aggs.asciidoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/reference/sql/functions/aggs.asciidoc b/docs/reference/sql/functions/aggs.asciidoc
index 8e4976addcf76..1e44cfbee981b 100644
--- a/docs/reference/sql/functions/aggs.asciidoc
+++ b/docs/reference/sql/functions/aggs.asciidoc
@@ -51,7 +51,7 @@ COUNT(expression) <1>
 
 <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.
+ones. For `COUNT(<field_name>)`, `null` values are not considered.
 
 *Output*: numeric value
 

From 46b6efa992024f7e6914fb6bd52446ea04095a9f Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 23 Jun 2021 09:26:20 -0400
Subject: [PATCH 09/10] Note empty string handling for several date fns

---
 .../sql/functions/date-time.asciidoc          | 30 +++++++++++--------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc
index d857fa8900754..c9c9a395eab52 100644
--- a/docs/reference/sql/functions/date-time.asciidoc
+++ b/docs/reference/sql/functions/date-time.asciidoc
@@ -420,8 +420,9 @@ DATE_PARSE(
 
 *Input*:
 
-<1> date expression as a string. If `null`, the function returns `null`.
-<2> parsing pattern. If `null`, the function returns `null`.
+<1> date expression as a string. If `null` or an empty string, the function
+returns `null`.
+<2> parsing pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: date
 
@@ -463,8 +464,9 @@ DATETIME_FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null`, the function returns `null`.
-<2> format pattern. If `null`, the function returns `null`.
+<1> date/datetime/time expression. If `null` or an empty string, the function
+returns `null`.
+<2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string
 
@@ -504,8 +506,9 @@ DATETIME_PARSE(
 
 *Input*:
 
-<1> datetime expression as a string. If `null`, the function returns `null`.
-<2> parsing pattern. If `null`, the function returns `null`.
+<1> datetime expression as a string. If `null` or an empty string, the function
+returns `null`.
+<2> parsing pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: datetime
 
@@ -553,8 +556,9 @@ TIME_PARSE(
 
 *Input*:
 
-<1> time expression as a string. If `null`, the function returns `null`.
-<2> parsing pattern. If `null`, the function returns `null`.
+<1> time expression as a string. If `null` or an empty string, the function
+returns `null`.
+<2> parsing pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: time
 
@@ -781,8 +785,9 @@ FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null`, the function returns `null`.
-<2> format pattern. If `null`, the function returns `null`.
+<1> date/datetime/time expression. If `null` or an empty string, the function
+returns `null`.
+<2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string
 
@@ -832,8 +837,9 @@ TO_CHAR(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null`, the function returns `null`.
-<2> format pattern. If `null`, the function returns `null`.
+<1> date/datetime/time expression. If `null` or an empty string, the function
+returns `null`.
+<2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string
 

From 651b6fedf862afc3ed6197390ba9c03193befcc8 Mon Sep 17 00:00:00 2001
From: James Rodewig <40268737+jrodewig@users.noreply.github.com>
Date: Wed, 23 Jun 2021 09:45:10 -0400
Subject: [PATCH 10/10] Remove empty string note for date exp

---
 docs/reference/sql/functions/date-time.asciidoc | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/docs/reference/sql/functions/date-time.asciidoc b/docs/reference/sql/functions/date-time.asciidoc
index c9c9a395eab52..1770e73c92713 100644
--- a/docs/reference/sql/functions/date-time.asciidoc
+++ b/docs/reference/sql/functions/date-time.asciidoc
@@ -464,8 +464,7 @@ DATETIME_FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null` or an empty string, the function
-returns `null`.
+<1> date/datetime/time expression. If `null`, the function returns `null`.
 <2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string
@@ -785,8 +784,7 @@ FORMAT(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null` or an empty string, the function
-returns `null`.
+<1> date/datetime/time expression. If `null`, the function returns `null`.
 <2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string
@@ -837,8 +835,7 @@ TO_CHAR(
 
 *Input*:
 
-<1> date/datetime/time expression. If `null` or an empty string, the function
-returns `null`.
+<1> date/datetime/time expression. If `null`, the function returns `null`.
 <2> format pattern. If `null` or an empty string, the function returns `null`.
 
 *Output*: string