Docs for `split` (ESQL-1084)

This adds docs for the new `split` function.

docs/reference/esql/esql-functions.asciidoc

@@ -17,6 +17,7 @@ these functions:
 * <<esql-length>>
 * <<esql-pow>>
 * <<esql-round>>
+* <<esql-split>>
 * <<esql-starts_with>>
 * <<esql-substring>>
 
@@ -53,7 +54,7 @@ FROM employees
 === `CIDR_MATCH`
 
 Returns `true` if the provided IP is contained in one of the provided CIDR
-blocks. 
+blocks.
 
 `CIDR_MATCH` accepts two or more arguments. The first argument is the IP
 address of type `ip` (both IPv4 and IPv6 are supported). Subsequent arguments
@@ -83,7 +84,7 @@ is specified, the `yyyy-MM-dd'T'HH:mm:ss.SSSZ` format is used.
 
 [source,esql]
 ----
-FROM employees 
+FROM employees
 | PROJECT first_name, last_name, hire_date
 | EVAL hired = DATE_FORMAT(hire_date, "YYYY-MM-dd")
 ----
@@ -107,7 +108,7 @@ Returns a boolean that indicates whether its input is a finite number.
 
 [source,esql]
 ----
-ROW d = 1.0 
+ROW d = 1.0
 | EVAL s = IS_FINITE(d/0)
 ----
 
@@ -117,7 +118,7 @@ Returns a boolean that indicates whether its input is infinite.
 
 [source,esql]
 ----
-ROW d = 1.0 
+ROW d = 1.0
 | EVAL s = IS_INFINITE(d/0)
 ----
 
@@ -127,7 +128,7 @@ Returns a boolean that indicates whether its input is not a number.
 
 [source,esql]
 ----
-ROW d = 1.0 
+ROW d = 1.0
 | EVAL s = IS_NAN(d)
 ----
 
@@ -162,12 +163,12 @@ FROM employees
 
 [[esql-pow]]
 === `POW`
-Returns the the value of a base (first argument) raised to a power (second 
+Returns the the value of a base (first argument) raised to a power (second
 argument).
 
 [source,esql]
 ----
-ROW base = 2.0, exponent = 2.0 
+ROW base = 2.0, exponent = 2.0
 | EVAL s = POW(base, exponent)
 ----
 
@@ -184,9 +185,12 @@ FROM employees
 | EVAL height = ROUND(height * 3.281, 1)
 ----
 
+include::functions/split.asciidoc[]
+
+
 [[esql-starts_with]]
 === `STARTS_WITH`
-Returns a boolean that indicates whether a keyword string starts with another 
+Returns a boolean that indicates whether a keyword string starts with another
 string:
 
 [source,esql]
@@ -205,7 +209,7 @@ length. This example returns the first three characters of every last name:
 ----
 FROM employees
 | PROJECT last_name
-| EVAL ln_sub = SUBSTRING(last_name, 1, 3) 
+| EVAL ln_sub = SUBSTRING(last_name, 1, 3)
 ----
 
 A negative start position is interpreted as being relative to the end of the
@@ -215,7 +219,7 @@ string. This example returns the last three characters of of every last name:
 ----
 FROM employees
 | PROJECT last_name
-| EVAL ln_sub = SUBSTRING(last_name, -3, 3) 
+| EVAL ln_sub = SUBSTRING(last_name, -3, 3)
 ----
 
 If length is omitted, substring returns the remainder of the string. This
@@ -225,5 +229,5 @@ example returns all characters except for the first:
 ----
 FROM employees
 | PROJECT last_name
-| EVAL ln_sub = SUBSTRING(last_name, 2) 
+| EVAL ln_sub = SUBSTRING(last_name, 2)
 ----

docs/reference/esql/functions/split.asciidoc

@@ -0,0 +1,16 @@
+[[esql-split]]
+=== `SPLIT`
+Split a single valued string into multiple strings. For example:
+
+[source,esql]
+----
+include::{esql-specs}/string.csv-spec[tag=split]
+----
+
+Which splits `"foo;bar;baz;qux;quux;corge"` on `;` and returns an array:
+[source,esql]
+----
+include::{esql-specs}/string.csv-spec[tag=split-result]
+----
+
+WARNING: Only single byte delimiters are currently supported.

docs/reference/esql/index.asciidoc

@@ -9,7 +9,7 @@
 
 [partintro]
 --
-The {es} Query Language (ESQL) is a query language that enables the iterative 
+The {es} Query Language (ESQL) is a query language that enables the iterative
 exploration of data.
 
 An ESQL query consists of a series of commands, separated by pipes. Each query
@@ -97,7 +97,7 @@ POST /_esql?format=txt
 
 ESQL can be used in Discover to explore a data set, and in Lens to visualize it.
 First, enable the `enableTextBased` setting in *Advanced Settings*. Next, in
-Discover or Lens, from the data view dropdown, select *ESQL*. 
+Discover or Lens, from the data view dropdown, select *ESQL*.
 
 NOTE: ESQL queries in Discover and Lens are subject to the time range selected
 with the time filter.

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

@@ -1,15 +0,0 @@
-// This spec contains examples that are included in the docs that don't fit into any other file.
-// The docs can and do include examples from other files.
-
-from
-// tag::from[]
-FROM employees
-// end::from[]
-| PROJECT emp_no
-| SORT emp_no
-| LIMIT 1
-;
-
-emp_no:integer
-10001
-;

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

@@ -198,8 +198,14 @@ emp_no:integer | name:keyword
 ;
 
 split
-row words="foo;bar;baz;qux;quux;corge;grault;garply;waldo;fred;plugh;xyzzy;thud" | eval word = split(words, ";");
+// tag::split[]
+ROW words="foo;bar;baz;qux;quux;corge"
+| EVAL word = SPLIT(words, ";")
+// end::split[]
+;
 
 words:keyword | word:keyword
-foo;bar;baz;qux;quux;corge;grault;garply;waldo;fred;plugh;xyzzy;thud | [foo,bar,baz,qux,quux,corge,grault,garply,waldo,fred,plugh,xyzzy,thud]
+// tag::split-result[]
+foo;bar;baz;qux;quux;corge | [foo,bar,baz,qux,quux,corge]
+// end::split-result[]
 ;