[ESQL] Add SPACE function

docs/changelog/112350.yaml

@@ -0,0 +1,5 @@
+pr: 112350
+summary: "[ESQL] Add `SPACE` function"
+area: ES|QL
+type: enhancement
+issues: []

docs/reference/esql/functions/string-functions.asciidoc

@@ -19,6 +19,7 @@
 * <<esql-replace>>
 * <<esql-right>>
 * <<esql-rtrim>>
+* <<esql-space>>
 * <<esql-split>>
 * <<esql-starts_with>>
 * <<esql-substring>>
@@ -39,6 +40,7 @@ include::layout/repeat.asciidoc[]
 include::layout/replace.asciidoc[]
 include::layout/right.asciidoc[]
 include::layout/rtrim.asciidoc[]
+include::layout/space.asciidoc[]
 include::layout/split.asciidoc[]
 include::layout/starts_with.asciidoc[]
 include::layout/substring.asciidoc[]

x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec

@@ -72,6 +72,7 @@ double pi()
 "double signum(number:double|integer|long|unsigned_long)"
 "double sin(angle:double|integer|long|unsigned_long)"
 "double sinh(number:double|integer|long|unsigned_long)"
+"keyword space(number:integer)"
 "keyword split(string:keyword|text, delim:keyword|text)"
 "double sqrt(number:double|integer|long|unsigned_long)"
 "geo_point|cartesian_point st_centroid_agg(field:geo_point|cartesian_point)"
@@ -196,6 +197,7 @@ rtrim         |string                              |"keyword|text"
 signum        |number                              |"double|integer|long|unsigned_long"                                                                                               |"Numeric expression. If `null`, the function returns `null`."
 sin           |angle                               |"double|integer|long|unsigned_long"                                                                                               |An angle, in radians. If `null`, the function returns `null`.
 sinh          |number                              |"double|integer|long|unsigned_long"                                                                                               |Numeric expression. If `null`, the function returns `null`.
+space         |number                              |"integer"                                                                                                                         |Number of spaces in result.
 split         |[string, delim]                     |["keyword|text", "keyword|text"]                                                                                                  |[String expression. If `null`\, the function returns `null`., Delimiter. Only single byte delimiters are currently supported.]
 sqrt          |number                              |"double|integer|long|unsigned_long"                                                                                               |"Numeric expression. If `null`, the function returns `null`."
 st_centroid_ag|field                               |"geo_point|cartesian_point"                                                                                                       |[""]
@@ -320,6 +322,7 @@ rtrim         |Removes trailing whitespaces from a string.
 signum        |Returns the sign of the given number. It returns `-1` for negative numbers, `0` for `0` and `1` for positive numbers.
 sin           |Returns the {wikipedia}/Sine_and_cosine[sine] of an angle.
 sinh          |Returns the {wikipedia}/Hyperbolic_functions[hyperbolic sine] of a number.
+space         |Returns a string made of `number` spaces.
 split         |Split a single valued string into multiple strings.
 sqrt          |Returns the square root of a number. The input can be any numeric value, the return value is always a double. Square roots of negative numbers and infinities are null.
 st_centroid_ag|Calculate the spatial centroid over a field with spatial point geometry type.
@@ -446,6 +449,7 @@ rtrim         |"keyword|text"
 signum        |double                                                                                                                      |false                       |false           |false
 sin           |double                                                                                                                      |false                       |false           |false
 sinh          |double                                                                                                                      |false                       |false           |false
+space         |keyword                                                                                                                     |false                       |false           |false
 split         |keyword                                                                                                                     |[false, false]              |false           |false
 sqrt          |double                                                                                                                      |false                       |false           |false
 st_centroid_ag|"geo_point|cartesian_point"                                                                                                 |false                       |false           |true
@@ -508,5 +512,5 @@ countFunctions#[skip:-8.15.99]
 meta functions |  stats  a = count(*), b = count(*), c = count(*) |  mv_expand c;
 
 a:long | b:long | c:long
-115    | 115    | 115
+116    | 116    | 116
 ;

x-pack/plugin/esql/qa/testFixtures/src/main/resources/string.csv-spec

@@ -1595,4 +1595,100 @@ emp_no:integer | languages:integer | first_name:keyword
 10004 | 5 | ChirstianChirstianChirstianChirstianChirstian
 ;
 
+space
+required_capability: space
+// tag::space[]
+ROW message = CONCAT("Hello", SPACE(1), "World!");
+// end::space[]
 
+// tag::space-result[]
+message:keyword
+Hello World!
+// end::space-result[]
+;
+
+spaceLength
+required_capability: space
+ROW len = LENGTH(SPACE(12));
+
+len:integer
+12
+;
+
+spaceCalculated
+required_capability: space
+ROW inner_width = 20, title = "Title"
+| EVAL lspace = SPACE((inner_width-LENGTH(title))/2),
+       rspace = SPACE(inner_width-LENGTH(lspace)-LENGTH(title)),
+       centered_title = CONCAT("<",lspace,title,rspace,">")
+| KEEP inner_width, centered_title;
+
+inner_width:integer | centered_title:keyword
+20 | <       Title        >
+;
+
+spaceNumberFromIndex
+required_capability: space
+FROM employees
+| EVAL s = CONCAT("<",SPACE(languages),">")
+| WHERE emp_no < 10005
+| SORT emp_no
+| KEEP emp_no, languages, s;
+
+emp_no:integer | languages:integer | s:keyword
+10001 | 2 | <  >
+10002 | 5 | <     >
+10003 | 4 | <    >
+10004 | 5 | <     >
+;
+
+spaceZero
+required_capability: space
+ROW s = SPACE(0);
+
+s:keyword
+""
+;
+
+spaceNull
+required_capability: space
+ROW s = SPACE(null);
+
+s:keyword
+null
+;
+
+spaceNegative
+required_capability: space
+FROM employees | SORT emp_no | LIMIT 1 | EVAL s = SPACE(-LENGTH(first_name)) | KEEP s;
+
+warning:Line 1:51: evaluation of [SPACE(-LENGTH(first_name))] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 1:51: java.lang.IllegalArgumentException: Number parameter cannot be negative, found [-6]
+
+s:keyword
+null
+;
+
+spaceComplex
+required_capability: space
+ROW x = 1+2+3, y = null | EVAL z = x + 5 | LIMIT 1
+| EVAL xs = SPACE(x), xsc = CONCAT("<",xs,">"),
+       xn = SPACE(null),
+       xz = SPACE(z), xzc = CONCAT("<",xz,">"),
+       lxz = LENGTH(xz), lxs = LENGTH(xs), ltr = LENGTH(TRIM(xz))
+| DROP xs, xz;
+
+x:integer | y:null | z:integer | xsc:keyword | xn:keyword | xzc:keyword | lxz:integer | lxs:integer | ltr:integer
+6 | null |  11 | <      > | null | <           > | 11 | 6 | 0
+;
+
+spaceMV
+required_capability: space
+ROW mv = [1,2,3] | EVAL x = space(mv) | KEEP x;
+
+warning:Line 1:29: evaluation of [space(mv)] failed, treating result as null. Only first 20 failures recorded.
+warning:Line 1:29: java.lang.IllegalArgumentException: single-value function encountered multi-value
+
+x:keyword
+null
+;

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

@@ -274,7 +274,12 @@ public enum Cap {
         /**
          * Allow mixed numeric types in coalesce
          */
-        MIXED_NUMERIC_TYPES_IN_COALESCE;
+        MIXED_NUMERIC_TYPES_IN_COALESCE,
+
+        /**
+         * Support for requesting the "SPACE" function.
+         */
+        SPACE;
 
         private final boolean snapshotOnly;
         private final FeatureFlag featureFlag;