From 30a32040d30d09fdc8dbc1a5e80f6d73f915a84f Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Wed, 25 Mar 2020 12:23:59 -0400
Subject: [PATCH] [DOCS] EQL: Document `substring` function (#53867)

Adds documentation for the EQL `substring` function.

Supporting changes:

* Creates a new "EQL function reference" page
* Updates the title of the "EQL syntax reference" page for consistency
* Adds a brief "Functions" section to the EQL syntax docs
* Updates EQL limitations docs to state that only array functions are
  unsupported
---
 docs/reference/eql/functions.asciidoc   | 66 +++++++++++++++++++++++++
 docs/reference/eql/index.asciidoc       |  2 +
 docs/reference/eql/limitations.asciidoc |  5 +-
 docs/reference/eql/syntax.asciidoc      | 12 +++++
 4 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/eql/functions.asciidoc

diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc
new file mode 100644
index 00000000000..cc5fbba57e4
--- /dev/null
+++ b/docs/reference/eql/functions.asciidoc
@@ -0,0 +1,66 @@
+[[eql-function-ref]]
+== EQL function reference
+++++
+<titleabbrev>Function reference</titleabbrev>
+++++
+
+experimental::[]
+
+{es} supports the following EQL functions:
+
+* <<eql-fn-substring>>
+
+[discrete]
+[[eql-fn-substring]]
+=== `substring`
+
+Extracts a substring from a source string at provided start and end positions.
+
+If no end position is provided, the function extracts the remaining string.
+
+[%collapsible]
+====
+*Example*
+[source,eql]
+----
+substring("start regsvr32.exe", 6)        // returns "regsvr32.exe"
+substring("start regsvr32.exe", 0, 5)     // returns "start"
+substring("start regsvr32.exe", 6, 14)    // returns "regsvr32"
+substring("start regsvr32.exe", -4)       // returns ".exe"
+substring("start regsvr32.exe", -4, -1)   // returns ".ex"
+----
+
+*Syntax*
+
+[source,txt]
+----
+substring(<source>, <start_pos>[, <end_pos>])
+----
+
+*Parameters*
+
+`<source>`::
+(Required, string)
+Source string.
+
+`<start_pos>`::
++
+--
+(Required, integer)
+Starting position for extraction.
+
+If this position is higher than the `<end_pos>` position or the length of the
+`<source>` string, the function returns an empty string.
+
+Positions are zero-indexed. Negative offsets are supported.
+--
+
+`<end_pos>`::
+(Optional, integer)
+Exclusive end position for extraction. If this position is not provided, the
+function returns the remaining string.
++
+Positions are zero-indexed. Negative offsets are supported.
+
+*Returns:* string
+====
\ No newline at end of file
diff --git a/docs/reference/eql/index.asciidoc b/docs/reference/eql/index.asciidoc
index 328f40a36a5..f9168b861c9 100644
--- a/docs/reference/eql/index.asciidoc
+++ b/docs/reference/eql/index.asciidoc
@@ -32,9 +32,11 @@ Consider using EQL if you:
 * <<eql-requirements>>
 * <<eql-search>>
 * <<eql-syntax>>
+* <<eql-function-ref>>
 * <<eql-limitations>>
 
 include::requirements.asciidoc[]
 include::search.asciidoc[]
 include::syntax.asciidoc[]
+include::functions.asciidoc[]
 include::limitations.asciidoc[]
diff --git a/docs/reference/eql/limitations.asciidoc b/docs/reference/eql/limitations.asciidoc
index 5e6cc74c319..dc7a211d8bd 100644
--- a/docs/reference/eql/limitations.asciidoc
+++ b/docs/reference/eql/limitations.asciidoc
@@ -15,7 +15,10 @@ experimental::[]
 {es} supports a subset of {eql-ref}/index.html[EQL syntax]. {es} cannot run EQL
 queries that contain:
 
-* {eql-ref}/functions.html[Functions]
+* Array functions:
+** {eql-ref}/functions.html#arrayContains[`arrayContains`]
+** {eql-ref}/functions.html#arrayCount[`arrayCount`]
+** {eql-ref}/functions.html#arraySearch[`arraySearch`]
 
 * {eql-ref}/joins.html[Joins]
 
diff --git a/docs/reference/eql/syntax.asciidoc b/docs/reference/eql/syntax.asciidoc
index 9beb9598bb9..a3827cfc58a 100644
--- a/docs/reference/eql/syntax.asciidoc
+++ b/docs/reference/eql/syntax.asciidoc
@@ -2,6 +2,9 @@
 [testenv="basic"]
 [[eql-syntax]]
 == EQL syntax reference
+++++
+<titleabbrev>Syntax reference</titleabbrev>
+++++
 
 experimental::[]
 
@@ -283,3 +286,12 @@ dots (`.`), hyphens (`-`), or spaces, must be escaped using backticks (+++`+++).
 `my-field`
 `my field`
 ----
+
+[discrete]
+[[eql-functions]]
+=== Functions
+
+{es} supports several of EQL's built-in functions. You can use these functions
+to convert data types, perform math, manipulate strings, and more.
+
+For a list of supported functions, see <<eql-function-ref>>.
\ No newline at end of file