› › ›

API поиска EQL

Возвращает результаты поиска для запроса Языка запросов событий (EQL).

EQL предполагает, что каждый документ в потоке данных или индексе соответствует событию.

resp = client.eql.search(
    index="my-data-stream",
    query="\n    process where process.name == \"regsvr32.exe\"\n  ",
)
print(resp)

response = client.eql.search(
  index: 'my-data-stream',
  body: {
    query: "\n    process where process.name == \"regsvr32.exe\"\n  "
  }
)
puts response

const response = await client.eql.search({
  index: "my-data-stream",
  query: '\n    process where process.name == "regsvr32.exe"\n  ',
});
console.log(response);

GET /my-data-stream/_eql/search
{
  "query": """
    process where process.name == "regsvr32.exe"
  """
}

Запрос

GET /<target>/_eql/search

POST /<target>/_eql/search

Предварительные условия

Если включены функции безопасности Elasticsearch, у вас должна быть read разрешение на доступ к индексу для целевого потока данных, индекса или псевдонима.
См. Необходимые поля.
[preview] Данная функция находится в техническом предварительном просмотре и может быть изменена или удалена в будущих версиях. Elastic будет работать над устранением проблем, но функции предварительного просмотра не подпадают под SLA поддержки официальных функций GA. Для межкластерного поиска локальные и удалённые кластеры должны использовать одну и ту же версию Elasticsearch, если у них есть версии до 7.17.7 (включительно) или до 8.5.1 (включительно). Для безопасности см. Удаленные кластеры.

Ограничения

См. ограничения EQL.

Параметры пути

<target>

(Обязательно, строка) Список потоков данных, индексов или псевдонимов, разделённых запятыми, используемых для ограничения запроса. Поддерживаются подстановочные знаки (*). Для поиска всех потоков данных и индексов используйте * или _all.

[preview] Данная функция находится в техническом предварительном просмотре и может быть изменена или удалена в будущих версиях. Elastic будет работать над устранением проблем, но функции предварительного просмотра не подпадают под SLA поддержки официальных функций GA. Для поиска в удалённом кластере используйте синтаксис <cluster>:<target>. См. Выполнение поиска EQL по нескольким кластерам.

Параметры запроса

allow_no_indices

(Необязательно, логическое значение)

Поведение этого параметра отличается от параметра allow_no_indices, используемого в других многоцелевых API.

Если false, запрос возвращает ошибку, если какой-либо шаблон подстановки, псевдоним или _all значение относится только к отсутствующим или закрытым индексам. Это поведение применяется даже если запрос обращается к другим открытым индексам. Например, запрос, обращённый к foo*,bar*, возвращает ошибку, если индекс начинается с foo, но ни один индекс не начинается с bar.

Если true, ошибку возвращают только запросы, которые исключительно обращаются к отсутствующим или закрытым индексам. Например, запрос, обращённый к foo*,bar*, не возвращает ошибку, если индекс начинается с foo, но ни один индекс не начинается с bar. Однако запрос, обращённый только к bar*, всё равно возвращает ошибку.

По умолчанию true.

ccs_minimize_roundtrips

(Необязательно, логическое значение) Если true, сетевые обмены между локальным и удалённым кластером минимизируются при выполнении межкластерных запросов поиска (CCS).

Этот параметр эффективен для запросов, которые обращаются к данным, полностью находящимся в одном удалённом кластере; когда данные распределены по нескольким кластерам, настройка игнорируется.

По умолчанию true.

expand_wildcards

(Необязательно, строка) Тип индекса, с которым могут совпадать шаблоны подстановки. Если запрос может обращаться к данным потоков данных, этот аргумент определяет, совпадают ли подстановочные выражения с скрытыми потоками данных. Поддерживаются разделённые запятыми значения, такие как open,hidden. Допустимые значения:

all: Соответствует любому потоку данных или индексу, включая скрытые.
open: Совпадает с открытыми индексами, не являющимися скрытыми. Также соответствует любому открытому потоку данных, не являющемуся скрытым.
closed: Совпадает с закрытыми индексами, не являющимися скрытыми. Также соответствует любому закрытому потоку данных, не являющемуся скрытым. Потоки данных не могут быть закрыты.
hidden: Совпадает со скрытыми потоками данных и скрытыми индексами. Должен быть объединён с open, closed или обоими.
none: Шаблоны подстановки не принимаются.

По умолчанию open.

filter_path

(Необязательно, строка) Список фильтров для ответа API, разделённых запятыми. См. Фильтрация ответов.

ignore_unavailable

(Необязательно, логическое значение) Если false, запрос возвращает ошибку, если обращается к отсутствующему или закрытому индексу. По умолчанию true.

keep_alive

(Необязательно, значение времени) Период, в течение которого поиск и его результаты хранятся в кластере. По умолчанию 5d (пять дней).

По истечении этого периода поиск и его результаты удаляются, даже если поиск всё ещё выполняется.

Если параметр keep_on_completion равен false, Elasticsearch хранит только асинхронные поиски, которые не завершаются в течение периода, установленного параметром wait_for_completion_timeout, независимо от этого значения.

Вы также можете указать это значение с помощью параметра тела запроса keep_alive. Если оба параметра указаны, используется только параметр запроса.

keep_on_completion

(Необязательно, логическое значение) Если true, поиск и его результаты хранятся в кластере.

Если false, поиск и его результаты хранятся в кластере только в том случае, если запрос не завершается в течение периода, установленного параметром wait_for_completion_timeout. По умолчанию false.

Вы также можете указать это значение с помощью параметра тела запроса keep_on_completion. Если оба параметра указаны, используется только параметр запроса.

wait_for_completion_timeout

(Необязательно, значение времени) Длительность таймаута ожидания завершения запроса. По умолчанию нет таймаута, что означает, что запрос ожидает полных результатов поиска.

Если этот параметр указан и запрос завершается в течение этого периода, возвращаются полные результаты поиска.

Если запрос не завершается в течение этого периода, поиск становится асинхронным поиском.

Вы также можете указать это значение с помощью параметра тела запроса wait_for_completion_timeout. Если оба параметра указаны, используется только параметр запроса.

Тело запроса

event_category_field

(Обязательно*, строка) Поле, содержащее классификацию события, например process, file или network.

По умолчанию установлено значение event.category, как определено в Elastic Common Schema (ECS). Если поток данных или индекс не содержит поля event.category, это значение обязательно.

Поле категории событий должно быть отображено как тип поля в семействе keyword.

fetch_size

(Необязательно, целое число) Максимальное количество событий для поиска за один раз для запросов последовательности. По умолчанию значение 1000.

Это значение должно быть больше чем 2, но не может превышать значение параметра index.max_result_window, по умолчанию равного 10000.

Внутренне, запрос последовательности извлекает и страницирует наборы событий, чтобы искать совпадения. Этот параметр контролирует размер этих наборов. Этот параметр не ограничивает общее количество просматриваемых событий или количество возвращаемых совпадений.

Большее значение fetch_size часто увеличивает скорость поиска, но использует больше памяти.

fields

(Необязательно, массив строк и объектов) Массив шаблонов полей. Запрос возвращает значения для имён полей, соответствующих этим шаблонам в свойстве hits.fields ответа.

Вы можете указать элементы в массиве как строку или объект. См. параметр fields.

Свойства объектов fields

field

(Обязательно, строка) Поле для возврата. Поддерживает подстановки (*).

format

(Необязательно, строка) Формат для полей дат и геопространственных данных. Другие типы данных полей не поддерживают этот параметр.

Поля date и date_nanos принимают формат даты. Поля geo_point и geo_shape принимают:

geojson (по умолчанию)

GeoJSON

wkt

Well Known Text

mvt(<spec>)

Бинарный Mapbox векторный тайл. API возвращает тайл в виде строки base64. У <spec> формат <zoom>/<x>/<y> с двумя необязательными суффиксами: @<extent> и/или :<buffer>. Например, 2/0/1 или 2/0/1@4096:5.

mvt параметры

<zoom>: (Обязательно, целое число) Уровень масштабирования тайла. Принимает 0-29.
<x>: (Обязательно, целое число) Координата X тайла.
<y>: (Обязательно, целое число) Координата Y тайла.
<extent>: (Необязательно, целое число) Размер, в пикселях, стороны тайла. Векторные тайлы квадратные с равными сторонами. По умолчанию 4096.
<buffer>: (Необязательно, целое число) Размер, в пикселях, буфера обрезки за пределами тайла. Это позволяет рендерерам избегать артефактов контура геометрий, которые выходят за пределы области тайла. По умолчанию 5.

filter

(Необязательно, объект Query DSL) Запрос, написанный на языке Query DSL, используемый для фильтрации событий, на которых выполняется запрос EQL.

keep_alive

По истечении этого периода поиск и его результаты удаляются, даже если поиск еще продолжается.

Вы также можете указать это значение, используя параметр запроса keep_alive. Если оба параметра указаны, используется только параметр запроса.

keep_on_completion

(Необязательно, Булево) Если true, поиск и его результаты хранятся в кластере.

Вы также можете указать это значение, используя параметр запроса keep_on_completion. Если оба параметра указаны, используется только параметр запроса.

query

(Обязательно, строка) Запрос EQL, который вы хотите выполнить. EQL.

result_position

(Необязательно, перечисление) Набор совпадающих событий или последовательностей для возврата.

Допустимые значения для result_position

tail: (По умолчанию) Возвращает самые последние совпадения, аналогично команде Unix tail.
head: Возвращает самые ранние совпадения, аналогично команде Unix head.

Этот параметр может изменить набор возвращаемых совпадений. Однако он не изменяет порядок сортировки совпадений в ответе.

runtime_mappings

(Необязательно, объект объектов) Определяет одно или несколько динамических полей в запросе поиска. Эти поля имеют приоритет над отображёнными полями с тем же именем.

Свойства объектов runtime_mappings

<field-name>

(Обязательно, объект) Настройка для динамического поля. Ключом является имя поля.

Свойства <field-name>

type

(Обязательно, строка) Тип поля, который может быть любым из следующих:

boolean
composite
date
double
geo_point
ip
keyword
long
lookup

script

(Необязательно, строка) Painless скрипт, выполняемый во время запроса. Скрипт имеет доступ к всему контексту документа, включая исходный _source и любые отображённые поля, а также их значения.

Этот скрипт должен включать emit для возврата рассчитанных значений. Например:

"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"

size

(Необязательно, целое или дробное число) Для базовых запросов — максимальное количество совпадающих событий для возврата.

Для запросов последовательностей — максимальное количество совпадающих последовательностей для возврата.

По умолчанию значение равно 10. Это значение должно быть больше 0.

Вы не можете использовать каналы, такие как head или tail, для превышения этого значения.

tiebreaker_field: (Необязательно, строка) Поле, используемое для сортировки совпадений с одинаковым временным меткой в порядке возрастания. См. Укажите разрыв для сортировки.

timestamp_field

(Обязательно*, строка) Поле, содержащее временную метку события.

По умолчанию равно @timestamp, как определено в Elastic Common Schema (ECS). Если поток данных или индекс не содержат поля @timestamp, это значение требуется.

События в ответе API сортируются по значению этого поля, преобразованному в миллисекунды с момента эпохи Unix, в порядке возрастания.

Поле временной метки следует отобразить как date. Тип поля date_nanos не поддерживается.

wait_for_completion_timeout

(Необязательно, значение времени) Длительность тайм-аута ожидания завершения запроса. По умолчанию тайм-аут отсутствует, т. е. запрос ожидает полных результатов поиска.

Если запрос не завершается в течение этого периода, поиск превращается в асинхронный поиск.

Вы также можете указать это значение с помощью параметра запроса wait_for_completion_timeout. Если оба параметра указаны, используется только параметр запроса.

Тело ответа

id

(строка) Идентификатор поиска.

Этот идентификатор поиска предоставляется только в следующих случаях:

Запрос поиска не возвращает полные результаты в течение периода тайм-аута параметра wait_for_completion_timeout, превращаясь в асинхронный поиск.
Параметр запроса поиска keep_on_completion равен true.

Вы можете использовать этот идентификатор с API асинхронного поиска EQL для получения текущего статуса и доступных результатов поиска или API статуса асинхронного поиска EQL для получения только текущего статуса.

is_partial

(Булево) Если true, ответ не содержит полных результатов поиска.

is_running

(Булево) Если true, запрос поиска всё ещё выполняется.

Если этот параметр и параметр is_partial имеют значение true, поиск — это активный асинхронный поиск. Если период keep_alive не истечёт, полные результаты поиска будут доступны после завершения поиска.

Если is_partial имеет значение true, но is_running имеет значение false, поиск возвратил частичные результаты из-за сбоя. Некоторые фрагменты вернули результаты, или узел, координирующий поиск, потерпел неудачу.

took

(целое число) Время выполнения запроса Elasticsearch в миллисекундах.

Это значение вычисляется путём измерения времени, прошедшего между получением запроса на координирующем узле и моментом, когда координирующий узел готов отправить ответ.

Время выполнения включает:

Время связи между координирующим узлом и узлами данных
Время, которое запрос тратит в search пуле потоков, ожидая выполнения
Фактическое время выполнения

Время выполнения не включает:

Время, необходимое для отправки запроса в Elasticsearch
Время, необходимое для сериализации JSON-ответа
Время, необходимое для отправки ответа клиенту

timed_out

(Булево) Если true, запрос превысил тайм-аут до завершения.

hits

(объект) Содержит совпадающие события и последовательности. Также содержит сопутствующие метаданные.

Свойства hits

total

(объект) Метаданные о количестве совпадающих событий или последовательностей.

Свойства total

value

(целое число) Для базовых запросов — общее количество совпадающих событий.

Для запросов последовательностей — общее количество совпадающих последовательностей.

relation

(строка) Указывает, является ли количество возвращённых событий или последовательностей точным или является нижней границей.

Возвращаемые значения:

eq: Точное
gte: Нижняя граница, включая возвращённые события или последовательности

sequences

(массив объектов) Содержит последовательности событий, соответствующие запросу. Каждый объект представляет собой соответствующую последовательность. Этот параметр возвращается только для EQL-запросов, содержащих последовательность.

Свойства объектов sequences

join_keys

(массив значений) Общие значения полей, используемые для ограничения совпадений в последовательности. Они определены с использованием ключевого слова by в синтаксисе EQL-запроса.

events

(массив объектов) Содержит события, соответствующие запросу. Каждый объект представляет собой соответствующее событие.

Свойства объектов events

_index: (строка) Название индекса, содержащего событие.
_id: (строка) Уникальный идентификатор события. Этот идентификатор уникален только в рамках индекса.
_source: (объект) Исходное JSON-тело, переданное для события во время индексации.

events

Свойства объектов events

_index: (строка) Название индекса, содержащего событие.
_id: (строка) Уникальный идентификатор события. Этот идентификатор уникален только в рамках индекса.
_source: (объект) Исходное JSON-тело, переданное для события во время индексации.

Примеры

Пример запроса с базовой фильтрацией

Следующий запрос поиска EQL ищет события с event.category значением process, которые удовлетворяют следующим условиям:

process.name значение cmd.exe
process.pid, отличное от 2013

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

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

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

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

API возвращает следующий ответ. Соответствующие события в свойстве hits.events отсортированы по времени (timestamp), преобразованному в миллисекунды с момента эпохи Unix, в порядке возрастания.

Если два или более события имеют одинаковое значение timestamp, поле tiebreaker_field используется для сортировки событий в порядке возрастания.

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

Пример запроса сопоставления последовательности

Следующий запрос поиска EQL соответствует последовательности событий, которые:

Начинаются с события с:
- event.category значением file
- file.name значением cmd.exe
- process.pid, отличным от 2013
Следуют за событием с:
- event.category значением process
- process.executable, содержащим подстроку regsvr32

Эти события также должны иметь одинаковое значение process.pid.

resp = client.eql.search(
    index="my-data-stream",
    query="\n    sequence by process.pid\n      [ file where file.name == \"cmd.exe\" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, \"regsvr32\") ]\n  ",
)
print(resp)

response = client.eql.search(
  index: 'my-data-stream',
  body: {
    query: "\n    sequence by process.pid\n      [ file where file.name == \"cmd.exe\" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, \"regsvr32\") ]\n  "
  }
)
puts response

const response = await client.eql.search({
  index: "my-data-stream",
  query:
    '\n    sequence by process.pid\n      [ file where file.name == "cmd.exe" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, "regsvr32") ]\n  ',
});
console.log(response);

GET /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") ]
  """
}

API возвращает следующий ответ. Соответствующие последовательности включаются в свойство hits.sequences. Свойство hits.sequences.join_keys содержит общие значения process.pid для каждого соответствующего события.

{
  "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"
              }
            }
          }
        ]
      }
    ]
  }
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/eql-search-api.html