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

Closes #74193.

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
 
@@ -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"]
 --------------------------------------------------
@@ -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
 
@@ -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.
 
@@ -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.:
 
@@ -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.:
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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.
 
@@ -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.
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 

docs/reference/sql/functions/date-time.asciidoc

@@ -256,15 +256,17 @@ 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
 
 *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
@@ -332,15 +334,16 @@ 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
 
 *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="^,^"]
 |===
@@ -417,15 +420,15 @@ DATE_PARSE(
 
 *Input*:
 
-<1> date expression as a string
-<2> parsing pattern
+<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
 
 *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
@@ -461,15 +464,14 @@ 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` or an empty string, the function returns `null`.
 
 *Output*: string
 
 *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
@@ -503,15 +505,15 @@ DATETIME_PARSE(
 
 *Input*:
 
-<1> datetime expression as a string
-<2> parsing pattern
+<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
 
 *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]
@@ -553,15 +555,15 @@ TIME_PARSE(
 
 *Input*:
 
-<1> time expression as a string
-<2> parsing pattern
+<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
 
 *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
@@ -603,14 +605,15 @@ 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
 
-*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="^,^"]
 |===
@@ -691,14 +694,17 @@ 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
 
-*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="^,^"]
 |===
@@ -778,16 +784,16 @@ 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` or an empty string, the function returns `null`.
 
 *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
@@ -829,15 +835,15 @@ 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` or an empty string, the function returns `null`.
 
 *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
@@ -875,7 +881,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 +903,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 +925,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 +947,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 +969,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 +991,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 +1014,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 +1037,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 +1059,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 +1081,7 @@ MONTH(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1097,7 +1103,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 +1155,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 +1177,7 @@ QUARTER(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -1223,7 +1229,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 +1251,7 @@ YEAR(datetime_exp) <1>
 
 *Input*:
 
-<1> date/datetime expression
+<1> date/datetime expression. If `null`, the function returns `null`.
 
 *Output*: integer
 

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
 

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
 
@@ -38,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:
 

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
 

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.