› › ›

API поиска EQL

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

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

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

Запрос

GET /<target>/_eql/search

POST /<target>/_eql/search

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

Если функции безопасности Elasticsearch включены, у вас должны быть права доступа index для целевого потока данных, индекса или псевдонима.
См. Обязательные поля.
[предварительный просмотр] Эта функция находится в стадии технического предварительного просмотра и может быть изменена или удалена в будущей версии. Elastic будет работать над исправлением любых проблем, но функции в техническом предварительном просмотре не подлежат соглашению об уровне обслуживания официальных функций GA. Для поиска по нескольким кластерам локальные и удалённые кластеры должны использовать одну и ту же версию Elasticsearch. Локальные кластеры версии 7.17.7 или более поздней также поддерживают поиск по нескольким кластерам в удалённых кластерах версии 7.15.0 или более поздней. В отношении безопасности см. Настройка удалённых кластеров с безопасностью.

Ограничения

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

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

<target>

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

[предварительный просмотр] Эта функция находится в стадии технического предварительного просмотра и может быть изменена или удалена в будущей версии. Elastic будет работать над исправлением любых проблем, но функции в техническом предварительном просмотре не подлежат соглашению об уровне обслуживания официальных функций 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

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

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

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

field

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

format

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

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

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

GeoJSON

wkt

Well Known Text

mvt(<zoom>/<x>/<y>@<extent>) или mvt(<zoom>/<x>/<y>)

Бинарный Mapbox векторная плитка. API возвращает плитку в виде строки, закодированной в base64.

Параметры mvt

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

filter

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

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. Если оба параметра указаны, используется только параметр запроса.

query

(Обязательное, строка) 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

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

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

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

Если два или более события имеют одинаковое значение времени, используется поле 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.

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/7.17/eql-search-api.html