Get EQL search results

  • POST also GET /{index}/_eql/search
Auth

Returns search results for an Event Query Language (EQL) query. EQL assumes each document in a data stream or index corresponds to an event.

Read the reference documentation

Path parameters

index union string | string[] required

Comma-separated list of index names to scope the operation

Query parameters

allow_no_indices boolean · default: true

Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes _all string or when no indices have been specified)

allow_partial_search_results boolean · default: false

If true, returns partial results if there are shard failures. If false, returns an error with no partial results.

allow_partial_sequence_results boolean · default: false

If true, sequence queries will return partial results in case of shard failures. If false, they will return no results at all. This flag has effect only if allow_partial_search_results is true.

expand_wildcards union oneOf · default: open

Whether to expand wildcard expression to concrete indices that are open, closed or both.

Supported values include:

  • all: Match any data stream or index, including hidden ones.
  • open: Match open, non-hidden indices. Also matches any non-hidden data stream.
  • closed: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  • hidden: Match hidden data streams and hidden indices. Must be combined with open, closed, or both.
  • none: Wildcard expressions are not accepted.
Values: all open closed hidden none
ccs_minimize_roundtrips boolean · default: true

Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution

ignore_unavailable boolean · default: true

If true, missing or closed indices are not included in the response.

keep_alive string · default: 5d

Period for which the search and its results are stored on the cluster.

keep_on_completion boolean · default: false

If true, the search and its results are stored on the cluster.

wait_for_completion_timeout string

Timeout duration to wait for the request to finish. Defaults to no timeout, meaning the request waits for complete search results.

Reference

Request body

query string required

EQL query you wish to run.

case_sensitive boolean
event_category_field string · default: event.category

Field containing the event classification, such as process, file, or network.

tiebreaker_field string

Field used to sort hits with the same timestamp in ascending order

timestamp_field string · default: @timestamp

Field containing event timestamp.

fetch_size number · default: 1000

Maximum number of events to search at a time for sequence queries.

filter union oneOf

Query, written in Query DSL, used to filter the events on which the EQL query runs.

One of: Query[] or Query
keep_alive string
keep_on_completion boolean
wait_for_completion_timeout string
allow_partial_search_results boolean · default: true

Allow query execution also in case of shard failures. If true, the query will keep running and will return results based on the available shards. For sequences, the behavior can be further refined using allow_partial_sequence_results

allow_partial_sequence_results boolean · default: false

This flag applies only to sequences and has effect only if allow_partial_search_results=true. If true, the sequence query will return results based on the available shards, ignoring the others. If false, the sequence query will return successfully, but will always have empty results.

size number

For basic queries, the maximum number of matching events to return. Defaults to 10

fields union oneOf

Array of wildcard (*) patterns. The response returns values for field names matching these patterns in the fields property of each hit.

object or object[]
field string required

A wildcard pattern. The request returns values for field names matching this pattern.

format string

The format in which the values are returned.

include_unmapped boolean
result_position enum · default: tail

Supported values include:

  • tail: Return the most recent matches, similar to the Unix tail command.
  • head: Return the earliest matches, similar to the Unix head command.
Values: tail head
runtime_mappings object
max_samples_per_key number · default: 1

By default, the response of a sample query contains up to 10 samples, with one sample per unique set of join keys. Use the size parameter to get a smaller or larger set of samples. To retrieve more than one sample per set of join keys, use the max_samples_per_key parameter. Pipes are not supported for sample queries.

Response

application/json
id string

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

took number

Milliseconds it took Elasticsearch to execute the request.

timed_out boolean

If true, the request timed out before completion.

hits object required

Contains matching events and sequences. Also contains related metadata.

total object

Metadata about the number of matching events or sequences.

relation enum required

Supported values include:

  • eq: Accurate
  • gte: Lower bound, including returned events or sequences
Values: eq gte
value number required
events object[]

Contains events matching the query. Each object represents a matching event.

_index string required

Name of the index containing the event.

_id string required

Unique identifier for the event. This ID is only unique within the index.

_source object required

Original JSON body passed for the event at index time.

missing boolean

Set to true for events in a timespan-constrained sequence that do not meet a given condition.

fields map string to object
sequences object[]

Contains event sequences matching the query. Each object represents a matching sequence. This parameter is only returned for EQL queries containing a sequence.

events object[] required

Contains events matching the query. Each object represents a matching event.

_index string required

Name of the index containing the event.

_id string required

Unique identifier for the event. This ID is only unique within the index.

_source object required

Original JSON body passed for the event at index time.

missing boolean

Set to true for events in a timespan-constrained sequence that do not meet a given condition.

fields map string to object
join_keys object[]

Shared field values used to constrain matches in the sequence. These are defined using the by keyword in the EQL query syntax.

shard_failures object[]

Contains information about shard failures (if any), in case allow_partial_search_results=true

index string
node string
reason object required
type string required

The type of error

reason union string nullable

A human-readable explanation of the error, in English.

One of: string
stack_trace string

The server stack trace. Present only if the error_trace=true parameter was sent with the request.

caused_by object
Same fields as reason in shard_failures
root_cause object[]
Same fields as reason in shard_failures
suppressed object[]
Same fields as reason in shard_failures
shard number
status string
primary boolean