Версія: 2.x

Мова запитів видимості

Використовуйте GET /api/workflows?query=..., щоб знайти запуски в одному namespace Server. Цей довідник описує опублікований native Server, вибраний у маніфесті сумісності, зараз 3.10.0. Список читає збережені дані видимості. Він не виконує іменований query-обробник workflow.

Запит потребує bearer-токена оператора або адміністратора, X-Namespace та X-Durable-Workflow-Control-Plane-Version: 2. Див. авторизацію namespace. Результати містять відповідні запуски, зокрема попередні запуски екземпляра й дочірні запуски з відповідними атрибутами. Вбудованого предиката лише для кореневих workflow немає.

Надсилання запиту

Задайте DURABLE_WORKFLOW_SERVER_URL як базову URL-адресу Server, а DURABLE_WORKFLOW_AUTH_TOKEN як токен оператора або адміністратора. Приклад потребує Bash, curl і jq. Замініть фіксований UTC-інтервал на потрібний період.

query='Status = failed AND CloseTime >= "2026-11-14T00:00:00Z" AND CloseTime < "2026-11-15T00:00:00Z"'
page=$(curl --fail-with-body --silent --show-error --get \
  "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \
  -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \
  -H 'X-Namespace: default' \
  -H 'X-Durable-Workflow-Control-Plane-Version: 2' \
  --data-urlencode "query=$query" \
  --data-urlencode 'page_size=50')
printf '%s\n' "$page" | jq '{workflow_count, workflows, next_page_token}'

Status = failed вибирає групу, яка також охоплює скасовані й примусово завершені запуски. Використовуйте Status = cancelled або Status = terminated для цих точних станів. running охоплює pending, running і waiting. completed вибирає завершені запуски. Значення стану не залежать від регістру.

Використовуйте --data-urlencode для query і токена сторінки. Лапки оболонки, екранування мови запитів і URL-кодування є окремими кроками. Успішна відповідь із workflows: [] означає, що жоден запуск не відповідає запиту.

Поля

Назви полів чутливі до регістру. Вбудовані назви мають пріоритет над користувацькими атрибутами.

Поле	Значення	Оператори
`WorkflowType`, `WorkflowId`, `RunId`, `TaskQueue`	Тип запуску, ID екземпляра, ID запуску або черга завдань	`=`, `!=`, `IN`, заперечений `IN`
`Status`, `ExecutionStatus`	Стан або група станів, описана вище	`=`, `!=`
`StartTime`, `ExecutionTime`	Момент початку запуску. Назви є псевдонімами.	Скалярні порівняння, `IN`, заперечений `IN`
`CloseTime`	Момент закриття запуску	Скалярні порівняння, `IN`, заперечений `IN`
`BuildId`, `BuildIds`	Псевдоніми значення сумісності запуску, а не пошук у парку worker	Оператори keyword з урахуванням native-відмови нижче

Скалярні порівняння: =, !=, <, <=, > і >=. Відсутній момент початку чи закриття не відповідає жодному порівнянню, навіть запереченому. Native-список відмовляє HTTP 409 / unqualified_build_visibility, якщо запуск, який слід повернути, має не-null значення сумісності. Розбір build-предиката не доводить кваліфіковану підтримку списків за build.

Інші поля мають бути атрибутами пошуку, зареєстрованими в цьому namespace. Переглядайте визначення через GET /api/search-attributes і реєструйте атрибут через POST /api/search-attributes із JSON-тілом на кшталт {"name":"OrderTotal","type":"double"}. Реєстрація потребує токена адміністратора. Самого виведеного збереженого типу недостатньо, щоб запитувати незареєстрований ключ. Видалення визначення зберігає значення, але робить запити за цим ключем недійсними.

Ідентифікатор починається з ASCII-літери й продовжується ASCII-літерами, цифрами або _. Використовуйте точну зареєстровану назву. Memo, мітки видимості, бізнес-ключі та назви батьківських/кореневих зв’язків не є додатковими вбудованими структурованими полями. Простий пошук усе ще знаходить бізнес-ключ, як описано нижче.

Типи й порівняння

Зареєстрований тип	Літерали й поведінка порівняння
`keyword`	Рівність або нерівність усього текстового значення, `IN` і заперечений `IN`. Без порівняння порядку.
`string`, `text`	Порівняння всього тексту тими самими операторами, що й `keyword`. Немає підрядкового, повнотекстового пошуку чи `LIKE`.
`int`	Ціле число без лапок, як-от `42` або `-3`. Скалярні порівняння, `IN` і заперечений `IN`. Число в лапках або десяткове число не є цілим літералом.
`double`	Ціле або десяткове число без лапок, зокрема експоненційний запис `1.5e3`. Скалярні порівняння, `IN` і заперечений `IN`.
`bool`	`true` або `false` без лапок, незалежно від регістру. Скалярні порівняння, `IN` і заперечений `IN`; `false` менше за `true`. `1` і `"true"` не є булевими літералами.
`datetime`	Дата й час у лапках. Скалярні порівняння, `IN` і заперечений `IN` порівнюють моменти. Задавайте UTC або явний зсув, наприклад `"2026-11-14T12:34:56.123456Z"`.
`keyword_list`	`Tags = "urgent"` перевіряє належність. `Tags IN ("urgent", "review")` відповідає будь-якому з наведених елементів. Нерівність, порядок і заперечена належність відхиляються.

Запуск без запитуваного атрибута ніколи не відповідає предикату, навіть для != і запереченого IN. Немає предиката існування або IS NULL. Значення зі старим іншим зареєстрованим типом не перетворюється автоматично на новий тип.

Порівняння keyword, тексту й вбудованих текстових полів дотримуються правил рівності бази даних. Опублікована схема MySQL/MariaDB використовує utf8mb4_unicode_ci, що ігнорує регістр, діакритику й кінцеві пробіли. SQLite та native-порівняння PostgreSQL є точними. Належність у keyword_list також точна. Не припускайте однакових текстових результатів між цими бекендами.

Дата й час приймають ISO-дати та часові позначки зі збереженням часток до мікросекунд. Дата без часу означає північ UTC; пропущений часовий пояс також означає UTC. Для переносних запитів задавайте явні часові позначки. Відносні дати на кшталт tomorrow і назви поясів на кшталт Europe/Paris не приймаються. Обчисліть рухомий інтервал у викликача й надішліть фіксовані межі.

Синтаксис, пріоритет і екранування

Пишіть порівняння як Field operator literal. Розділяйте предикати через AND або OR. Ключові слова не залежать від регістру.
NOT застосовується до наступного предиката перед AND; AND має вищий пріоритет за OR. A = 1 OR B = 2 AND C = 3 означає A = 1 OR (B = 2 AND C = 3).
Дужки обмежують непорожній список IN з елементами через кому. Вони не групують булеві вирази. За потреби повторіть предикати в гілках OR.
Заперечена належність записується як NOT Region IN ("eu", "us"). SQL-форма Region NOT IN (...) не підтримується. Status IN (...) також не підтримується; використовуйте Status = running OR Status = completed.
Для рядків використовуйте одинарні або подвійні лапки. Екрануйте вибрані лапки та буквальну зворотну скісну риску через \. Наприклад, Customer = 'O\'Brien' і Path = "C:\\orders". Парсер також декодує C-послідовності \n, \t і \r; JSON-запис \uXXXX тут не є Unicode-екрануванням. Пишіть Unicode-символи безпосередньо.
Текстові літерали без лапок допускають ASCII-літери, цифри, _, ., : і -. Краще брати текст у лапки, щоб випадково не вивести булевий або числовий тип. SQL-конструкцій SELECT, ORDER BY і LIMIT немає.

У виразі окреме зареєстроване булеве поле може означати Flag = true, а NOT Flag означає Flag = false. Натомість самотній Flag є простим пошуковим текстом. Явні порівняння усувають цю неоднозначність.

Server розпізнає вираз за синтаксисом порівняння, IN (...) або початковим предикатом NOT. Інший текст шукається як підрядок у workflow ID та бізнес-ключі. Наприклад, query=order-1001 є простим пошуком. Тому непідтримуваний SQL-подібний текст може стати простим пошуком, а не синтаксичною помилкою. Використовуйте задокументовану граматику й перевіряйте помилки query, коли розпізнаний вираз недійсний.

Приклади запитів

Передайте будь-який вираз нижче як значення query у наведеному curl-запиті. Приклади користувацьких атрибутів передбачають, що OrderTotal: double, Attempt: int, Region: keyword, Tags: keyword_list, Approved: bool і DueAt: datetime зареєстровано й заповнено у вибраному namespace.

Завдання	Запит
Замовлення понад числовий поріг	`WorkflowType = "orders.fulfillment" AND OrderTotal > 1000`
Спроби у включному діапазоні	`Attempt >= 2 AND Attempt <= 5`
Один із двох регіонів	`Region IN ("eu", "us")`
Інші збережені регіони	`NOT Region IN ("eu", "us")`
Будь-яка мітка зі списку	`Tags IN ("urgent", "review")`
Явне false	`Approved = false`
Часове вікно	`DueAt >= "2026-11-14T00:00:00Z" AND DueAt < "2026-11-15T00:00:00Z"`
Дві черги з тим самим типом	`WorkflowType = "orders.fulfillment" AND TaskQueue = "orders" OR WorkflowType = "orders.fulfillment" AND TaskQueue = "priority"`

Пагінація й обмеження

Параметр	Поведінка
`workflow_type`	Необов’язковий точний фільтр типу, поєднується з `query` і `status` через `AND`.
`status`	Необов’язковий фільтр. Краще використовувати канонічні групи `running`, `completed` або `failed`. Поточний endpoint списку також приймає точні `cancelled` і `terminated`; `pending` та `waiting` тут не приймаються.
`page_size`	Ціле від `1` до `200`, типово `50`. Використовуйте цей параметр, а не `limit`.
`next_page_token`	Копіюйте токен попередньої відповіді, не декодуйте й не створюйте його самостійно. Завершіть, коли він null.

workflow_count є кількістю на цій сторінці, а не загальною кількістю відповідних запусків. Результати сортуються за спаданням часу початку/сортування, потім ID запуску. Пагінація читає живі дані зі зміщенням. Не змінюйте namespace, query, фільтри й розмір сторінки. Вставки, закриття або зміни атрибутів між запитами можуть зсувати збіги та спричиняти повтори чи пропуски; це не експорт знімка. Недійсний токен зараз повертає до першої сторінки замість помилки.

Отримайте наступну сторінку першого прикладу, якщо вона є:

next=$(printf '%s\n' "$page" | jq -r '.next_page_token // empty')
if [ -n "$next" ]; then
  curl --fail-with-body --silent --show-error --get \
    "$DURABLE_WORKFLOW_SERVER_URL/api/workflows" \
    -H "Authorization: Bearer $DURABLE_WORKFLOW_AUTH_TOKEN" \
    -H 'X-Namespace: default' \
    -H 'X-Durable-Workflow-Control-Plane-Version: 2' \
    --data-urlencode "query=$query" \
    --data-urlencode 'page_size=50' \
    --data-urlencode "next_page_token=$next" | jq .
fi

Розмір сторінки обмежує повернуті рядки, а не роботу з обчислення query. Зберігайте вирази й списки IN невеликими та використовуйте вибіркові предикати типу, стану чи атрибута. Парсер workflow не визначає schedule-ліміт у 2048 символів. HTTP-сервери та проксі можуть мати власні обмеження URI. Список schedule використовує іншу граматику: рівність і AND.

Недійсні запити

Розпізнаний вираз із помилкою розбору, пошуку поля чи перевірки типу повертає HTTP 422 з reason: "validation_failed", message та масивами в errors.query і validation_errors.query. Для недійсного розміру сторінки або стану використовується ключ відповідного параметра.

Недійсний вираз	Виправлення
`Unknown = 1`	Зареєструйте атрибут у цьому namespace або виправте назву поля.
`OrderTotal = "1000"`	Використовуйте числовий літерал `1000`.
`Approved = 1`	Використовуйте `true` або `false`.
`Region > "eu"`	Keywords підтримують рівність і належність, а не порядок.
`Tags != "urgent"` або `NOT Tags IN ("urgent")`	Заперечена належність не підтримується для keyword_list.
`Attempt IN ()`, `Attempt = 1 AND`	Задайте непорожній список або повний предикат.
`DueAt > "tomorrow"`	Надішліть конкретну часову позначку.

Embedded-режим і Waterline

Ця мова доступна через Server API списку workflow. Поточні embedded-списки та фільтри збережених подань Waterline не реалізують усю граматику. Їхні точні метадані-фільтри key=value та підрядкові поля не доводять підтримку діапазонів, IN, != чи булевих виразів. Service-mode Waterline також потребує явної підтримки UI/API, перш ніж збережене подання можна буде вважати цією мовою запитів. Спільна робота над паритетом залишається відкритою у функції запитів видимості.

Довідник спирається на опублікований native-парсер та unit-тести, реалізацію HTTP-пагінації і тести API списків. Вони описують поведінку опублікованого Server, а не завершення паритету embedded або Waterline.

Надсилання запиту​

Поля​

Типи й порівняння​

Синтаксис, пріоритет і екранування​

Приклади запитів​

Пагінація й обмеження​

Недійсні запити​

Embedded-режим і Waterline​