Команды ES|QL

Команды обработки ES|QL изменяют входную таблицу, добавляя, удаляя или изменяя строки и столбцы.

ES|QL поддерживает следующие команды обработки:

Команда источника FROM возвращает таблицу с данными из потока данных, индекса или псевдонима.

Синтаксис

FROM index_pattern [METADATA fields]

Параметры

Описание

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

FROM employees

FROM employees
| LIMIT 1000

Примеры

FROM employees

Для ссылки на индексы, псевдонимы и потоки данных можно использовать математику дат. Это может быть полезно для данных временных рядов, например, для доступа к индексу сегодняшнего дня:

FROM <logs-{now/d}>

Используйте списки, разделенные запятыми, или подстановочные знаки для запроса к нескольким потокам данных, индексам или псевдонимам:

FROM employees-00001,other-employees-*

Используйте формат <remote_cluster_name>:<target> для запроса к потокам данных и индексам на удаленных кластерах:

FROM cluster_one:employees-00001,cluster_two:other-employees-*

Используйте необязательную директиву METADATA для включения полей метаданных:

FROM employees METADATA _id

Используйте двойные кавычки (") или тройные двойные кавычки (""") для экранирования имён индексов, содержащих специальные символы:

FROM "this=that", """this[that"""

Команда источника ROW создает строку с одним или несколькими столбцами, значения которых вы указываете. Это может быть полезно для тестирования.

Синтаксис

ROW column1 = value1[, ..., columnN = valueN]

Параметры

Примеры

ROW a = 1, b = "two", c = null

Используйте квадратные скобки для создания столбцов с несколькими значениями:

ROW a = [2, 1]

ROW поддерживает использование функций:

ROW a = ROUND(1.23, 0)

Команда источника SHOW возвращает информацию о развертывании и его возможностях.

Синтаксис

SHOW item

Параметры

Примеры

Используйте SHOW INFO для получения версии развертывания, даты сборки и хэша.

SHOW INFO

DISSECT позволяет извлекать структурированные данные из строки.

Синтаксис

DISSECT input "pattern" [APPEND_SEPARATOR="<separator>"]

Параметры

Описание

DISSECT позволяет извлекать структурированные данные из строки. DISSECT сопоставляет строку с шаблоном, основанным на разделителях, и извлекает указанные ключи в качестве столбцов.

Обратитесь к разделу Обработка данных с помощью DISSECT для синтаксиса шаблонов dissect.

Примеры

Следующий пример анализирует строку, содержащую метку времени, некоторый текст и IP-адрес:

ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1"
| DISSECT a """%{date} - %{msg} - %{ip}"""
| KEEP date, msg, ip

По умолчанию DISSECT выводит столбцы строк типа keyword. Для преобразования в другой тип используйте функции преобразования типов:

ROW a = "2023-01-23T12:15:00.000Z - some text - 127.0.0.1"
| DISSECT a """%{date} - %{msg} - %{ip}"""
| KEEP date, msg, ip
| EVAL date = TO_DATETIME(date)

Команда обработки DROP удаляет одну или несколько колонок.

Синтаксис

DROP columns

Параметры

Примеры

FROM employees
| DROP height

Вместо указания каждой колонки по имени, можно использовать подстановочные знаки для удаления всех колонок с именем, соответствующим шаблону:

FROM employees
| DROP height*

ENRICH позволяет добавлять данные из существующих индексов в качестве новых колонок с помощью политики обогащения.

Синтаксис

ENRICH policy [ON match_field] [WITH [new_name1 = ]field1, [new_name2 = ]field2, ...]

Параметры

Описание

ENRICH позволяет добавлять данные из существующих индексов в качестве новых колонок с помощью политики обогащения. См. Обогащение данных для получения информации о настройке политики.

Примеры

В следующем примере используется политика обогащения languages_policy для добавления новой колонки для каждого поля обогащения, определенного в политике. Сопоставление выполняется с помощью match_field, определённого в политике обогащения, и требует, чтобы входная таблица имела колонку с тем же именем (language_code в этом примере). ENRICH будет искать записи в индексе обогащения на основе значения поля соответствия.

ROW language_code = "1"
| ENRICH languages_policy

Чтобы использовать колонку с другим именем, чем match_field, определенное в политике, в качестве поля соответствия, используйте ON <column-name>:

ROW a = "1"
| ENRICH languages_policy ON a

По умолчанию каждое из определенных в политике полей обогащения добавляется как колонка. Для явного выбора полей обогащения, которые добавляются, используйте WITH <field1>, <field2>, ...:

ROW a = "1"
| ENRICH languages_policy ON a WITH language_name

Можно переименовать добавляемые колонки, используя WITH new_name=<field1>:

ROW a = "1"
| ENRICH languages_policy ON a WITH name = language_name

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

Команда обработки EVAL позволяет добавлять новые колонки с вычисленными значениями.

Синтаксис

EVAL [column1 =] value1[, ..., [columnN =] valueN]

Параметры

Описание

Команда обработки EVAL позволяет добавлять новые колонки с вычисленными значениями. EVAL поддерживает различные функции для вычисления значений. См. Функции для получения дополнительной информации.

Примеры

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height_feet = height * 3.281, height_cm = height * 100

Если указанная колонка уже существует, существующая колонка будет удалена, а новая колонка будет добавлена в таблицу:

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height = height * 3.281

Указание имени выходной колонки необязательно. Если не указано, имя новой колонки равно выражению. Следующий запрос добавляет колонку, названную height*3.281:

FROM employees
| SORT emp_no
| KEEP first_name, last_name, height
| EVAL height * 3.281

Поскольку это имя содержит специальные символы, его необходимо заключить в кавычки с использованием обратных кавычек (`) при использовании в последующих командах:

FROM employees
| EVAL height * 3.281
| STATS avg_height_feet = AVG(`height * 3.281`)

GROK позволяет извлекать структурированные данные из строки.

Синтаксис

GROK input "pattern"

Параметры

Описание

GROK позволяет извлекать структурированные данные из строки. GROK сопоставляет строку с шаблонами на основе регулярных выражений и извлекает указанные шаблоны в виде столбцов.

Обратитесь к разделу "Обработка данных с помощью GROK" для синтаксиса шаблонов grok.

Примеры

Следующий пример анализирует строку, содержащую метку времени, IP-адрес, адрес электронной почты и число:

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num}"""
| KEEP date, ip, email, num

По умолчанию GROK выводит столбцы строк типа keyword. int и float типы можно преобразовать, добавив :type к семантике в шаблоне. Например, {NUMBER:num:int}:

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"""
| KEEP date, ip, email, num

Для других преобразований типов используйте функции преобразования типов:

ROW a = "2023-01-23T12:15:00.000Z 127.0.0.1 some.email@foo.com 42"
| GROK a """%{TIMESTAMP_ISO8601:date} %{IP:ip} %{EMAILADDRESS:email} %{NUMBER:num:int}"""
| KEEP date, ip, email, num
| EVAL date = TO_DATETIME(date)

Если имя поля используется более одного раза, GROK создаёт столбец с множественными значениями:

FROM addresses
| KEEP city.name, zip_code
| GROK zip_code """%{WORD:zip_parts} %{WORD:zip_parts}"""

Команда обработки KEEP позволяет указать, какие столбцы будут возвращены и в каком порядке.

Синтаксис

KEEP columns

Параметры

Описание

Команда обработки KEEP позволяет указать, какие столбцы будут возвращены и в каком порядке.

При совпадении имени поля с несколькими выражениями применяются правила приоритета. Поля добавляются в порядке их появления. Если одно поле соответствует нескольким выражениям, применяются следующие правила приоритета (от наивысшего к наименьшему):

Если поле соответствует двум выражениям с одинаковым приоритетом, приоритет получает правое выражение.

Обратитесь к примерам для иллюстрации этих правил приоритета.

Примеры

Столбцы возвращаются в указанном порядке:

FROM employees
| KEEP emp_no, first_name, last_name, height

Вместо указания каждого столбца по имени, можно использовать подстановочные знаки для возвращения всех столбцов с именем, соответствующим шаблону:

FROM employees
| KEEP h*

Подстановочный символ звездочка (*) сам по себе означает все столбцы, не соответствующие другим аргументам.

Этот запрос сначала вернёт все столбцы с именем, начинающимся с h, а затем все остальные столбцы:

FROM employees
| KEEP h*, *

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

Полное имя поля имеет приоритет перед выражениями с подстановкой:

FROM employees
| KEEP first_name, last_name, first_name*

Выражения с подстановкой имеют одинаковый приоритет, но последнее побеждает (несмотря на то, что оно менее конкретное):

FROM employees
| KEEP first_name*, last_name, first_na*

Простое выражение с подстановкой * имеет самый низкий приоритет. Порядок вывода определяется другими аргументами:

FROM employees
| KEEP *, first_name

Команда обработки LIMIT позволяет ограничить количество возвращаемых строк.

Синтаксис

LIMIT max_number_of_rows

Параметры

Описание

Команда обработки LIMIT позволяет ограничить количество возвращаемых строк. Запросы не возвращают более 10 000 строк, независимо от значения команды LIMIT.

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

Чтобы обойти это ограничение:

Значения по умолчанию и максимальные значения могут быть изменены с помощью следующих динамических параметров кластера:

Пример

FROM employees
| SORT emp_no ASC
| LIMIT 5

Команда обработки MV_EXPAND расширяет многозначные столбцы в одну строку на значение, дублируя другие столбцы.

Синтаксис

MV_EXPAND column

Параметры

Пример

ROW a=[1,2,3], b="b", j=["a","b"]
| MV_EXPAND a

Команда обработки RENAME переименовывает один или несколько столбцов.

Синтаксис

RENAME old_name1 AS new_name1[, ..., old_nameN AS new_nameN]

Параметры

Описание

Команда обработки RENAME переименовывает один или несколько столбцов. Если столбец с новым именем уже существует, он будет заменён новым.

Примеры

FROM employees
| KEEP first_name, last_name, still_hired
| RENAME  still_hired AS employed

Несколько столбцов могут быть переименованы с помощью одной команды RENAME:

FROM employees
| KEEP first_name, last_name
| RENAME first_name AS fn, last_name AS ln

Команда обработки SORT сортирует таблицу по одному или нескольким столбцам.

Синтаксис

SORT column1 [ASC/DESC][NULLS FIRST/NULLS LAST][, ..., columnN [ASC/DESC][NULLS FIRST/NULLS LAST]]

Параметры

Описание

Команда обработки SORT сортирует таблицу по одному или нескольким столбцам.

По умолчанию сортировка выполняется по возрастанию. Используйте ASC или DESC для задания явного порядка сортировки.

Две строки с одинаковым ключом сортировки считаются равными. Вы можете предоставить дополнительные выражения сортировки для разрыва ничьих.

Сортировка по многозначным столбцам использует самое низкое значение при сортировке по возрастанию и самое высокое значение при сортировке по убыванию.

По умолчанию значения null считаются большими, чем любые другие. При сортировке по возрастанию значения null будут отсортированы последними, а при сортировке по убыванию — первыми. Вы можете изменить это, указав NULLS FIRST или NULLS LAST.

Примеры

FROM employees
| KEEP first_name, last_name, height
| SORT height

Явное упорядочение по возрастанию с помощью ASC:

FROM employees
| KEEP first_name, last_name, height
| SORT height DESC

Предоставление дополнительных выражений сортировки для обработки совпадений:

FROM employees
| KEEP first_name, last_name, height
| SORT height DESC, first_name ASC

Сортировка значений null вначале с помощью NULLS FIRST:

FROM employees
| KEEP first_name, last_name, height
| SORT first_name ASC NULLS FIRST

Команда обработки STATS группирует строки по общему значению и вычисляет одну или несколько агрегированных значений по сгруппированным строкам.

Синтаксис

STATS [column1 =] expression1 [WHERE boolean_expression1][,
      ...,
      [columnN =] expressionN [WHERE boolean_expressionN]]
      [BY grouping_expression1[, ..., grouping_expressionN]]

Параметры

Описание

Команда обработки STATS группирует строки по общему значению и вычисляет одно или несколько агрегированных значений по сгруппированным строкам. Для вычисления каждого агрегированного значения строки в группе могут быть отфильтрованы с помощью WHERE. Если BY опущено, выходная таблица содержит ровно одну строку с агрегациями, применёнными к всему набору данных.

Поддерживаются следующие функции агрегирования:

Поддерживаются следующие функции группировки:

Примеры

Вычисление статистики и группировка по значениям другого столбца:

FROM employees
| STATS count = COUNT(emp_no) BY languages
| SORT languages

Опущение BY возвращает одну строку с агрегациями, применёнными к всему набору данных:

FROM employees
| STATS avg_lang = AVG(languages)

Можно вычислять несколько значений:

FROM employees
| STATS avg_lang = AVG(languages), max_lang = MAX(languages)

Для фильтрации строк, используемых в агрегации, используйте клаузу WHERE:

FROM employees
| STATS avg50s = AVG(salary)::LONG WHERE birth_date < "1960-01-01",
        avg60s = AVG(salary)::LONG WHERE birth_date >= "1960-01-01"
        BY gender
| SORT gender

Агрегации могут быть смешанными, с фильтром и группировкой, которые также являются необязательными:

FROM employees
| EVAL Ks = salary / 1000 // thousands
| STATS under_40K = COUNT(*) WHERE Ks < 40,
        inbetween = COUNT(*) WHERE 40 <= Ks AND Ks < 60,
        over_60K  = COUNT(*) WHERE 60 <= Ks,
        total     = COUNT(*)

Если ключ группировки многозначный, входная строка находится во всех группах:

ROW i=1, a=["a", "b"] | STATS MIN(i) BY a | SORT a ASC

Также можно сгруппировать по нескольким значениям:

FROM employees
| EVAL hired = DATE_FORMAT("yyyy", hire_date)
| STATS avg_salary = AVG(salary) BY hired, languages.long
| EVAL avg_salary = ROUND(avg_salary)
| SORT hired, languages.long

Если все ключи группировки многозначные, входная строка находится во всех группах:

ROW i=1, a=["a", "b"], b=[2, 3] | STATS MIN(i) BY a, b | SORT a ASC, b ASC

И агрегирующие функции, и выражения группировки принимают другие функции. Это полезно для использования STATS на столбцах с несколькими значениями. Например, чтобы вычислить среднее изменение заработной платы, вы можете использовать MV_AVG, чтобы сначала усреднить несколько значений на сотрудника, и использовать результат с функцией AVG:

FROM employees
| STATS avg_salary_change = ROUND(AVG(MV_AVG(salary_change)), 10)

Пример группировки по выражению — группировка сотрудников по первой букве их фамилии:

FROM employees
| STATS my_count = COUNT() BY LEFT(last_name, 1)
| SORT `LEFT(last_name, 1)`

Указание имени выходного столбца необязательно. Если оно не указано, новое имя столбца равно выражению. Следующий запрос возвращает столбец, названный AVG(salary):

FROM employees
| STATS AVG(salary)

Поскольку это имя содержит специальные символы, его необходимо заключить в кавычки с обратными апострофами (`) при использовании его в последующих командах:

FROM employees
| STATS AVG(salary)
| EVAL avg_salary_rounded = ROUND(`AVG(salary)`)

Команда обработки WHERE создаёт таблицу, которая содержит все строки из входной таблицы, для которых заданное условие вычисляется как true.

Синтаксис

WHERE expression

Параметры

Примеры

FROM employees
| KEEP first_name, last_name, still_hired
| WHERE still_hired == true

Что, если still_hired — булевое поле, может быть упрощено до:

FROM employees
| KEEP first_name, last_name, still_hired
| WHERE still_hired

Используйте математические операции с датами, чтобы получить данные из определённого временного интервала. Например, чтобы получить последние час логов:

FROM sample_data
| WHERE @timestamp > NOW() - 1 hour

WHERE поддерживает различные функции. Например, функция LENGTH:

FROM employees
| KEEP first_name, last_name, height
| WHERE LENGTH(first_name) < 4

Полный список всех функций см. в Обзоре функций.

Для сравнения NULL используйте предикаты IS NULL и IS NOT NULL:

FROM employees
| WHERE birth_date IS NULL
| KEEP first_name, last_name
| SORT first_name
| LIMIT 3

FROM employees
| WHERE is_rehired IS NOT NULL
| STATS COUNT(emp_no)

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

Поддерживаются следующие символы подстановки:

Поддерживаемые типы

FROM employees
| WHERE first_name LIKE """?b*"""
| KEEP first_name, last_name

Совпадение точных символов * и . потребует экранирования. Символ экранирования — обратный слэш \. Так как обратный слэш также является специальным символом в строковых литералах, потребуется дополнительное экранирование.

ROW message = "foo * bar"
| WHERE message LIKE "foo \\* bar"

Для уменьшения нагрузки на экранирование, мы рекомендуем использовать строковые литералы в тройных кавычках """

ROW message = "foo * bar"
| WHERE message LIKE """foo \* bar"""

Используйте RLIKE для фильтрации данных по шаблонам строк с использованием регулярных выражений. RLIKE обычно действует на поле, расположенном слева от оператора, но также может действовать на константное (литеральное) выражение. Правая часть оператора представляет шаблон.

Поддерживаемые типы

FROM employees
| WHERE first_name RLIKE """.leja.*"""
| KEEP first_name, last_name

Сопоставление специальных символов (например, ., *, (…) потребует экранирования. Символом экранирования является обратный слэш \. Поскольку обратный слэш также является специальным символом в строковых литералах, он также потребует дополнительного экранирования.

ROW message = "foo ( bar"
| WHERE message RLIKE "foo \\( bar"

Для уменьшения накладных расходов на экранирование мы рекомендуем использовать строки с тройными кавычками """

ROW message = "foo ( bar"
| WHERE message RLIKE """foo \( bar"""

Оператор IN позволяет проверить, равен ли поле или выражение элементу в списке литералов, полей или выражений:

ROW a = 1, b = 4, c = 3
| WHERE c-a IN (3, b / 2, a)

Полный список всех операторов см. в разделе Операторы.