|
|
| Строка 1: |
Строка 1: |
|
| |
|
| = Действие «Запрос DQL» для Workflows =
| |
| Действие '''Выполнить запрос DQL''' для Workflows позволяет запрашивать данные из хранилища данных с помощью '''DQL''' и использовать результаты в последующих задачах.
| |
|
| |
| == Входные данные ==
| |
|
| |
| * '''Запрос DQL''': запрос '''DQL''' для выполнения.
| |
| * '''Сегмент фильтра''': один или несколько '''сегментов фильтра''' для применения к запросу. Сегменты фильтра сужают данные, видимые запросу, на основе предопределённых критериев.
| |
| * '''Часовой пояс''': часовой пояс, используемый для основанных на времени функций '''DQL''', таких как <code>toTimestamp()</code>. По умолчанию — '''UTC''', если не задан.
| |
| * '''Завершать при пустом результате''': если включено, действие завершится ошибкой, если запрос не вернёт ни одной записи.
| |
|
| |
| == Результат ==
| |
| Результат действия '''Выполнить запрос DQL''' — это ответ '''API запросов к хранилищу данных''', который включает следующие свойства верхнего уровня:
| |
|
| |
| * <code>records</code>: массив записей результатов. Поля в каждой записи соответствуют столбцам, спроецированным запросом '''DQL'''.
| |
| * <code>types</code>: метаданные типов, описывающие схему записей.
| |
| * <code>metadata</code>: метаданные выполнения запроса, такие как проанализированный временной диапазон, просканированные байты и ID запроса для отладки.
| |
|
| |
| == Отличия от интерактивного использования DQL в приложениях ==
| |
| Действие '''Выполнить запрос DQL''', как и любое другое действие, является неинтерактивным. Оно выполняется автоматически как часть вашего Workflow. Это особенно важно, поскольку у вас могут быть ожидания от использования '''DQL''' в таких приложениях, как '''Блокноты''' и '''Дашборды''', которые имеют собственное поведение, построенное поверх '''API запросов к хранилищу данных'''. Это означает:
| |
|
| |
| * '''Часовой пояс''': '''API''' по умолчанию использует '''UTC'''. '''Блокноты''' и '''Дашборды''' автоматически применяют локаль вашего браузера или настроенный часовой пояс пользователя, но действие '''Выполнить запрос DQL''' не имеет доступа к пользовательским настройкам. Если ваши результаты зависят от местного времени, используйте поле ввода '''Часовой пояс''' или явно задайте часовой пояс в запросе. Это также влияет на выражения привязки к календарю — выражения, которые привязываются к границе календаря, например <code>-1M@M</code> (начало прошлого месяца), вычисляются относительно поля '''Часовой пояс''', что может дать другие результаты, чем в блокноте, где ваш местный часовой пояс применяется автоматически.
| |
| * '''Временной диапазон''': если в запросе не указан временной диапазон, применяется значение по умолчанию '''API''' (последние 2 часа). Чтобы задать явный временной диапазон, используйте параметры <code>from</code> и <code>to</code> команды <code>fetch</code>.
| |
| * '''Лимит записей''': лимит результатов по умолчанию — 1 000 записей. Используйте ключевое слово <code>limit</code> в запросе, чтобы получить больше. Фактическая верхняя граница — это общий лимит размера результата действия.
| |
|
| |
| === Запрос запускающего события ===
| |
| Когда Workflow запускается событийным триггером, выполнение может уже обрабатываться, пока запускающее событие ещё не сохранено в хранилище данных. Задача '''Выполнить запрос DQL''' в вашем Workflow, которая ищет событие через <code>fetch ...</code>, может поэтому вернуть пустой результат. Чтобы обойти это, либо установите задержку '''Ожидание перед''' в 30–45 секунд в опциях задачи, либо передайте событие непосредственно в запрос '''DQL''' с помощью команды <code>data</code> — запускающее событие доступно в контексте выполнения Workflow через <code><nowiki>{{ event() }}</nowiki></code>:<pre>data json:"""<nowiki>{{ event()|to_json }}</nowiki>"""
| |
| | fields timestamp, event.name, event.id</pre>
| |
|
| |
| === Использование результатов DQL в условиях ===
| |
| Задача с состоянием '''Успех''' означает, что действие выполнилось без ошибок — это не означает, что запрос вернул записи. Чтобы ветвить выполнение в зависимости от того, были ли возвращены какие-либо записи, включите '''Завершать при пустом результате''' в задаче '''DQL'''. Тогда задача завершится ошибкой, когда запрос не вернёт ни одной записи. Затем используйте условие для последующих задач, чтобы решить, запускать их или нет, в зависимости от успеха или ошибки задачи запроса.
| |
|
| |
| Если вы оставите '''Завершать при пустом результате''' отключённым, массив <code>records</code> может быть пустым, даже когда задача завершается успешно. Доступ к конкретной записи без предварительной проверки длины массива вызовет ошибку условия. Используйте фильтр <code>| length</code>, чтобы проверить наличие записей перед доступом к ним:<pre><nowiki>{{ result("dql_task")["records"] | length > 0 }}</nowiki></pre>Чтобы безопасно получить доступ к первой записи в условии:<pre><nowiki>{{ result("dql_task")["records"] | length > 0 and result("dql_task")["records"][0]["field_name"] == "expected_value" }}</nowiki></pre>
| |
