From e74fdacabdd66b204d755676621d9992f52556e3 Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@elastic.co>
Date: Thu, 23 Apr 2020 10:59:50 -0400
Subject: [PATCH] [DOCS] Add admonition for EQL exact matches on text fields
 (#53402) (#55670)

Adds a important admonition to the EQL syntax page noting that
the equal (`==`) operator should not be used to match `text` field
values.

Relates to #52709 and #53020
---
 docs/reference/eql/syntax.asciidoc | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/reference/eql/syntax.asciidoc b/docs/reference/eql/syntax.asciidoc
index cbb5fb780ae..a72a9bc656c 100644
--- a/docs/reference/eql/syntax.asciidoc
+++ b/docs/reference/eql/syntax.asciidoc
@@ -10,7 +10,7 @@ experimental::[]
 
 [IMPORTANT]
 ====
-{es} supports a subset of EQL syntax.
+{es} supports a subset of EQL syntax. See <<eql-limitations>>.
 ====
 
 [discrete]
@@ -72,6 +72,19 @@ You can specify and combine these criteria using the following operators:
 <   <=   ==   !=   >=   >
 ----
 
+[IMPORTANT]
+====
+Avoid using the equal operator (`==`) to perform exact matching on `text` field
+values.
+
+By default, {es} changes the values of <<text,`text`>> fields as part of
+<<analysis, analysis>>. This can make finding exact matches for `text` field
+values difficult.
+
+To search `text` fields, consider using a <<eql-search-filter-query-dsl,query
+DSL filter>> that contains a <<query-dsl-match-query,`match`>> query.
+====
+
 .*Definitions*
 [%collapsible]
 ====