Действие «Запрос DQL» для Workflows

Действие «Запрос DQL» для Workflows

Действие Выполнить запрос DQL для Workflows позволяет запрашивать данные из хранилища данных с помощью DQL и использовать результаты в последующих задачах.

Входные данные

• Запрос DQL: запрос DQL для выполнения.
• Сегмент фильтра: один или несколько сегментов фильтра для применения к запросу. Сегменты фильтра сужают данные, видимые запросу, на основе предопределённых критериев.
• Часовой пояс: часовой пояс, используемый для основанных на времени функций DQL, таких как toTimestamp(). По умолчанию — UTC, если не задан.
• Завершать при пустом результате: если включено, действие завершится ошибкой, если запрос не вернёт ни одной записи.

Результат

Результат действия Выполнить запрос DQL — это ответ API запросов к хранилищу данных, который включает следующие свойства верхнего уровня:

• records: массив записей результатов. Поля в каждой записи соответствуют столбцам, спроецированным запросом DQL.
• types: метаданные типов, описывающие схему записей.
• metadata: метаданные выполнения запроса, такие как проанализированный временной диапазон, просканированные байты и ID запроса для отладки.

Отличия от интерактивного использования DQL в приложениях

Действие Выполнить запрос DQL, как и любое другое действие, является неинтерактивным. Оно выполняется автоматически как часть вашего Workflow. Это особенно важно, поскольку у вас могут быть ожидания от использования DQL в таких приложениях, как Блокноты и Дашборды, которые имеют собственное поведение, построенное поверх API запросов к хранилищу данных. Это означает:

• Часовой пояс: API по умолчанию использует UTC. Блокноты и Дашборды автоматически применяют локаль вашего браузера или настроенный часовой пояс пользователя, но действие Выполнить запрос DQL не имеет доступа к пользовательским настройкам. Если ваши результаты зависят от местного времени, используйте поле ввода Часовой пояс или явно задайте часовой пояс в запросе. Это также влияет на выражения привязки к календарю — выражения, которые привязываются к границе календаря, например -1M@M (начало прошлого месяца), вычисляются относительно поля Часовой пояс, что может дать другие результаты, чем в блокноте, где ваш местный часовой пояс применяется автоматически.
• Временной диапазон: если в запросе не указан временной диапазон, применяется значение по умолчанию API (последние 2 часа). Чтобы задать явный временной диапазон, используйте параметры from и to команды fetch.
• Лимит записей: лимит результатов по умолчанию — 1 000 записей. Используйте ключевое слово limit в запросе, чтобы получить больше. Фактическая верхняя граница — это общий лимит размера результата действия.

Запрос запускающего события

Когда Workflow запускается событийным триггером, выполнение может уже обрабатываться, пока запускающее событие ещё не сохранено в хранилище данных. Задача Выполнить запрос DQL в вашем Workflow, которая ищет событие через fetch ..., может поэтому вернуть пустой результат. Чтобы обойти это, либо установите задержку Ожидание перед в 30–45 секунд в опциях задачи, либо передайте событие непосредственно в запрос DQL с помощью команды data — запускающее событие доступно в контексте выполнения Workflow через {{ event() }}:

data json:"""{{ event()|to_json }}"""
| fields timestamp, event.name, event.id

Использование результатов DQL в условиях

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

Если вы оставите Завершать при пустом результате отключённым, массив records может быть пустым, даже когда задача завершается успешно. Доступ к конкретной записи без предварительной проверки длины массива вызовет ошибку условия. Используйте фильтр | length, чтобы проверить наличие записей перед доступом к ним:

{{ result("dql_task")["records"] | length > 0 }}

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

{{ result("dql_task")["records"] | length > 0 and result("dql_task")["records"][0]["field_name"] == "expected_value" }}