From 4982b720ef1053053a937ddd340cfb190a4df6f3 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Wed, 1 Apr 2020 11:35:36 -0400
Subject: [PATCH] [DOCS] EQL: Document `length` function (#54225)

---
 docs/reference/eql/functions.asciidoc | 55 ++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 2 deletions(-)

diff --git a/docs/reference/eql/functions.asciidoc b/docs/reference/eql/functions.asciidoc
index 8e22e89b065..33f9d2cab35 100644
--- a/docs/reference/eql/functions.asciidoc
+++ b/docs/reference/eql/functions.asciidoc
@@ -9,6 +9,7 @@ experimental::[]
 {es} supports the following EQL functions:
 
 * <<eql-fn-endswith>>
+* <<eql-fn-length>>
 * <<eql-fn-startswith>>
 * <<eql-fn-substring>>
 
@@ -71,7 +72,7 @@ field datatypes:
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
   <<constant-keyword,`constant_keyword`>> sub-field
 
-Fields containing array values use the first array item only.
+Fields containing <<array,array values>> use the first array item only.
 --
 
 `<substring>`::
@@ -92,6 +93,56 @@ field datatypes:
 *Returns:* boolean or `null`
 ====
 
+[discrete]
+[[eql-fn-length]]
+=== `length`
+
+Returns the character length of a provided string, including whitespace and
+punctuation.
+
+[%collapsible]
+====
+*Example*
+[source,eql]
+----
+length("explorer.exe")         // returns 12
+length("start explorer.exe")   // returns 18
+length("")                     // returns 0
+length(null)                   // returns null
+
+// process.name = "regsvr32.exe"
+length(process.name)           // returns 12
+----
+
+*Syntax*
+[source,txt]
+----
+length(<string>)
+----
+
+*Parameters*
+
+`<string>`::
++
+--
+(Required, string or `null`)
+String for which to return the character length. If `null`, the function returns
+`null`. Empty strings return `0`.
+
+If using a field as the argument, this parameter only supports the following
+field datatypes:
+
+* <<keyword,`keyword`>>
+* <<constant-keyword,`constant_keyword`>>
+* <<text,`text`>> field with a <<keyword,`keyword`>> or
+  <<constant-keyword,`constant_keyword`>> sub-field
+
+<<array,Array values>> are not supported.
+--
+
+*Returns:* integer or `null`
+====
+
 [discrete]
 [[eql-fn-startswith]]
 === `startsWith`
@@ -151,7 +202,7 @@ field datatypes:
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
   <<constant-keyword,`constant_keyword`>> sub-field
 
-Fields containing array values use the first array item only.
+Fields containing <<array,array values>> use the first array item only.
 --
 
 `<substring>`::