[DOCS] SQL: Document null handing for string functions (#74201) (#7…

…4208)
elastic · Jun 16, 2021 · 25d92bb · 25d92bb
1 parent e8c94ed
commit 25d92bb
Showing 1 changed file with 36 additions and 34 deletions.
diff --git a/docs/reference/sql/functions/string.asciidoc b/docs/reference/sql/functions/string.asciidoc
@@ -16,7 +16,7 @@ ASCII(string_exp) <1>
 
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -37,7 +37,7 @@ BIT_LENGTH(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -58,7 +58,7 @@ CHAR(code) <1>
 --------------------------------------------------
 *Input*:
 
-<1> integer expression
+<1> integer expression. If `null` or negative, the function returns `null`.
 
 *Output*: string
 
@@ -79,7 +79,7 @@ CHAR_LENGTH(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -107,7 +107,7 @@ CONCAT(
 
 *Output*: string
 
-*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. `NULL` input strings are treated as empty strings.
+*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. `null` input strings are treated as empty strings.
 
 [source, sql]
 --------------------------------------------------
@@ -128,10 +128,10 @@ INSERT(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> integer expression
-<3> integer expression
-<4> string expression
+<1> string expression. If `null`, the function returns `null`.
+<2> integer expression. If `null`, the function returns `null`.
+<3> integer expression. If `null`, the function returns `null`.
+<4> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -152,7 +152,7 @@ LCASE(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -175,8 +175,9 @@ LEFT(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> integer expression
+<1> string expression. If `null`, the function returns `null`.
+<2> integer expression. If `null`, the function returns `null`. If `0` or
+negative, the function returns an empty string.
 
 *Output*: string
 
@@ -197,7 +198,7 @@ LENGTH(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -228,7 +229,7 @@ LOCATE(
 
 *Output*: integer
 
-*Description*: Returns the starting position of the first occurrence of `pattern` within `source`. The optional `start` specifies the character position to start the search with. The first character position in `source` is indicated by the value 1. Not specifying `start` or specifying it as `NULL`, any negative value, 0 or 1, starts the search at the first character position. If `pattern` is not found within `source`, the value 0 is returned.
+*Description*: Returns the starting position of the first occurrence of `pattern` within `source`. The optional `start` specifies the character position to start the search with. The first character position in `source` is indicated by the value 1. Not specifying `start` or specifying it as `null`, any negative value, 0 or 1, starts the search at the first character position. If `pattern` is not found within `source`, the value 0 is returned.
 
 [source, sql]
 --------------------------------------------------
@@ -250,7 +251,7 @@ LTRIM(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -271,7 +272,7 @@ OCTET_LENGTH(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -294,8 +295,8 @@ POSITION(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> string expression
+<1> string expression. If `null`, the function returns `null`.
+<2> string expression. If `null`, the function returns `null`.
 
 *Output*: integer
 
@@ -318,8 +319,8 @@ REPEAT(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> integer expression
+<1> string expression. If `null`, the function returns `null`.
+<2> integer expression. If `0`, negative, or `null`, the function returns `null`.
 
 *Output*: string
 
@@ -343,9 +344,9 @@ REPLACE(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> string expression
-<3> string expression
+<1> string expression. If `null`, the function returns `null`.
+<2> string expression. If `null`, the function returns `null`.
+<3> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -368,8 +369,9 @@ RIGHT(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> integer expression
+<1> string expression. If `null`, the function returns `null`.
+<2> integer expression. If `null`, the function returns `null`. If `0` or
+negative, the function returns an empty string.
 
 *Output*: string
 
@@ -390,7 +392,7 @@ RTRIM(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -411,7 +413,7 @@ SPACE(count) <1>
 --------------------------------------------------
 *Input*:
 
-<1> integer expression
+<1> integer expression. If `null` or negative, the function returns `null`.
 
 *Output*: string
 
@@ -434,8 +436,8 @@ STARTS_WITH(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> string expression
+<1> string expression. If `null`, the function returns `null`.
+<2> string expression. If `null`, the function returns `null`.
 
 *Output*: boolean value
 
@@ -465,9 +467,9 @@ SUBSTRING(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> integer expression
-<3> integer expression
+<1> string expression. If `null`, the function returns `null`.
+<2> integer expression. If `null`, the function returns `null`.
+<3> integer expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -487,7 +489,7 @@ TRIM(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: string
 
@@ -508,7 +510,7 @@ UCASE(string_exp) <1>
 --------------------------------------------------
 *Input*:
 
-<1> string expression
+<1> string expression. If `null`, the function returns `null`.
 
 *Output*: string