Get EQL search results

POST also GET /{index}/_eql/search

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

Learn more about EQL

Path Parameters

index union IndexName | [] IndexName required: Comma-separated list of index names to scope the operation

Query Parameters

allow_no_indices boolean · default: true

A setting that does two separate checks on the index expression. If false, the request returns an error (1) if any wildcard expression (including _all and *) resolves to zero matching indices or (2) if the complete set of resolved indices, aliases or data streams is empty after all expressions are evaluated. If true, index expressions that resolve to no indices are allowed and the request returns an empty result.

allow_partial_search_results boolean · default: true

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 string ExpandWildcards · 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 false, the request returns an error if it targets a concrete (non-wildcarded) index, alias, or data stream that is missing, closed, or otherwise unavailable. If true, unavailable concrete targets are silently ignored.

keep_alive string Duration · 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 Duration

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

Request

query string required: EQL query you wish to run.
case_sensitive boolean
event_category_field string Field · default: event.category: Field containing the event classification, such as process, file, or network.
tiebreaker_field string Field: Field used to sort hits with the same timestamp in ascending order
timestamp_field string Field · default: @timestamp: Field containing event timestamp.
fetch_size number uint · 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: QueryContainer[] or QueryContainer
keep_alive string Duration
keep_on_completion boolean
wait_for_completion_timeout string Duration
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 uint: 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.; FieldAndFormat or FieldAndFormat[]
result_position enum ResultPosition · 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 RuntimeFields
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

Examples

Run POST /my-data-stream/_eql/search to search for events that have a process.name of cmd.exe and a process.pid other than 2013.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /my-data-stream/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

JavaScript Elasticsearch JavaScript Client

const response = await client.eql.search({
  index: "my-data-stream",
  query:
    '\n    process where (process.name == "cmd.exe" and process.pid != 2013)\n  ',
});

Python Elasticsearch Python Client

resp = client.eql.search(
    index="my-data-stream",
    query="\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-data-stream/_eql/search" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "\n    process where (process.name == \u0022cmd.exe\u0022 and process.pid != 2013)\n  "
  }'

Java Elasticsearch Java Client

client.eql().search(s -> s
    .index("my-data-stream")
    .query("""
        
    process where (process.name == "cmd.exe" and process.pid != 2013)
  
        """)
);

C# Elasticsearch .NET Client

var response = await client.Eql
    .SearchAsync<MyDocument, MyDocument>(indices: new[] { "my-data-stream" }, d1 => d1
        .Query("\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ")
    );

PHP Elasticsearch PHP Client

$resp = $client->eql()->search([
    "index" => "my-data-stream",
    "body" => [
        "query" => "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  ",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.eql.search(
  index: "my-data-stream",
  body: {
    "query": "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  }
)

Response

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-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": ".ds-my-data-stream-2099.12.07-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"
              }
            }
          }
        ]
      }
    ]
  }
}

Run POST /my-data-stream/_eql/search to search for a sequence of events. The sequence starts with an event with an event.category of file, a file.name of cmd.exe, and a process.pid other than 2013. It is followed by an event with an event.category of process and a process.executable that contains the substring regsvr32. These events must also share the same process.pid value.

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST /my-data-stream/_eql/search
{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

curl Shell

curl -X POST "$ELASTICSEARCH_URL/my-data-stream/_eql/search" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}'

Response

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-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": ".ds-my-data-stream-2099.12.07-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"
              }
            }
          }
        ]
      }
    ]
  }
}

Path Parameters

Query Parameters { allow_no_indices , allow_partial_search_results , allow_partial_sequence_results , expand_wildcards , ccs_minimize_roundtrips , ignore_unavailable , keep_alive , keep_on_completion , wait_for_completion_timeout , }

Response

Query Parameters