[DOCS] EQL: Document head and tail pipes (#58673)

Author: jrodewig

docs/reference/eql/functions.asciidoc

@@ -1,3 +1,5 @@
+[role="xpack"]
+[testenv="basic"]
 [[eql-function-ref]]
 == EQL function reference
 ++++

docs/reference/eql/index.asciidoc

@@ -50,10 +50,12 @@ Consider using EQL if you:
 * <<eql-search>>
 * <<eql-syntax>>
 * <<eql-function-ref>>
+* <<eql-pipe-ref>>
 * <<eql-limitations>>
 
 include::requirements.asciidoc[]
 include::search.asciidoc[]
 include::syntax.asciidoc[]
 include::functions.asciidoc[]
+include::pipes.asciidoc[]
 include::limitations.asciidoc[]

docs/reference/eql/limitations.asciidoc

@@ -35,7 +35,12 @@ queries that contain:
 ** `descendant of`
 ** `event of`
 
-* {eql-ref}/pipes.html[Pipes]
+* The following {eql-ref}/pipes.html[pipes]:
+** {eql-ref}/pipes.html#count[`count`]
+** {eql-ref}/pipes.html#filter[`filter`]
+** {eql-ref}/pipes.html#sort[`sort`]
+** {eql-ref}/pipes.html#unique[`unique`]
+** {eql-ref}/pipes.html#unique-count[`unique_count`]
 
 * {eql-ref}/sequences.html[State and timespan-related sequence keywords]:
 ** `with maxspan`

docs/reference/eql/pipes.asciidoc

@@ -0,0 +1,82 @@
+[role="xpack"]
+[testenv="basic"]
+[[eql-pipe-ref]]
+== EQL pipe reference
+++++
+<titleabbrev>Pipe reference</titleabbrev>
+++++
+
+dev::[]
+
+{es} supports the following EQL pipes:
+
+* <<eql-pipe-head>>
+* <<eql-pipe-tail>>
+
+[discrete]
+[[eql-pipe-head]]
+=== `head`
+
+Returns up to a specified number of events, starting with the earliest matching
+events. Works similarly to the
+https://en.wikipedia.org/wiki/Head_(Unix)[Unix head command].
+
+[%collapsible]
+====
+*Example*
+
+The following EQL query returns up to fifty of the earliest powershell
+commands.
+
+[source,eql]
+----
+process where process.name == "powershell.exe"
+| head 50
+----
+
+*Syntax*
+[source,txt]
+----
+head <max>
+----
+
+*Parameters*
+
+`<max>`::
+(Required, integer)
+Maximum number of matching events to return.
+====
+
+[discrete]
+[[eql-pipe-tail]]
+=== `tail`
+
+Returns up to a specified number of events, starting with the most recent
+matching events. Works similarly to the
+https://en.wikipedia.org/wiki/Tail_(Unix)[Unix tail command].
+
+[%collapsible]
+====
+*Example*
+
+The following EQL query returns up to thirty of the most recent `svchost.exe`
+processes.
+
+[source,eql]
+----
+process where process.name == "svchost.exe"
+| tail 30
+----
+
+*Syntax*
+[source,txt]
+----
+tail <max>
+----
+
+*Parameters*
+
+`<max>`::
+(Required, integer)
+Maximum number of matching events to return.
+====

docs/reference/eql/syntax.asciidoc

@@ -473,3 +473,36 @@ file where file.extension in ("exe", "dll")
 We recommend testing and benchmarking any indexing changes before deploying them
 in production. See <<tune-for-indexing-speed>> and <<tune-for-search-speed>>.
 ====
+
+[discrete]
+[[eql-pipes]]
+=== Pipes
+
+EQL pipes filter, aggregate, and post-process events returned by
+an EQL query. You can use pipes to narrow down EQL query results or make them
+more specific.
+
+Pipes are delimited using the pipe (`|`) character.
+
+[source,eql]
+----
+event_category where condition | pipe
+----
+
+.*Example*
+[%collapsible]
+====
+The following EQL query uses the `tail` pipe to return only the 10 most recent
+events matching the query.
+
+[source,eql]
+----
+authentication where agent.id == 4624
+| tail 10
+----
+====
+
+You can pass the output of a pipe to another pipe. This lets you use multiple
+pipes with a single query.
+
+For a list of supported pipes, see <<eql-pipe-ref>>.