From 65f49d0bbae6403130dd69443995af0cc8b4b8df Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Mon, 27 Jan 2020 16:03:23 -0500
Subject: [PATCH] [DOCS] Add top-level EQL docs page. Adds EQL requirements
 page. (#51334)

* Creates a top-level page for EQL in the ES reference.
   This page contains a high-level introduction and will include a nav for other EQL docs pages as they're built.

* Creates a requirements page.
  This page outlines the fields needed to use EQL in ES.
---
 docs/reference/eql/index.asciidoc        | 34 +++++++++++++++++++++++
 docs/reference/eql/requirements.asciidoc | 35 ++++++++++++++++++++++++
 docs/reference/index.asciidoc            |  2 ++
 3 files changed, 71 insertions(+)
 create mode 100644 docs/reference/eql/index.asciidoc
 create mode 100644 docs/reference/eql/requirements.asciidoc

diff --git a/docs/reference/eql/index.asciidoc b/docs/reference/eql/index.asciidoc
new file mode 100644
index 00000000000..8c4b0e07ce2
--- /dev/null
+++ b/docs/reference/eql/index.asciidoc
@@ -0,0 +1,34 @@
+[role="xpack"]
+[testenv="basic"]
+[[eql]]
+= EQL for event-based search
+++++
+<titleabbrev>EQL</titleabbrev>
+++++
+
+experimental::[]
+
+{eql-ref}/index.html[Event Query Language (EQL)] is a query language used for
+logs and other event-based data.
+
+You can use EQL in {es} to easily express relationships between events and
+quickly match events with shared properties. You can use EQL and query
+DSL together to better filter your searches.
+
+[float]
+[[when-to-use-eql]]
+=== When to use EQL
+
+Consider using EQL if you:
+
+* Use {es} for threat hunting or other security use cases
+* Search time-series data or logs, such as network or system logs
+* Want an easy way to explore relationships between events
+
+[float]
+[[eql-toc]]
+=== In this section
+
+* <<eql-requirements,EQL requirements>>
+
+include::requirements.asciidoc[]
diff --git a/docs/reference/eql/requirements.asciidoc b/docs/reference/eql/requirements.asciidoc
new file mode 100644
index 00000000000..1791b547d50
--- /dev/null
+++ b/docs/reference/eql/requirements.asciidoc
@@ -0,0 +1,35 @@
+[role="xpack"]
+[testenv="basic"]
+[[eql-requirements]]
+== EQL requirements
+++++
+<titleabbrev>Requirements</titleabbrev>
+++++
+
+EQL is schemaless and works out-of-the-box with most common log formats. If you
+use a standard log format and already know what fields in your index contain
+event type and timestamp information, you can skip this page.
+
+[discrete]
+[[eql-required-fields]]
+=== Required fields
+
+In {es}, EQL assumes each document in an index corresponds to an event.
+
+To search an index using EQL, each document in the index must contain the
+following field archetypes:
+
+Event type::
+A field containing the event classification, such as `process`, `file`, or
+`network`. This is typically mapped as a <<keyword,`keyword`>> field.
+
+Timestamp::
+A field containing the date and/or time the event occurred. This is typically
+mapped as a <<date,`date`>> field.
+
+[TIP]
+====
+While no schema is required to use EQL in {es}, we recommend the
+{ecs-ref}[Elastic Common Schema (ECS)]. {es}'s EQL search is designed to work
+with core ECS fields by default.
+====
\ No newline at end of file
diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc
index df4f2f75070..6dc0c88a10b 100644
--- a/docs/reference/index.asciidoc
+++ b/docs/reference/index.asciidoc
@@ -48,6 +48,8 @@ ifeval::["{release-state}"=="unreleased"]
 
 include::autoscaling/index.asciidoc[]
 
+include::eql/index.asciidoc[]
+
 endif::[]
 
 include::sql/index.asciidoc[]