Как использовать DQL-запросы

Язык запросов Ключ-АСТРОМ (DQL) знакомит вас с важными концепциями, которые следует усвоить при начале работы.

DQL-запрос — это запрос, доступный только для чтения, на обработку данных и возврат результатов. Запрос формируется простым текстом с использованием конвейерной модели потока данных, которую легко читать, создавать и автоматизировать.

Объединение команд с помощью оператора

DQL-запрос содержит как минимум одну или несколько команд, каждая из которых возвращает табличный вывод, содержащий записи (строки) и поля (столбцы). Все команды разделены символом «|» (конвейером). Данные передаются потоком или по воронке от одной команды к другой. На каждом этапе данные фильтруются или обрабатываются, а затем передаются на следующий этап.

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

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

Лучший способ изучить DQL — начать с базовых запросов.

Загрузить данные

Команда DQL fetch определяет, какие данные следует загрузить из Ключ-АСТРОМ и при необходимости обработать на следующих этапах конвейера обработки.

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

fetch logs | filter loglevel == "ERROR" | summarize numErr = count()

Оператор начинается с загрузки (fetch) всех загруженных логов. Поскольку на первом этапе временной интервал запроса не был указан, применяется временной диапазон, указанный в пользовательском интерфейсе Ключ-АСТРОМ. Он содержит три команды: fetch, filter, и summarize, разделенные вертикальной чертой.

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

numErr
34

Вы также можете изменить тип данных events, используя команду fetch, добавив после неё events. В примере запроса показано суммарное значение для поля amount в наборе данных событий.

fetch events | summarize Total_amount = sum(amount)

Total_amount
1,064,497

Укажите временные рамки

Мы предлагаем использовать элементы управления, предлагаемые пользовательским интерфейсом, для выбора временного интервала запроса.

Однако оператор DQL позволяет переопределить выбор пользовательского интерфейса, используя параметр from или to для указания желаемого временного диапазона. Если в приложении или API не указано иное, временной интервал по умолчанию составляет 2 часа.

В этом примере с относительными временными диапазонами выполняются запросы к журналам за последние два часа:

fetch logs, from:now() - 2h

В этом примере запрашиваются журналы за последние 24 часа, за исключением последних двух часов:

fetch logs, from:now() - 24h, to:now() - 2h

Вы также можете использовать абсолютные временные диапазоны с параметром timeframe:

fetch logs, timeframe:"2021-10-20T00:00:00Z/2021-10-28T12:00:00Z"

Фильтр по логическому выражению

Уточните список запрашиваемых записей с помощью filter. Используйте операторы типа == или != для включения или исключения полей с определёнными значениями. Функции типа endsWith или contains позволяют включать поля, которые заканчиваются или содержат определённую строку.

fetch logs, from:now() - 2h | filter loglevel == "SEVERE" or loglevel == "ERROR" and not endsWith(log.source,"audit.log")

Выберите подмножество полей

fetch logs | fields timestamp, loglevel, log.source, content

Упорядочить результаты с помощью сортировки

По умолчанию команда sort сортирует записи по возрастанию. В следующем примере мы сортируем результаты по убыванию.

fetch logs | filter loglevel == "SEVERE" or loglevel == "ERROR" | fields timestamp, loglevel, dt.process.name, host.name, content | limit 5 | sort timestamp desc

Агрегации

В этом примере рассчитывается количество событий booking.process.started. Агрегация намеренно учитывает только рабочие дни и часы (пн-пт, с 8:00 до 17:00).

fetch bizevents | filter event.type=="booking.process.started" | fieldsAdd hour=formatTimestamp(timestamp,format:"hh"), day_of_week=formatTimestamp(timestamp,format:"EE") | filterOut (day_of_week  == "Sat" or day_of_week == "Sun") or (toLong(hour) <= 08 or toLong(hour) >= 17) | summarize numStarts = count(), by:{product}

Агрегации с течением времени

DQL предоставляет специальные команды, такие как makeTimeseries, для агрегации списка необработанных записей событий в виде временного ряда, пригодного для построения графика. Давайте рассмотрим логи, сгруппированные по уровню логов и 5-минутному интервалу агрегации:

fetch logs | filter loglevel == "SEVERE" or loglevel == "ERROR" | makeTimeseries count = count(), by:loglevel, interval:5m

Изучите приложение DQL

Вы можете изучить DQL, используя практический опыт с помощью интерактивных обучающих программ в приложении Learn DQL. Вы можете использовать приложение, если являетесь клиентом с доступом к SaaS-среде Ключ-АСТРОМ или зарегистрированным участником сообщества Ключ-АСТРОМ. Вы также можете зарегистрироваться на 15-дневную бесплатную пробную версию, чтобы опробовать приложение.