Fixed Properties reference docs.

Fixed Properties reference docs.

== VASSAL Reference Manual
[#top]

[.small]#<<index.adoc#toc,Home>> > <<GameModule.adoc#top,Module>> > <<PieceWindow.adoc#top,Game Piece Palette>> > <<GamePiece.adoc#top,Game Piece>> > *Properties*#

'''''

=== Properties

A Property is like a variable in programming: it has a _value_ which can be referenced by including its _name_ in <<Expression.adoc#top,Expressions>>, <<MessageFormat.adoc#top,Message Formats>> and other similar fields.
Most types of Property have their values change through the course of the game.
Some Properties can have their values set by commands provided in Game Pieces themselves; others have their values set by the system and cannot be changed from within the module.

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components.
You can add your own new properties to a Game Piece _explicitly_ by adding <<DynamicProperty.adoc#top,Dynamic Property>> traits to create values which can be changed during the course of the game and <<PropertyMarker.adoc#top,Marker>> traits for properties whose values will remain constant.
System-defined properties are also added _implicitly_ when other traits are added (see below). <<GlobalProperties.adoc#top,Global Properties>> can also be defined for a Zone, a Map or for the entire module.
If a referenced Property name is not defined in a Game Piece, the VASSAL looks for the value in the Zone containing the piece, then in the Map containing the piece, then in the module.

Properties can be matched using <<Expression.adoc#top,Expressions>> like _name == value_ for an exact match, _name != value_ for a non-match, or _name =~ value_ for a https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[regular expression] match.
For properties that return a numeric value (e.g.
the level in a <<Layer.adoc#Properties,Layer)>> you can use _<_, _<=_, _>_, and _>=._  You can combine expressions using && for logical AND and || for a logical OR.

*Components that use properties*

* Any <<MessageFormat.adoc#top,Message Format>> defined in a Game Piece will substitute values for the properties defined on that Game Piece.

* The <<Map.adoc#GlobalKeyCommand,Global Key Command>> component uses properties to determine which pieces will respond to the command.
* The <<Map.adoc#GamePieceLayers,Game Piece Layers>> component uses properties to determine relative ordering when drawing pieces on the map.
* The <<TriggerAction.adoc#top,Trigger Action>> trait uses properties to determine when to fire a Key Command or <<NamedKeyCommand.adoc#top,Named Key Command>> .
* The <<Label.adoc#top,Text Label>> trait substitutes properties when setting the text of the label.
* A <<ZonedGrid.adoc#Zone,Zone>> uses properties to specify a <<ZonedGrid.adoc#ZoneHighlighter,Zone Highlighter>>.

*Properties defined by Game Pieces*

* The <<BasicPiece.adoc#top,Basic Piece>> defines properties related to a piece's name, location, side, and whether it's selected.

* The <<Layer.adoc#Properties,Layer>> trait defines properties related to the state of that Layer.
* The <<Rotate.adoc#top,Rotate>> trait defines properties related to the current facing of the piece.

* The <<Label.adoc#top,Text Label>> trait returns the value of the label as a property.
* The <<PropertyMarker.adoc#top,Marker>> trait allows you to define your own static properties.
* The <<DynamicProperty.adoc#top,Dynamic Property>> trait allows you to define your own changeable properties.

* The <<MarkMoved.adoc#top,Mark When Moved>> trait sets a property when a piece has moved.
* The <<Mask.adoc#Properties,Mask>> trait sets a property when the piece is masked.
* The <<Hideable.adoc#top,Invisible>> trait sets a property when the piece is invisible.

* The <<PropertySheet.adoc#top,Property Sheet>> trait exposes a set of user-editable properties.

*Properties defined by other components*

* The <<GlobalProperties.adoc#top,Global Property>> component defines properties for a <<ZonedGrid.adoc#Zone,Zone>>, <<Map.adoc#top,Map>> or the <<GameModule.adoc#top,module>>.
* The <<GlobalOptions.adoc#top,Global Options>> component allows you to tie property values to preferences settings.
* The results of a roll by a <<GameModule.adoc#DiceButton,Dice Button>> is exposed as a property
* A <<Deck.adoc#top,Deck>> component exposes the number of cards remaining as a Map-level property.

==== Handy Combined List of VASSAL-defined Properties for Game Pieces

|===
|Property |Trait |Description
|*BasicName* |<<BasicPiece.adoc#top,Basic Piece>> |The basic name of the piece.
|*ClickedX* |Basic Piece |Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*ClickedY* |Basic Piece |Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*CurrentBoard* |Basic Piece |Current Board name or "" if not on a map.
|*CurrentMap* |Basic Piece |Current Map name or "" if not on a map.
|*CurrentX* |Basic Piece |Current X-coordinate of the piece.
|*CurrentY* |Basic Piece |Current Y-coordinate of the piece.
|*CurrentZone* |Basic Piece |Current Zone name if the current map has a <<ZonedGrid.adoc#top,multi-zoned grid>>, or "" if the piece is not in any zone, or not on a map.
|*DeckName* |Basic Piece |Current Deck name if stacked in a <<Deck.adoc#top,Deck>>, or "" if not in a Deck.
|*IgnoreGrid* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece ignores the map grid when moving.
|*Immobile* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot be moved by drag and drop.
|*Invisible* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to the current player.
|*InvisibleToOthers* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to other players.
|*LocationName* |Basic Piece |Name of the piece's current location, as determined by the map's <<ZonedGrid.adoc#Zone,Zone>> (if any) and grid settings.
|*Moved* |<<MarkMoved.adoc#top,Mark When Moved>> |"true" if this piece has moved since the last time its movement history was cleared.
|*NoStack* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot stack with other pieces.
|*Obscured* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from the current player.
|*ObscuredToOthers* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from other players.
|*OldBoard* |Basic Piece |Board name prior to most recent movement.
|*OldLocationName* |Basic Piece |Location name prior to most recent movement.
|*OldMap* |Basic Piece |Map name prior to most recent movement.
|*OldX* |Basic Piece |X coordinate prior to most recent movement.
|*OldY* |Basic Piece |Y coordinate prior to most recent movement.
|*OldZone* |Basic Piece |Zone name prior to most recent movement.
|*PieceName* |Basic Piece |Full piece name including both Basic Name and all additional strings provided by traits.
|*playerSide* |Basic Piece |Side of the current player (not the side of the piece).
|*Restricted* |<<RestrictedAccess.adoc#top,Restricted Access>> |"true" if there are restrictions as to who can access this piece.
|*Selected* |Basic Piece |"true" if the piece is currently selected.
|*_<property_name>_* |<<PropertySheet.adoc#top,PropertySheet>> |The value of each property on the Property Sheet can be accessed via the property name.
|*_<layername>__Active* |<<Layer.adoc#top,Layer>> |"true" if the Layer _<layername>_ is currently active.
|*_<layername>__Image* |<<Layer.adoc#top,Layer>> |The image name of the currently active layer for _Layer_ _<layername>_.
|*_<layername>__Level* |<<Layer.adoc#top,Layer>> |The level number of the currently active layer for _Layer_ _<layername>_.
|*_<layername>__Name* |<<Layer.adoc#top,Layer>> |The level name of the currently active layer for _Layer_ _<layername>_.
|*_<rotatename>__Facing* |<<Rotate.adoc#top,Can Rotate>> |The current facing number (1, 2, etc) for the _Can Rotate_ trait _<rotatename>_.
|*_<rotatename>__Degrees* |<<Rotate.adoc#top,Can Rotate>> |The current degrees of rotation for the _Can Rotate_ trait _<name>_.
|_<Property Name>_ |<<Label.adoc#top,Text Label>> |If the "Property Name" field in the trait is filled out, then a property with that name will be filled with the current value of the _Text Label_ trait's Text field.
|*_<deckname>__numPieces* |<<Deck.adoc#top,Deck>> (Map level property) |Number of pieces/"cards" in the _Deck_ _<deckname>_.
|*_<deckname>___<expression_name>_* |<<Deck.adoc#top,Deck>> (Map level property) |The number of pieces/"cards" for which the named expression evaluates to true in the _Deck_ _<deckname>_.
|===

== VASSAL Reference Manual
[#top]

[.small]#<<index.adoc#toc,Home>> > <<GameModule.adoc#top,Module>> > <<PieceWindow.adoc#top,Game Piece Palette>> > <<GamePiece.adoc#top,Game Piece>> > *Properties*#

'''''

=== Properties

[width="100%",cols="34%,33%,33%",]
|===
a|
A Property is like a variable in programming: it has a _value_ which can be referenced by including its _name_ in <<Expression.adoc#top,Expressions>>, <<MessageFormat.adoc#top,Message Formats>> and other similar fields.
Most types of Property have their values change through the course of the game.
Some Properties can have their values set by commands provided in Game Pieces themselves; others have their values set by the system and cannot be changed from within the module.

Each Game Piece has its own set of properties (each with a name and a value) that can be used for identification by various components.
You can add your own new properties to a Game Piece _explicitly_ by adding <<DynamicProperty.adoc#top,Dynamic Property>> traits to create values which can be changed during the course of the game and <<PropertyMarker.adoc#top,Marker>> traits for properties whose values will remain constant.
System-defined properties are also added _implicitly_ when other traits are added (see below). <<GlobalProperties.adoc#top,Global Properties>> can also be defined for a Zone, a Map or for the entire module.
If a referenced Property name is not defined in a Game Piece, the VASSAL looks for the value in the Zone containing the piece, then in the Map containing the piece, then in the module.

Properties can be matched using <<Expression.adoc#top,Expressions>> like _name == value_ for an exact match, _name != value_ for a non-match, or _name =~ value_ for a https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[regular expression] match.
For properties that return a numeric value (e.g.
the level in a <<Layer.adoc#Properties,Layer)>> you can use _<_, _<=_, _>_, and _>=._  You can combine expressions using && for logical AND and || for a logical OR.

*Components that use properties*

* Any <<MessageFormat.adoc#top,Message Format>> defined in a Game Piece will substitute values for the properties defined on that Game Piece.

* The <<Map.adoc#GlobalKeyCommand,Global Key Command>> component uses properties to determine which pieces will respond to the command.
* The <<Map.adoc#GamePieceLayers,Game Piece Layers>> component uses properties to determine relative ordering when drawing pieces on the map.
* The <<TriggerAction.adoc#top,Trigger Action>> trait uses properties to determine when to fire a Key Command or <<NamedKeyCommand.adoc#top,Named Key Command>> .
* The <<Label.adoc#top,Text Label>> trait substitutes properties when setting the text of the label.
* A <<ZonedGrid.adoc#Zone,Zone>> uses properties to specify a <<ZonedGrid.adoc#ZoneHighlighter,Zone Highlighter>>.

*Properties defined by Game Pieces*

* The <<BasicPiece.adoc#top,Basic Piece>> defines properties related to a piece's name, location, side, and whether it's selected.

* The <<Layer.adoc#Properties,Layer>> trait defines properties related to the state of that Layer.
* The <<Rotate.adoc#top,Rotate>> trait defines properties related to the current facing of the piece.

* The <<Label.adoc#top,Text Label>> trait returns the value of the label as a property.
* The <<PropertyMarker.adoc#top,Marker>> trait allows you to define your own static properties.
* The <<DynamicProperty.adoc#top,Dynamic Property>> trait allows you to define your own changeable properties.

* The <<MarkMoved.adoc#top,Mark When Moved>> trait sets a property when a piece has moved.
* The <<Mask.adoc#Properties,Mask>> trait sets a property when the piece is masked.
* The <<Hideable.adoc#top,Invisible>> trait sets a property when the piece is invisible.

* The <<PropertySheet.adoc#top,Property Sheet>> trait exposes a set of user-editable properties.

*Properties defined by other components*

* The <<GlobalProperties.adoc#top,Global Property>> component defines properties for a <<ZonedGrid.adoc#Zone,Zone>>, <<Map.adoc#top,Map>> or the <<GameModule.adoc#top,module>>.
* The <<GlobalOptions.adoc#top,Global Options>> component allows you to tie property values to preferences settings.
* The results of a roll by a <<GameModule.adoc#DiceButton,Dice Button>> is exposed as a property
* A <<Deck.adoc#top,Deck>> component exposes the number of cards remaining as a Map-level property.
|===

==== Handy Combined List of VASSAL-defined Properties for Game Pieces

|===
|Property |Trait |Description
|*BasicName* |<<BasicPiece.adoc#top,Basic Piece>> |The basic name of the piece.
|*ClickedX* |Basic Piece |Map X-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*ClickedY* |Basic Piece |Map Y-coordinate where player last right-clicked on piece to bring up context menu (or 0 if never).
|*CurrentBoard* |Basic Piece |Current Board name or "" if not on a map.
|*CurrentMap* |Basic Piece |Current Map name or "" if not on a map.
|*CurrentX* |Basic Piece |Current X-coordinate of the piece.
|*CurrentY* |Basic Piece |Current Y-coordinate of the piece.
|*CurrentZone* |Basic Piece |Current Zone name if the current map has a <<ZonedGrid.adoc#top,multi-zoned grid>>, or "" if the piece is not in any zone, or not on a map.
|*DeckName* |Basic Piece |Current Deck name if stacked in a <<Deck.adoc#top,Deck>>, or "" if not in a Deck.
|*IgnoreGrid* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece ignores the map grid when moving.
|*Immobile* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot be moved by drag and drop.
|*Invisible* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to the current player.
|*InvisibleToOthers* |<<Hideable.adoc#top,Invisible>> |"true" if this piece is invisible to other players.
|*LocationName* |Basic Piece |Name of the piece's current location, as determined by the map's <<ZonedGrid.adoc#Zone,Zone>> (if any) and grid settings.
|*Moved* |<<MarkMoved.adoc#top,Mark When Moved>> |"true" if this piece has moved since the last time its movement history was cleared.
|*NoStack* |<<NonStacking.adoc#top,Does not stack>> |"true" if this piece cannot stack with other pieces.
|*Obscured* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from the current player.
|*ObscuredToOthers* |<<Mask.adoc#top,Mask>> |"true" if this piece is masked from other players.
|*OldBoard* |Basic Piece |Board name prior to most recent movement.
|*OldLocationName* |Basic Piece |Location name prior to most recent movement.
|*OldMap* |Basic Piece |Map name prior to most recent movement.
|*OldX* |Basic Piece |X coordinate prior to most recent movement.
|*OldY* |Basic Piece |Y coordinate prior to most recent movement.
|*OldZone* |Basic Piece |Zone name prior to most recent movement.
|*PieceName* |Basic Piece |Full piece name including both Basic Name and all additional strings provided by traits.
|*playerSide* |Basic Piece |Side of the current player (not the side of the piece).
|*Restricted* |<<RestrictedAccess.adoc#top,Restricted Access>> |"true" if there are restrictions as to who can access this piece.
|*Selected* |Basic Piece |"true" if the piece is currently selected.
|*_<property_name>_* |<<PropertySheet.adoc#top,PropertySheet>> |The value of each property on the Property Sheet can be accessed via the property name.
|*_<layername>__Active* |<<Layer.adoc#top,Layer>> |"true" if the Layer _<layername>_ is currently active.
|*_<layername>__Image* |<<Layer.adoc#top,Layer>> |The image name of the currently active layer for _Layer_ _<layername>_.
|*_<layername>__Level* |<<Layer.adoc#top,Layer>> |The level number of the currently active layer for _Layer_ _<layername>_.
|*_<layername>__Name* |<<Layer.adoc#top,Layer>> |The level name of the currently active layer for _Layer_ _<layername>_.
|*_<rotatename>__Facing* |<<Rotate.adoc#top,Can Rotate>> |The current facing number (1, 2, etc) for the _Can Rotate_ trait _<rotatename>_.
|*_<rotatename>__Degrees* |<<Rotate.adoc#top,Can Rotate>> |The current degrees of rotation for the _Can Rotate_ trait _<name>_.
|_<Property Name>_ |<<Label.adoc#top,Text Label>> |If the "Property Name" field in the trait is filled out, then a property with that name will be filled with the current value of the _Text Label_ trait's Text field.
|*_<deckname>__numPieces* |<<Deck.adoc#top,Deck>> (Map level property) |Number of pieces/"cards" in the _Deck_ _<deckname>_.
|*_<deckname>___<expression_name>_* |<<Deck.adoc#top,Deck>> (Map level property) |The number of pieces/"cards" for which the named expression evaluates to true in the _Deck_ _<deckname>_.
|===


[DOCS] Update `ignore_unavailable` default for EQL search API (#63210)

[role="xpack"]
[testenv="basic"]

[[eql-search-api]]
=== EQL search API
++++
<titleabbrev>EQL search</titleabbrev>
++++

beta::[]

Returns search results for an <<eql,Event Query Language (EQL)>> query.

EQL assumes each document in a data stream or index corresponds to an
event.

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    process where process.name == "regsvr32.exe"
  """
}
----
// TEST[setup:sec_logs]

[[eql-search-api-request]]
==== {api-request-title}

`GET /<target>/_eql/search`

`POST /<target>/_eql/search`

[[eql-search-api-prereqs]]
==== {api-prereq-title}

See <<eql-required-fields>>.

[[eql-search-api-limitations]]
===== Limitations

See <<eql-syntax-limitations,EQL limitations>>.

[[eql-search-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string)
Comma-separated list of data streams, indices, or <<indices-aliases,index
aliases>> used to limit the request. Accepts wildcard (`*`) expressions.
+
To search all data streams and indices in a cluster, use
`_all` or `*`.

[[eql-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

`ignore_unavailable`::
(Optional, boolean) If `true`, missing or closed indices are not included in the
response. Defaults to `true`.

`keep_alive`::
+
--
(Optional, <<time-units,time value>>)
Period for which the search and its results are stored on the cluster. Defaults
to `5d` (five days).

When this period expires, the search and its results are deleted, even if the
search is still ongoing.

If the <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter is
`false`, {es} only stores <<eql-search-async,async searches>> that do not
complete within the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter, regardless of this value.

[IMPORTANT]
====
You can also specify this value using the `keep_alive` request body parameter.
If both parameters are specified, only the query parameter is used.
====
--

`keep_on_completion`::
+
--
(Optional, boolean)
If `true`, the search and its results are stored on the cluster.

If `false`, the search and its results are stored on the cluster only if the
request does not complete during the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter. Defaults to `false`.

[IMPORTANT]
====
You can also specify this value using the `keep_on_completion` request body
parameter. If both parameters are specified, only the query parameter is used.
====
--

`wait_for_completion_timeout`::
+
--
(Optional, <<time-units,time value>>)
Timeout duration to wait for the request to finish. Defaults to no
timeout, meaning the request waits for complete search results.

If this parameter is specified and the request completes during this period,
complete search results are returned.

If the request does not complete during this period, the search becomes an
<<eql-search-async,async search>>.

[IMPORTANT]
====
You can also specify this value using the `wait_for_completion_timeout` request
body parameter. If both parameters are specified, only the query parameter is
used.
====
--

[[eql-search-api-request-body]]
==== {api-request-body-title}

`event_category_field`::
(Required*, string)
Field containing the event classification, such as `process`, `file`, or
`network`.
+
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 must be mapped as a field type in the
<<keyword,`keyword`>> family.

`fetch_size`::
(Optional, integer)
Maximum number of events to search at a time for sequence queries. Defaults to
`1000`.
+
This value must be greater than `2` but cannot exceed the value of the
<<index-max-result-window,`index.max_result_window`>> setting, which defaults to
`10000`.
+
Internally, a sequence query fetches and paginates sets of events to search for
matches. This parameter controls the size of those sets. This parameter does not
limit the total number of events searched or the number of matching events
returned.
+
A greater `fetch_size` value often increases search speed but uses more memory.

`filter`::
(Optional, <<query-dsl,query DSL object>>)
Query, written in query DSL, used to filter the events on which the EQL query
runs.

`keep_alive`::
+
--
(Optional, <<time-units,time value>>)
Period for which the search and its results are stored on the cluster. Defaults
to `5d` (five days).

When this period expires, the search and its results are deleted, even if the
search is still ongoing.

If the <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter is
`false`, {es} only stores <<eql-search-async,async searches>> that do not
complete within the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter, regardless of this value.

[IMPORTANT]
====
You can also specify this value using the `keep_alive` query parameter.
If both parameters are specified, only the query parameter is used.
====
--

[[eql-search-api-keep-on-completion]]
`keep_on_completion`::
+
--
(Optional, boolean)
If `true`, the search and its results are stored on the cluster.

If `false`, the search and its results are stored on the cluster only if the
request does not complete during the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter. Defaults to `false`.

[IMPORTANT]
====
You can also specify this value using the `keep_on_completion` query parameter.
If both parameters are specified, only the query parameter is used.
====
--

[[eql-search-api-request-query-param]]
`query`::
(Required, string)
<<eql-syntax,EQL>> query you wish to run.

`size`::
(Optional, integer or float)
For <<eql-basic-syntax,basic queries>>, the maximum number of matching events to
return.
+
For <<eql-sequences,sequence queries>>, the maximum number of matching sequences
to return.
+
Defaults to `10`. This value must be greater than `0`.
+
NOTE: You cannot use <<eql-pipe-ref,pipes>>, such as `head` or `tail`, to exceed
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.

[[eql-search-api-timestamp-field]]
`timestamp_field`::
+
--
(Required*, string)
Field containing event timestamp.

Defaults to `@timestamp`, as defined in the
{ecs-ref}/ecs-event.html[Elastic Common Schema (ECS)]. If a data stream or index
does not contain the `@timestamp` field, this value is required.

Events in the API response are sorted by this field's value, converted to
milliseconds since the {wikipedia}/Unix_time[Unix epoch], in
ascending order.

The timestamp field should be mapped as a <<date,`date`>>. The
<<date_nanos,`date_nanos`>> field type is not supported.
--

[[eql-search-api-wait-for-completion-timeout]]
`wait_for_completion_timeout`::
+
--
(Optional, <<time-units,time value>>)
Timeout duration to wait for the request to finish. Defaults to no
timeout, meaning the request waits for complete search results.

If this parameter is specified and the request completes during this period,
complete search results are returned.

If the request does not complete during this period, the search becomes an
<<eql-search-async,async search>>.

[IMPORTANT]
====
You can also specify this value using the `wait_for_completion_timeout` query
parameter. If both parameters are specified, only the query parameter is used.
====
--

[role="child_attributes"]
[[eql-search-api-response-body]]
==== {api-response-body-title}

[[eql-search-api-response-body-search-id]]
`id`::
+
--
(string)
Identifier for the search.

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`.

You can use this ID with the <<get-async-eql-search-api,get async EQL search
API>> to get the current status and available results for the search.
--

`is_partial`::
(boolean)
If `true`, the response does not contain complete search results.

`is_running`::
+
--
(boolean)
If `true`, the search request is still executing.

[IMPORTANT]
====
If this parameter and the `is_partial` parameter are `true`, the search is an
<<eql-search-async,ongoing async search>>. If the `keep_alive` period does not
pass, the complete search results will be available when the search completes.

If `is_partial` is `true` but `is_running` is `false`, the search returned
partial results due to a failure. Only some shards returned results or the node
coordinating the search failed.
====
--

`took`::
+
--
(integer)
Milliseconds it took {es} to execute the request.

This value is calculated by measuring the time elapsed
between receipt of a request on the coordinating node
and the time at which the coordinating node is ready to send the response.

Took time includes:

* Communication time between the coordinating node and data nodes
* Time the request spends in the `search` <<modules-threadpool,thread pool>>,
  queued for execution
* Actual execution time

Took time does *not* include:

* Time needed to send the request to {es}
* Time needed to serialize the JSON response
* Time needed to send the response to a client
--

`timed_out`::
(boolean)
If `true`, the request timed out before completion.

`hits`::
(object)
Contains matching events and sequences. Also contains related metadata.
+
.Properties of `hits`
[%collapsible%open]
====

`total`::
(object)
Metadata about the number of matching events or sequences.
+
.Properties of `total`
[%collapsible%open]
=====

`value`::
(integer)
For <<eql-basic-syntax,basic queries>>, the total number of matching events.
+
For <<eql-sequences,sequence queries>>, the total number of matching sequences.

`relation`::
+
--
(string)
Indicates whether the number of events or sequences returned is accurate or a
lower bound.

Returned values are:

`eq`::: Accurate
`gte`::: Lower bound, including returned events or sequences
--
=====

`sequences`::
(array of objects)
Contains event sequences matching the query. Each object represents a
matching sequence. This parameter is only returned for EQL queries containing
a <<eql-sequences,sequence>>.
+
.Properties of `sequences` objects
[%collapsible%open]
=====
`join_keys`::
(array of values)
Shared field values used to constrain matches in the sequence. These are defined
using the <<eql-sequences,`by` keyword>> in the EQL query syntax.

`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
======
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_source`::
(object)
Original JSON body passed for the event at index time.
======
=====

[[eql-search-api-response-events]]
`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
=====
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_source`::
(object)
Original JSON body passed for the event at index time.
=====
====

[[eql-search-api-example]]
==== {api-examples-title}

[[eql-search-api-basic-query-ex]]
===== Basic query example

The following EQL search request searches for events with an `event.category` of
`process` that meet the following conditions:

* A `process.name` of `cmd.exe`
* An `process.pid` other than `2013`

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}
----
// TEST[setup:sec_logs]

The API returns the following response. Matching events in the `hits.events`
property are sorted by <<eql-search-api-timestamp-field,timestamp>>, converted
to milliseconds since the {wikipedia}/Unix_time[Unix epoch],
in ascending order.

If two or more events share the same timestamp, the
<<eql-search-api-tiebreaker-field,`tiebreaker_field`>> field is used to sort
the events in ascending, lexicographic order.

[source,console-result]
----
{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "events": [
      {
        "_index": "my-index-000001",
        "_id": "babI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-06T11:04:05.000Z",
          "event": {
            "category": "process",
            "id": "edwCRnyD",
            "sequence": 1
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      },
      {
        "_index": "my-index-000001",
        "_id": "b6bI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-07T11:06:07.000Z",
          "event": {
            "category": "process",
            "id": "cMyt5SZ2",
            "sequence": 3
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "babI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.0._id/]
// TESTRESPONSE[s/"_id": "b6bI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.1._id/]

[[eql-search-api-sequence-ex]]
===== Sequence query example

The following EQL search request matches a <<eql-sequences,sequence>> of events
that:

. Start with an event with:
+
--
* An `event.category` of `file`
* A `file.name` of `cmd.exe`
* An `process.pid` other than `2013`
--
. Followed by an event with:
+
--
* An `event.category` of `process`
* A `process.executable` that contains the substring `regsvr32`
--

These events must also share the same `process.pid` value.

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}
----
// TEST[setup:sec_logs]

The API returns the following response. Matching sequences are included in the
`hits.sequences` property. The `hits.sequences.join_keys` property contains the
shared `process.pid` value for each matching event.

[source,console-result]
----
{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": "my-index-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": "my-index-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.sequences.0.events.1._id/]

[role="xpack"]
[testenv="basic"]

[[eql-search-api]]
=== EQL search API
++++
<titleabbrev>EQL search</titleabbrev>
++++

beta::[]

Returns search results for an <<eql,Event Query Language (EQL)>> query.

EQL assumes each document in a data stream or index corresponds to an
event.

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    process where process.name == "regsvr32.exe"
  """
}
----
// TEST[setup:sec_logs]

[[eql-search-api-request]]
==== {api-request-title}

`GET /<target>/_eql/search`

`POST /<target>/_eql/search`

[[eql-search-api-prereqs]]
==== {api-prereq-title}

See <<eql-required-fields>>.

[[eql-search-api-limitations]]
===== Limitations

See <<eql-syntax-limitations,EQL limitations>>.

[[eql-search-api-path-params]]
==== {api-path-parms-title}

`<target>`::
(Required, string)
Comma-separated list of data streams, indices, or <<indices-aliases,index
aliases>> used to limit the request. Accepts wildcard (`*`) expressions.
+
To search all data streams and indices in a cluster, use
`_all` or `*`.

[[eql-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

`keep_alive`::
+
--
(Optional, <<time-units,time value>>)
Period for which the search and its results are stored on the cluster. Defaults
to `5d` (five days).

When this period expires, the search and its results are deleted, even if the
search is still ongoing.

If the <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter is
`false`, {es} only stores <<eql-search-async,async searches>> that do not
complete within the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter, regardless of this value.

[IMPORTANT]
====
You can also specify this value using the `keep_alive` request body parameter.
If both parameters are specified, only the query parameter is used.
====
--

`keep_on_completion`::
+
--
(Optional, boolean)
If `true`, the search and its results are stored on the cluster.

If `false`, the search and its results are stored on the cluster only if the
request does not complete during the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter. Defaults to `false`.

[IMPORTANT]
====
You can also specify this value using the `keep_on_completion` request body
parameter. If both parameters are specified, only the query parameter is used.
====
--

`wait_for_completion_timeout`::
+
--
(Optional, <<time-units,time value>>)
Timeout duration to wait for the request to finish. Defaults to no
timeout, meaning the request waits for complete search results.

If this parameter is specified and the request completes during this period,
complete search results are returned.

If the request does not complete during this period, the search becomes an
<<eql-search-async,async search>>.

[IMPORTANT]
====
You can also specify this value using the `wait_for_completion_timeout` request
body parameter. If both parameters are specified, only the query parameter is
used.
====
--

[[eql-search-api-request-body]]
==== {api-request-body-title}

`event_category_field`::
(Required*, string)
Field containing the event classification, such as `process`, `file`, or
`network`.
+
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 must be mapped as a field type in the
<<keyword,`keyword`>> family.

`fetch_size`::
(Optional, integer)
Maximum number of events to search at a time for sequence queries. Defaults to
`1000`.
+
This value must be greater than `2` but cannot exceed the value of the
<<index-max-result-window,`index.max_result_window`>> setting, which defaults to
`10000`.
+
Internally, a sequence query fetches and paginates sets of events to search for
matches. This parameter controls the size of those sets. This parameter does not
limit the total number of events searched or the number of matching events
returned.
+
A greater `fetch_size` value often increases search speed but uses more memory.

`filter`::
(Optional, <<query-dsl,query DSL object>>)
Query, written in query DSL, used to filter the events on which the EQL query
runs.

`keep_alive`::
+
--
(Optional, <<time-units,time value>>)
Period for which the search and its results are stored on the cluster. Defaults
to `5d` (five days).

When this period expires, the search and its results are deleted, even if the
search is still ongoing.

If the <<eql-search-api-keep-on-completion,`keep_on_completion`>> parameter is
`false`, {es} only stores <<eql-search-async,async searches>> that do not
complete within the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter, regardless of this value.

[IMPORTANT]
====
You can also specify this value using the `keep_alive` query parameter.
If both parameters are specified, only the query parameter is used.
====
--

[[eql-search-api-keep-on-completion]]
`keep_on_completion`::
+
--
(Optional, boolean)
If `true`, the search and its results are stored on the cluster.

If `false`, the search and its results are stored on the cluster only if the
request does not complete during the period set by the
<<eql-search-api-wait-for-completion-timeout,`wait_for_completion_timeout`>>
parameter. Defaults to `false`.

[IMPORTANT]
====
You can also specify this value using the `keep_on_completion` query parameter.
If both parameters are specified, only the query parameter is used.
====
--

[[eql-search-api-request-query-param]]
`query`::
(Required, string)
<<eql-syntax,EQL>> query you wish to run.

`size`::
(Optional, integer or float)
For <<eql-basic-syntax,basic queries>>, the maximum number of matching events to
return.
+
For <<eql-sequences,sequence queries>>, the maximum number of matching sequences
to return.
+
Defaults to `10`. This value must be greater than `0`.
+
NOTE: You cannot use <<eql-pipe-ref,pipes>>, such as `head` or `tail`, to exceed
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.

[[eql-search-api-timestamp-field]]
`timestamp_field`::
+
--
(Required*, string)
Field containing event timestamp.

Defaults to `@timestamp`, as defined in the
{ecs-ref}/ecs-event.html[Elastic Common Schema (ECS)]. If a data stream or index
does not contain the `@timestamp` field, this value is required.

Events in the API response are sorted by this field's value, converted to
milliseconds since the {wikipedia}/Unix_time[Unix epoch], in
ascending order.

The timestamp field should be mapped as a <<date,`date`>>. The
<<date_nanos,`date_nanos`>> field type is not supported.
--

[[eql-search-api-wait-for-completion-timeout]]
`wait_for_completion_timeout`::
+
--
(Optional, <<time-units,time value>>)
Timeout duration to wait for the request to finish. Defaults to no
timeout, meaning the request waits for complete search results.

If this parameter is specified and the request completes during this period,
complete search results are returned.

If the request does not complete during this period, the search becomes an
<<eql-search-async,async search>>.

[IMPORTANT]
====
You can also specify this value using the `wait_for_completion_timeout` query
parameter. If both parameters are specified, only the query parameter is used.
====
--

[role="child_attributes"]
[[eql-search-api-response-body]]
==== {api-response-body-title}

[[eql-search-api-response-body-search-id]]
`id`::
+
--
(string)
Identifier for the search.

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`.

You can use this ID with the <<get-async-eql-search-api,get async EQL search
API>> to get the current status and available results for the search.
--

`is_partial`::
(boolean)
If `true`, the response does not contain complete search results.

`is_running`::
+
--
(boolean)
If `true`, the search request is still executing.

[IMPORTANT]
====
If this parameter and the `is_partial` parameter are `true`, the search is an
<<eql-search-async,ongoing async search>>. If the `keep_alive` period does not
pass, the complete search results will be available when the search completes.

If `is_partial` is `true` but `is_running` is `false`, the search returned
partial results due to a failure. Only some shards returned results or the node
coordinating the search failed.
====
--

`took`::
+
--
(integer)
Milliseconds it took {es} to execute the request.

This value is calculated by measuring the time elapsed
between receipt of a request on the coordinating node
and the time at which the coordinating node is ready to send the response.

Took time includes:

* Communication time between the coordinating node and data nodes
* Time the request spends in the `search` <<modules-threadpool,thread pool>>,
  queued for execution
* Actual execution time

Took time does *not* include:

* Time needed to send the request to {es}
* Time needed to serialize the JSON response
* Time needed to send the response to a client
--

`timed_out`::
(boolean)
If `true`, the request timed out before completion.

`hits`::
(object)
Contains matching events and sequences. Also contains related metadata.
+
.Properties of `hits`
[%collapsible%open]
====

`total`::
(object)
Metadata about the number of matching events or sequences.
+
.Properties of `total`
[%collapsible%open]
=====

`value`::
(integer)
For <<eql-basic-syntax,basic queries>>, the total number of matching events.
+
For <<eql-sequences,sequence queries>>, the total number of matching sequences.

`relation`::
+
--
(string)
Indicates whether the number of events or sequences returned is accurate or a
lower bound.

Returned values are:

`eq`::: Accurate
`gte`::: Lower bound, including returned events or sequences
--
=====

`sequences`::
(array of objects)
Contains event sequences matching the query. Each object represents a
matching sequence. This parameter is only returned for EQL queries containing
a <<eql-sequences,sequence>>.
+
.Properties of `sequences` objects
[%collapsible%open]
=====
`join_keys`::
(array of values)
Shared field values used to constrain matches in the sequence. These are defined
using the <<eql-sequences,`by` keyword>> in the EQL query syntax.

`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
======
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_source`::
(object)
Original JSON body passed for the event at index time.
======
=====

[[eql-search-api-response-events]]
`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
=====
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_source`::
(object)
Original JSON body passed for the event at index time.
=====
====

[[eql-search-api-example]]
==== {api-examples-title}

[[eql-search-api-basic-query-ex]]
===== Basic query example

The following EQL search request searches for events with an `event.category` of
`process` that meet the following conditions:

* A `process.name` of `cmd.exe`
* An `process.pid` other than `2013`

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}
----
// TEST[setup:sec_logs]

The API returns the following response. Matching events in the `hits.events`
property are sorted by <<eql-search-api-timestamp-field,timestamp>>, converted
to milliseconds since the {wikipedia}/Unix_time[Unix epoch],
in ascending order.

If two or more events share the same timestamp, the
<<eql-search-api-tiebreaker-field,`tiebreaker_field`>> field is used to sort
the events in ascending, lexicographic order.

[source,console-result]
----
{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "events": [
      {
        "_index": "my-index-000001",
        "_id": "babI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-06T11:04:05.000Z",
          "event": {
            "category": "process",
            "id": "edwCRnyD",
            "sequence": 1
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      },
      {
        "_index": "my-index-000001",
        "_id": "b6bI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-07T11:06:07.000Z",
          "event": {
            "category": "process",
            "id": "cMyt5SZ2",
            "sequence": 3
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "babI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.0._id/]
// TESTRESPONSE[s/"_id": "b6bI3XMBI9IjHuIqU0S_"/"_id": $body.hits.events.1._id/]

[[eql-search-api-sequence-ex]]
===== Sequence query example

The following EQL search request matches a <<eql-sequences,sequence>> of events
that:

. Start with an event with:
+
--
* An `event.category` of `file`
* A `file.name` of `cmd.exe`
* An `process.pid` other than `2013`
--
. Followed by an event with:
+
--
* An `event.category` of `process`
* A `process.executable` that contains the substring `regsvr32`
--

These events must also share the same `process.pid` value.

[source,console]
----
GET /my-index-000001/_eql/search
{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}
----
// TEST[setup:sec_logs]

The API returns the following response. Matching sequences are included in the
`hits.sequences` property. The `hits.sequences.join_keys` property contains the
shared `process.pid` value for each matching event.

[source,console-result]
----
{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": "my-index-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": "my-index-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]
// TESTRESPONSE[s/"_id": "AtOJ4UjUBAAx3XR5kcCM"/"_id": $body.hits.sequences.0.events.0._id/]
// TESTRESPONSE[s/"_id": "OQmfCaduce8zoHT93o4H"/"_id": $body.hits.sequences.0.events.1._id/]


[DOCS] EQL: Fix hits param for sequences (#57410)

[role="xpack"]
[testenv="basic"]

[[eql-search-api]]
=== EQL search API
++++
<titleabbrev>EQL search</titleabbrev>
++++

experimental::[]

Returns search results for an <<eql,Event Query Language (EQL)>> query.

In {es}, EQL assumes each document in an index corresponds to an event.

////
[source,console]
----
PUT /my_index/_bulk?refresh
{"index":{"_index" : "my_index", "_id" : "1"}}
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "2"}}
{ "@timestamp": "2020-12-06T11:04:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "3"}}
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "4"}}
{ "@timestamp": "2020-12-07T11:07:08.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "5"}}
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
----
// TESTSETUP
////

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    process where process.name = "regsvr32.exe"
  """
}
----

[[eql-search-api-request]]
==== {api-request-title}

`GET /<index>/_eql/search`

`POST /<index>/_eql/search`

[[eql-search-api-prereqs]]
==== {api-prereq-title}

See <<eql-requirements,EQL requirements>>.

[[eql-search-api-limitations]]
===== Limitations

See <<eql-limitations,EQL limitations>>.

[[eql-search-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(Required, string)
Comma-separated list of index names or <<indices-aliases,index aliases>> used to
limit the request. Accepts wildcard expressions.
+
To search all indices, use `_all` or `*`.

[[eql-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

[[eql-search-api-request-body]]
==== {api-request-body-title}

`case_sensitive`::
(Optional, boolean)
If `true`, matching for the <<eql-search-api-request-query-param,EQL query>> is
case sensitive. Defaults to `false`.

`event_category_field`::
(Required*, string)
Field containing the event classification, such as `process`, `file`, or
`network`.
+
Defaults to `event.category`, as defined in the {ecs-ref}/ecs-event.html[Elastic
Common Schema (ECS)]. If an index does not contain the `event.category` field,
this value is required.

`filter`::
(Optional, <<query-dsl,query DSL object>>)
Query, written in query DSL, used to filter the events on which the EQL query
runs.

`implicit_join_key_field`::
(Optional, string)
Reserved for future use.

[[eql-search-api-request-query-param]]
`query`::
(Required, string)
<<eql-syntax,EQL>> query you wish to run.
+
IMPORTANT: This parameter supports a subset of EQL syntax. See
<<eql-unsupported-syntax>>.

`search_after`::
(Optional, string)
Reserved for future use.

`size`::
(Optional, integer or float)
Maximum number of matching events to return. Defaults to `50`. Values must be
greater than `0`.

[[eql-search-api-timestamp-field]]
`timestamp_field`::
+
--
(Required*, string)
Field containing event timestamp.

Defaults to `@timestamp`, as defined in the
{ecs-ref}/ecs-event.html[Elastic Common Schema (ECS)]. If an index does not
contain the `@timestamp` field, this value is required.

Events in the API response are sorted by this field's value, converted to
milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in
ascending order.
--

[role="child_attributes"]
[[eql-search-api-response-body]]
==== {api-response-body-title}

`took`::
+
--
(integer)
Milliseconds it took {es} to execute the request.

This value is calculated by measuring the time elapsed
between receipt of a request on the coordinating node
and the time at which the coordinating node is ready to send the response.

Took time includes:

* Communication time between the coordinating node and data nodes
* Time the request spends in the `search` <<modules-threadpool,thread pool>>,
  queued for execution
* Actual execution time

Took time does *not* include:

* Time needed to send the request to {es}
* Time needed to serialize the JSON response
* Time needed to send the response to a client
--

`timed_out`::
(boolean)
If `true`, the request timed out before completion.

`hits`::
(object)
Contains matching events and sequences. Also contains related metadata.
+
.Properties of `hits`
[%collapsible%open]
====

`total`::
(object)
Metadata about the number of matching events or sequences.
+
.Properties of `total`
[%collapsible%open]
=====

`value`::
(integer)
For <<eql-basic-syntax,basic queries>>, the total number of matching events.
+
For <<eql-sequences,sequence queries>>, the total number of matching sequences.

`relation`::
+
--
(string)
Indicates whether the number of events or sequences returned is accurate or a
lower bound.

Returned values are:

`eq`::: Accurate
`gte`::: Lower bound, including returned events or sequences
--
=====

`sequences`::
(array of objects)
Contains event sequences matching the query. Each object represents a
matching sequence. This parameter is only returned for EQL queries containing
a <<eql-sequences,sequence>>.
+
.Properties of `sequences` objects
[%collapsible%open]
=====
`join_keys`::
(array of strings)
Shared field values used to constrain matches in the sequence. These are defined
using the <<eql-sequences,`by` keyword>> in the EQL query syntax.

`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
======
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_score`::
(float)
Positive 32-bit floating point number used to determine the relevance of the
 event. See <<relevance-scores>>.

`_source`::
(object)
Original JSON body passed for the event at index time.

`sort`::
(array)
Integer used as the sort value for the event.
+
By default, this is the event's <<eql-search-api-timestamp-field,timestamp
value>>, converted to milliseconds since the
https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
======
=====

[[eql-search-api-response-events]]
`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
=====
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_score`::
(float)
Positive 32-bit floating point number used to determine the relevance of the
 event. See <<relevance-scores>>.

`_source`::
(object)
Original JSON body passed for the event at index time.

`sort`::
(array)
Integer used as the sort value for the event.
+
By default, this is the event's <<eql-search-api-timestamp-field,timestamp
value>>, converted to milliseconds since the
https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
=====
====

[[eql-search-api-example]]
==== {api-examples-title}

[[eql-search-api-basic-query-ex]]
===== Basic query example

The following EQL search request searches for events with an `event.category` of
`file` that meet the following conditions:

* A `file.name` of `cmd.exe`
* An `agent.id` other than `my_user`

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    file where (file.name == "cmd.exe" and agent.id != "my_user")
  """
}
----

The API returns the following response. Matching events in the `hits.events`
property are sorted by <<eql-search-api-timestamp-field,timestamp>>, converted
to milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
in ascending order.

[source,console-result]
----
{
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "events": [
      {
        "_index": "my_index",
        "_id": "2",
        "_score": null,
        "_source": {
          "@timestamp": "2020-12-06T11:04:07.000Z",
          "agent": {
            "id": "8a4f500d"
          },
          "event": {
            "category": "file"
          },
          "file": {
            "accessed": "2020-12-07T11:07:08.000Z",
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe",
            "type": "file",
            "size": 16384
          },
          "process": {
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe"
          }
        },
        "sort": [
          1607252647000
        ]
      },
      {
        "_index": "my_index",
        "_id": "4",
        "_score": null,
        "_source": {
          "@timestamp": "2020-12-07T11:07:08.000Z",
          "agent": {
            "id": "8a4f500d"
          },
          "event": {
            "category": "file"
          },
          "file": {
            "accessed": "2020-12-07T11:07:08.000Z",
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe",
            "type": "file",
            "size": 16384
          },
          "process": {
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe"
          }
        },
        "sort": [
          1607339228000
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]

[[eql-search-api-sequence-ex]]
===== Sequence query example

The following EQL search request matches a <<eql-sequences,sequence>> of events
that:

. Start with an event with:
+
--
* An `event.category` of `file`
* A `file.name` of `cmd.exe`
* An `agent.id` other than `my_user`
--
. Followed by an event with:
+
--
* An `event.category` of `process`
* A `process.path` that contains the substring `regsvr32`
--

These events must also share the same `agent.id` value.

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    sequence by agent.id
      [ file where file.name == "cmd.exe" and agent.id != "my_user" ]
      [ process where stringContains(process.path, "regsvr32") ]
  """
}
----

The API returns the following response. The `hits.sequences.join_keys` property
contains the shared `agent.id` value for each matching event. Matching events in
the `hits.sequences.events` property are sorted by
<<eql-search-api-timestamp-field,timestamp>>, converted to milliseconds since
the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.

[source,console-result]
----
{
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          "8a4f500d"
        ],
        "events": [
          {
            "_index": "my_index",
            "_id": "4",
            "_score": null,
            "_source": {
              "@timestamp": "2020-12-07T11:07:08.000Z",
              "agent": {
                "id": "8a4f500d"
              },
              "event": {
                "category": "file"
              },
              "file": {
                "accessed": "2020-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe"
              }
            },
            "fields": {
              "@timestamp": [
                "1607339228000"
              ]
            },
            "sort": [
              1607339228000
            ]
          },
          {
            "_index": "my_index",
            "_id": "5",
            "_score": null,
            "_source": {
              "@timestamp": "2020-12-07T11:07:09.000Z",
              "agent": {
                "id": "8a4f500d"
              },
              "event": {
                "category": "process"
              },
              "process": {
                "name": "regsvr32.exe",
                "path": "C:\\Windows\\System32\\regsvr32.exe"
              }
            },
            "fields": {
              "@timestamp": [
                "1607339229000"
              ]
            },
            "sort": [
              1607339229000
            ]
          }
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]

[role="xpack"]
[testenv="basic"]

[[eql-search-api]]
=== EQL search API
++++
<titleabbrev>EQL search</titleabbrev>
++++

experimental::[]

Returns search results for an <<eql,Event Query Language (EQL)>> query.

In {es}, EQL assumes each document in an index corresponds to an event.

////
[source,console]
----
PUT /my_index/_bulk?refresh
{"index":{"_index" : "my_index", "_id" : "1"}}
{ "@timestamp": "2020-12-06T11:04:05.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "2"}}
{ "@timestamp": "2020-12-06T11:04:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "3"}}
{ "@timestamp": "2020-12-07T11:06:07.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "4"}}
{ "@timestamp": "2020-12-07T11:07:08.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "file" }, "file": { "accessed": "2020-12-07T11:07:08.000Z", "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe", "type": "file", "size": 16384 }, "process": { "name": "cmd.exe", "path": "C:\\Windows\\System32\\cmd.exe" } }
{"index":{"_index" : "my_index", "_id" : "5"}}
{ "@timestamp": "2020-12-07T11:07:09.000Z", "agent": { "id": "8a4f500d" }, "event": { "category": "process" }, "process": { "name": "regsvr32.exe", "path": "C:\\Windows\\System32\\regsvr32.exe" } }
----
// TESTSETUP
////

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    process where process.name = "regsvr32.exe"
  """
}
----

[[eql-search-api-request]]
==== {api-request-title}

`GET /<index>/_eql/search`

`POST /<index>/_eql/search`

[[eql-search-api-prereqs]]
==== {api-prereq-title}

See <<eql-requirements,EQL requirements>>.

[[eql-search-api-limitations]]
===== Limitations

See <<eql-limitations,EQL limitations>>.

[[eql-search-api-path-params]]
==== {api-path-parms-title}

`<index>`::
(Required, string)
Comma-separated list of index names or <<indices-aliases,index aliases>> used to
limit the request. Accepts wildcard expressions.
+
To search all indices, use `_all` or `*`.

[[eql-search-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `false`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

[[eql-search-api-request-body]]
==== {api-request-body-title}

`case_sensitive`::
(Optional, boolean)
If `true`, matching for the <<eql-search-api-request-query-param,EQL query>> is
case sensitive. Defaults to `false`.

`event_category_field`::
(Required*, string)
Field containing the event classification, such as `process`, `file`, or
`network`.
+
Defaults to `event.category`, as defined in the {ecs-ref}/ecs-event.html[Elastic
Common Schema (ECS)]. If an index does not contain the `event.category` field,
this value is required.

`filter`::
(Optional, <<query-dsl,query DSL object>>)
Query, written in query DSL, used to filter the events on which the EQL query
runs.

`implicit_join_key_field`::
(Optional, string)
Reserved for future use.

[[eql-search-api-request-query-param]]
`query`::
(Required, string)
<<eql-syntax,EQL>> query you wish to run.
+
IMPORTANT: This parameter supports a subset of EQL syntax. See
<<eql-unsupported-syntax>>.

`search_after`::
(Optional, string)
Reserved for future use.

`size`::
(Optional, integer or float)
Maximum number of matching events to return. Defaults to `50`. Values must be
greater than `0`.

[[eql-search-api-timestamp-field]]
`timestamp_field`::
+
--
(Required*, string)
Field containing event timestamp.

Defaults to `@timestamp`, as defined in the
{ecs-ref}/ecs-event.html[Elastic Common Schema (ECS)]. If an index does not
contain the `@timestamp` field, this value is required.

Events in the API response are sorted by this field's value, converted to
milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in
ascending order.
--

[role="child_attributes"]
[[eql-search-api-response-body]]
==== {api-response-body-title}

`took`::
+
--
(integer)
Milliseconds it took {es} to execute the request.

This value is calculated by measuring the time elapsed
between receipt of a request on the coordinating node
and the time at which the coordinating node is ready to send the response.

Took time includes:

* Communication time between the coordinating node and data nodes
* Time the request spends in the `search` <<modules-threadpool,thread pool>>,
  queued for execution
* Actual execution time

Took time does *not* include:

* Time needed to send the request to {es}
* Time needed to serialize the JSON response
* Time needed to send the response to a client
--

`timed_out`::
(boolean)
If `true`, the request timed out before completion.

`hits`::
(object)
Contains matching events and metadata.
+
.Properties of `hits`
[%collapsible%open]
====

`total`::
(object)
Metadata about the number of matching events.
+
.Properties of `total`
[%collapsible%open]
=====

`value`::
(integer)
Total number of matching events.

`relation`::
+
--
(string)
Indicates whether the number of events returned is accurate or a lower bound.

Returned values are:

`eq`::: Accurate
`gte`::: Lower bound, including returned events
--
=====

`sequences`::
(array of objects)
Contains event sequences matching the query. Each object represents a
matching sequence. This parameter is only returned for EQL queries containing
a <<eql-sequences,sequence>>.
+
.Properties of `sequences` objects
[%collapsible%open]
=====
`join_keys`::
(array of strings)
Shared field values used to constrain matches in the sequence. These are defined
using the <<eql-sequences,`by` keyword>> in the EQL query syntax.

`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
======
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_score`::
(float)
Positive 32-bit floating point number used to determine the relevance of the
 event. See <<relevance-scores>>.

`_source`::
(object)
Original JSON body passed for the event at index time.

`sort`::
(array)
Integer used as the sort value for the event.
+
By default, this is the event's <<eql-search-api-timestamp-field,timestamp
value>>, converted to milliseconds since the
https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
======
=====

[[eql-search-api-response-events]]
`events`::
(array of objects)
Contains events matching the query. Each object represents a
matching event.
+
.Properties of `events` objects
[%collapsible%open]
=====
`_index`::
(string)
Name of the index containing the event.

`_id`::
(string)
(string)
Unique identifier for the event.
This ID is only unique within the index.

`_score`::
(float)
Positive 32-bit floating point number used to determine the relevance of the
 event. See <<relevance-scores>>.

`_source`::
(object)
Original JSON body passed for the event at index time.

`sort`::
(array)
Integer used as the sort value for the event.
+
By default, this is the event's <<eql-search-api-timestamp-field,timestamp
value>>, converted to milliseconds since the
https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
=====
====

[[eql-search-api-example]]
==== {api-examples-title}

[[eql-search-api-basic-query-ex]]
===== Basic query example

The following EQL search request searches for events with an `event.category` of
`file` that meet the following conditions:

* A `file.name` of `cmd.exe`
* An `agent.id` other than `my_user`

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    file where (file.name == "cmd.exe" and agent.id != "my_user")
  """
}
----

The API returns the following response. Matching events in the `hits.events`
property are sorted by <<eql-search-api-timestamp-field,timestamp>>, converted
to milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
in ascending order.

[source,console-result]
----
{
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "events": [
      {
        "_index": "my_index",
        "_id": "2",
        "_score": null,
        "_source": {
          "@timestamp": "2020-12-06T11:04:07.000Z",
          "agent": {
            "id": "8a4f500d"
          },
          "event": {
            "category": "file"
          },
          "file": {
            "accessed": "2020-12-07T11:07:08.000Z",
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe",
            "type": "file",
            "size": 16384
          },
          "process": {
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe"
          }
        },
        "sort": [
          1607252647000
        ]
      },
      {
        "_index": "my_index",
        "_id": "4",
        "_score": null,
        "_source": {
          "@timestamp": "2020-12-07T11:07:08.000Z",
          "agent": {
            "id": "8a4f500d"
          },
          "event": {
            "category": "file"
          },
          "file": {
            "accessed": "2020-12-07T11:07:08.000Z",
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe",
            "type": "file",
            "size": 16384
          },
          "process": {
            "name": "cmd.exe",
            "path": "C:\\Windows\\System32\\cmd.exe"
          }
        },
        "sort": [
          1607339228000
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]

[[eql-search-api-sequence-ex]]
===== Sequence query example

The following EQL search request matches a <<eql-sequences,sequence>> of events
that:

. Start with an event with:
+
--
* An `event.category` of `file`
* A `file.name` of `cmd.exe`
* An `agent.id` other than `my_user`
--
. Followed by an event with:
+
--
* An `event.category` of `process`
* A `process.path` that contains the substring `regsvr32`
--

These events must also share the same `agent.id` value.

[source,console]
----
GET /my_index/_eql/search
{
  "query": """
    sequence by agent.id
      [ file where file.name == "cmd.exe" and agent.id != "my_user" ]
      [ process where stringContains(process.path, "regsvr32") ]
  """
}
----

The API returns the following response. The `hits.sequences.join_keys` property
contains the shared `agent.id` value for each matching event. Matching events in
the `hits.sequences.events` property are sorted by
<<eql-search-api-timestamp-field,timestamp>>, converted to milliseconds since
the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.

[source,console-result]
----
{
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          "8a4f500d"
        ],
        "events": [
          {
            "_index": "my_index",
            "_id": "4",
            "_score": null,
            "_source": {
              "@timestamp": "2020-12-07T11:07:08.000Z",
              "agent": {
                "id": "8a4f500d"
              },
              "event": {
                "category": "file"
              },
              "file": {
                "accessed": "2020-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe"
              }
            },
            "fields": {
              "@timestamp": [
                "1607339228000"
              ]
            },
            "sort": [
              1607339228000
            ]
          },
          {
            "_index": "my_index",
            "_id": "5",
            "_score": null,
            "_source": {
              "@timestamp": "2020-12-07T11:07:09.000Z",
              "agent": {
                "id": "8a4f500d"
              },
              "event": {
                "category": "process"
              },
              "process": {
                "name": "regsvr32.exe",
                "path": "C:\\Windows\\System32\\regsvr32.exe"
              }
            },
            "fields": {
              "@timestamp": [
                "1607339229000"
              ]
            },
            "sort": [
              1607339229000
            ]
          }
        ]
      }
    ]
  }
}
----
// TESTRESPONSE[s/"took": 6/"took": $body.took/]


Adding more documentation on scaling threadpools

[[modules-threadpool]]
== Thread Pool

A node holds several thread pools in order to improve how threads memory consumption
are managed within a node. Many of these pools also have queues associated with them,
which allow pending requests to be held instead
of discarded.

There are several thread pools, but the important ones include:

`index`::
    For index/delete operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `200`.

`search`::
    For count/search operations. Defaults to `fixed`
    with a size of `3x # of available processors`,
    queue_size of `1000`.

`suggest`::
    For suggest operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`get`::
    For get operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`bulk`::
    For bulk operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `50`.

`percolate`::
    For percolate operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`snapshot`::
    For snapshot/restore operations. Defaults to `scaling` with a
    keep-alive of `5m` and a size of `min(5, (# of available processors)/2)`.

`warmer`::
    For segment warm-up operations. Defaults to `scaling` with a
    keep-alive of `5m` and a size of `min(5, (# of available processors)/2)`.

`refresh`::
    For refresh operations. Defaults to `scaling` with a
    keep-alive of `5m` and a size of `min(10, (# of available processors)/2)`.

`listener`::
    Mainly for java client executing of action when listener threaded is set to true.
    Default size of `(# of available processors)/2`, max at 10.

Changing a specific thread pool can be done by setting its type and
specific type parameters, for example, changing the `index` thread pool
to have more threads:

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: fixed
        size: 30
--------------------------------------------------

NOTE: you can update threadpool settings live using
      <<cluster-update-settings>>.

[float]
[[types]]
=== Thread pool types

The following are the types of thread pools that can be used and their
respective parameters:

[float]
==== `cache`

The `cache` thread pool is an unbounded thread pool that will spawn a
thread if there are pending requests. Here is an example of how to set
it:

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: cached
--------------------------------------------------

[float]
==== `fixed`

The `fixed` thread pool holds a fixed size of threads to handle the
requests with a queue (optionally bounded) for pending requests that
have no threads to service them.

The `size` parameter controls the number of threads, and defaults to the
number of cores times 5.

The `queue_size` allows to control the size of the queue of pending
requests that have no threads to execute them. By default, it is set to
`-1` which means its unbounded. When a request comes in and the queue is
full, it will abort the request.

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: fixed
        size: 30
        queue_size: 1000
--------------------------------------------------

[float]
==== `scaling`

The `scaling` thread pool holds a dynamic number of threads. This number is
proportional to the workload and varies between 1 and the value of the
`size` parameter.

The `keep_alive` parameter determines how long a thread should be kept
around in the thread pool without it doing any work.

[source,js]
--------------------------------------------------
threadpool:
    warmer:
        type: scaling
        size: 8
        keep_alive: 2m
--------------------------------------------------

[float]
[[processors]]
=== Processors setting
The number of processors is automatically detected, and the thread pool
settings are automatically set based on it. Sometimes, the number of processors
are wrongly detected, in such cases, the number of processors can be
explicitly set using the `processors` setting.

In order to check the number of processors detected, use the nodes info
API with the `os` flag.

[[modules-threadpool]]
== Thread Pool

A node holds several thread pools in order to improve how threads memory consumption
are managed within a node. Many of these pools also have queues associated with them,
which allow pending requests to be held instead
of discarded.

There are several thread pools, but the important ones include:

`index`::
    For index/delete operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `200`.

`search`::
    For count/search operations. Defaults to `fixed`
    with a size of `3x # of available processors`,
    queue_size of `1000`.

`suggest`::
    For suggest operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`get`::
    For get operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`bulk`::
    For bulk operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `50`.

`percolate`::
    For percolate operations. Defaults to `fixed`
    with a size of `# of available processors`,
    queue_size of `1000`.

`snapshot`::
    For snapshot/restore operations. Defaults to `scaling`,
    keep-alive `5m` with a size of `(# of available processors)/2`.

`warmer`::
    For segment warm-up operations. Defaults to `scaling`
    with a `5m` keep-alive.

`refresh`::
    For refresh operations. Defaults to `scaling`
    with a `5m` keep-alive.

`listener`::
    Mainly for java client executing of action when listener threaded is set to true.
    Default size of `(# of available processors)/2`, max at 10.

Changing a specific thread pool can be done by setting its type and
specific type parameters, for example, changing the `index` thread pool
to have more threads:

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: fixed
        size: 30
--------------------------------------------------

NOTE: you can update threadpool settings live using
      <<cluster-update-settings>>.

[float]
[[types]]
=== Thread pool types

The following are the types of thread pools that can be used and their
respective parameters:

[float]
==== `cache`

The `cache` thread pool is an unbounded thread pool that will spawn a
thread if there are pending requests. Here is an example of how to set
it:

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: cached
--------------------------------------------------

[float]
==== `fixed`

The `fixed` thread pool holds a fixed size of threads to handle the
requests with a queue (optionally bounded) for pending requests that
have no threads to service them.

The `size` parameter controls the number of threads, and defaults to the
number of cores times 5.

The `queue_size` allows to control the size of the queue of pending
requests that have no threads to execute them. By default, it is set to
`-1` which means its unbounded. When a request comes in and the queue is
full, it will abort the request.

[source,js]
--------------------------------------------------
threadpool:
    index:
        type: fixed
        size: 30
        queue_size: 1000
--------------------------------------------------

[float]
[[processors]]
=== Processors setting
The number of processors is automatically detected, and the thread pool
settings are automatically set based on it. Sometimes, the number of processors
are wrongly detected, in such cases, the number of processors can be
explicitly set using the `processors` setting.

In order to check the number of processors detected, use the nodes info
API with the `os` flag.