Browse Source

[DOCS] EQL: Update grammary for escaped event categories (#63202)

James Rodewig 5 years ago
parent
commit
cb9e61fae5

+ 1 - 1
docs/reference/eql/eql-search-api.asciidoc

@@ -145,7 +145,7 @@ Defaults to `event.category`, as defined in the {ecs-ref}/ecs-event.html[Elastic
 Common Schema (ECS)]. If a data stream or index does not contain the
 `event.category` field, this value is required.
 +
-The event category field is typically mapped as a field type in the
+The event category field must be mapped as a field type in the
 <<keyword,`keyword`>> family.
 
 `fetch_size`::

+ 1 - 1
docs/reference/eql/eql.asciidoc

@@ -404,7 +404,7 @@ documents use a different timestamp or event category field, you must specify it
 in the search request using the `timestamp_field` or `event_category_field`
 parameters.
 
-The event category field is typically mapped as a field type in the
+The event category field must be mapped as a field type in the
 <<keyword,`keyword`>> family. The timestamp field should be mapped as a
 <<date,`date`>> field type. <<date_nanos,`date_nanos`>> timestamp fields are not
 supported.

+ 33 - 6
docs/reference/eql/syntax.asciidoc

@@ -55,11 +55,38 @@ any where network.protocol == "http"
 ----
 
 [discrete]
-[[eql-syntax-escape-identifiers]]
-===== Escape an event category or field name
+[[eql-syntax-escape-an-event-category]]
+===== Escape an event category
 
-Event categories or field names that contain a hyphen (`-`), contain a space, or
-start with a numeral must be escaped with enclosing backticks (+++`+++).
+Use enclosing double quotes (`"`) or three enclosing double quotes (`"""`) to
+escape event categories that:
+
+* Contain a special character, such as a hyphen (`-`) or dot (`.`)
+* Contain a space
+* Start with a numeral
+
+[source,eql]
+----
+".my.event.category"
+"my-event-category"
+"my event category"
+"6eventcategory"
+
+""".my.event.category"""
+"""my-event-category"""
+"""my event category"""
+"""6eventcategory"""
+----
+
+[discrete]
+[[eql-syntax-escape-a-field-name]]
+===== Escape a field name
+
+Use enclosing enclosing backticks (+++`+++) to escape field names that:
+
+* Contain a hyphen (`-`)
+* Contain a space
+* Start with a numeral
 
 [source,eql]
 ----
@@ -68,8 +95,8 @@ start with a numeral must be escaped with enclosing backticks (+++`+++).
 `6myfield`
 ----
 
-Any backticks (+++`+++) in an event category or field name must be escaped using
-double backticks (+++``+++).
+Use double backticks (+++``+++) to escape any backticks (+++`+++) in the field
+name.
 
 [source,eql]
 ----