Browse Source

[DOCS] EQL: Fix tiebreaker field docs (#64671)

Corrects the EQL docs to remove `event.sequence` as the default `tiebreaker_field` value.
James Rodewig 5 years ago
parent
commit
fb1936bed1
2 changed files with 19 additions and 15 deletions
  1. 4 10
      docs/reference/eql/eql-search-api.asciidoc
  2. 15 5
      docs/reference/eql/eql.asciidoc

+ 4 - 10
docs/reference/eql/eql-search-api.asciidoc

@@ -245,15 +245,9 @@ this value.
 [[eql-search-api-tiebreaker-field]]
 `tiebreaker_field`::
 (Optional, string)
-Field used to sort events with the same
-<<eql-search-api-timestamp-field,timestamp field>> value. Defaults to
-`event.sequence`, as defined in the {ecs-ref}/ecs-event.html[Elastic Common
-Schema (ECS)].
-+
-By default, matching events in the search response are sorted by timestamp,
-converted to milliseconds since the {wikipedia}/Unix_time[Unix
-epoch], in ascending order. If two or more events share the same timestamp, this
-field is used to sort the events in ascending, lexicographic order.
+Field used to sort hits with the same
+<<eql-search-api-timestamp-field,timestamp>> in ascending, lexicographic order.
+See <<eql-search-specify-a-sort-tiebreaker>>.
 
 [[eql-search-api-timestamp-field]]
 `timestamp_field`::
@@ -311,7 +305,7 @@ This search ID is only provided if one of the following conditions is met:
 * A search request does not return complete results during the
   <<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
   parameter's timeout period, becoming an <<eql-search-async,async search>>.
-  
+
 * The search request's <<eql-search-api-keep-on-completion,`keep_on_completion`>>
   parameter is `true`.
 

+ 15 - 5
docs/reference/eql/eql.asciidoc

@@ -141,7 +141,7 @@ GET /my-index-000001/_eql/search
 === Search for a sequence of events
 
 Use EQL's <<eql-sequences,sequence syntax>> to search for a series of
-ordered events. List the event items in ascending chronological order, 
+ordered events. List the event items in ascending chronological order,
 with the most recent event listed last:
 
 [source,console]
@@ -388,18 +388,28 @@ or event category field.
 [[eql-search-specify-a-sort-tiebreaker]]
 === Specify a sort tiebreaker
 
-By default, the EQL search API returns matching events by timestamp. If two or
+By default, the EQL search API returns matching hits by timestamp. If two or
 more events share the same timestamp, {es} uses a tiebreaker field value to sort
 the events in ascending, lexicographic order.
 
-`event.sequence` is the default tiebreaker field. To specify another tiebreaker
-field, use the `tiebreaker_field` parameter:
+If you don't specify a tiebreaker field or the events also share the same
+tiebreaker value, {es} considers the events concurrent. Concurrent events cannot
+be part of the same sequence and may not be returned in a consistent sort order.
+
+To specify a tiebreaker field, use the `tiebreaker_field` parameter. If you
+specify a tiebreaker field for a sequence query, all events in the searched data
+streams or indices must contain a tiebreaker field value. For basic queries,
+{es} orders matching events with no tiebreaker value after events with a
+tiebreaker value.
+
+If you use the {ecs-ref}[ECS], we recommend using `event.sequence` as the
+tiebreaker field.
 
 [source,console]
 ----
 GET /my-index-000001/_eql/search
 {
-  "tiebreaker_field": "event.id",
+  "tiebreaker_field": "event.sequence",
   "query": """
     process where process.name == "cmd.exe" and stringContains(process.executable, "System32")
   """