Списки, итоги и переходы

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

Список можно получить из коллекции, HTTP-ответа или предыдущего действия. Дальше реакции могут отбирать строки, менять порядок, получать группы и итоги, показывать кнопки и выбирать следующий шаг.

Что выбрать

Для перехода по количеству и полноте результата поиска остаётся действие branch_result. Оно отличается от сравнения произвольного значения. Например, результат поиска проверяется на «Ничего не найдено», а поле transition.status – на равенство updated.

Обработать список

1. Укажите источник: ключ контекста, в котором лежит массив объектов или результат с полем rows. Например, response.items или search.
2. При необходимости добавьте фильтры. Каждая строка содержит имя поля, условие и значение. Все условия должны выполняться одновременно.
3. Добавьте поля сортировки в порядке приоритета. Выберите текстовый или числовой режим и направление. Числовой режим ставит 2 перед 10.
4. Если нужны только первые вхождения, перечислите поля в убрать повторы. Например, по id или по паре category, name.
5. Настройте пропустить и максимум строк, а также необязательный список полей результата.
6. Укажите, куда сохранить результат, например selection.

Действие применяет фильтры, сортировку, удаление повторов, окно строк и выбор полей именно в этом порядке. Равные ключи сохраняют порядок входного списка. Отсутствующие значения и null сортируются в конце при обоих направлениях. Удаление повторов различает число 1 и строку "1". Исходный список не изменяется.

Для проверки в редакторе используйте буквальный JSON-пример. Эта проверка не запускает реакцию, не отправляет сообщения и не изменяет записи.

Имена полей – точные ключи объектов. Точка в имени не означает переход во вложенный объект. Числовые фильтры пропускают отсутствующее поле и null; имеющееся неверное число даёт ошибку.

{
  "source": "response.items",
  "filters": [{"field": "state", "operator": "eq", "value": "ready"}],
  "sort": [{"field": "score", "direction": "desc", "mode": "number"}],
  "distinct_by": ["id"],
  "offset": 0,
  "limit": 10,
  "save_to_ctx": "selection"
}

Строки доступны в selection.rows, первая строка в selection.first, её скалярное поле – через {{ctx.selection.first.name}}. Число возвращённых строк находится в selection.count.

total показывает число подходящих переданных строк до выбора страницы. Если исходный ответ сервиса содержал только первые сто записей, действие не может узнать, сколько их осталось на сервере. Метка scope=loaded_rows прямо обозначает область подсчёта.

Страницы и неполные данные

Для следующей страницы увеличьте offset. Это окно над текущим списком, а не сохранённый снимок удалённой базы: если источник изменился, границы страниц тоже могут измениться.

Если исходный результат был неполным, эта информация сохраняется. Неполная выдача не становится полной после фильтрации или подсчёта. При использовании branch_result сначала обрабатывайте ветку Неполная выдача. Одна видимая строка на странице ещё не доказывает, что подходящая запись всего одна.

Группы и итоги

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

Для общего итога оставьте группировку пустой. Для отдельных итогов перечислите поля группировки. Группы идут в порядке первого появления во входных данных.

{
  "source": "response.items",
  "group_by": ["state"],
  "metrics": [
    {"as": "records", "operator": "count"},
    {"as": "total_score", "operator": "sum", "field": "score"},
    {"as": "average_score", "operator": "avg", "field": "score"}
  ],
  "save_to_ctx": "summary"
}

В summary.rows будет по строке на каждое значение state. Имена метрик должны быть уникальными и отличаться от полей группировки и служебных полей результата.

Обычные имена полей, включая count и total, подходят для группировки. Служебные поля ранжирования _score и _match_type группировать нельзя.

count_distinct различает типы: число 1 и строка "1" считаются разными значениями. Отсутствующие значения и null пропускаются. Для этой метрики массивы и объекты дают ошибку.

Отсутствующие числовые значения пропускаются. Если имеющееся значение нельзя прочитать как число, действие возвращает ошибку вместо незаметной замены на ноль. Для пустого общего итога count и sum равны нулю, а avg, min, max – null. Пустой список с группировкой не создаёт групп. Среднее при необходимости округляется до 12 знаков после запятой.

Все итоги относятся к загруженным строкам. Это не запрос на подсчёт всей коллекции или внешней базы.

Выбрать шаг по значению

В поле значения можно использовать текст, число в текстовой форме или подстановку. Затем добавьте условия в порядке приоритета. Выполняется первая совпавшая ветка. Если ни одна не подошла, используется необязательная ветка Иначе. Без неё действие завершится без перехода, с объяснением в журнале.

Доступны равенство и неравенство, числовые сравнения, наличие фрагмента, начало или конец строки, регулярное выражение, пустое и непустое значение. Равенство текста различает регистр. Числовые сравнения не сравнивают числа по алфавиту. Регулярные выражения используют RE2.

Например, после условного изменения записи проверьте {{ctx.transition.status}}:

• updated – продолжить работу с успешно изменённой записью;
• conflict – перечитать данные и предложить пользователю актуальный следующий шаг;
• not_found – показать, что запись больше недоступна.

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

{
  "value": "{{ctx.transition.status}}",
  "cases": [{"operator": "eq", "value": "updated", "reaction_id": "reaction-success"}],
  "else_reaction_id": "reaction-fallback"
}

Замените ID на реальные реакции этого бота. Для условий empty и not_empty операнд value в ветке не нужен. Буквальная проверка через evaluate_conditions возвращает, например, {"matched":true,"case_index":0,"reaction_id":"reaction-success","operator":"eq"}. Индекс ветки начинается с нуля; -1 и оператор else обозначают запасной переход или отсутствие совпадения. Проверка не исполняет выбранную реакцию.

Изменить запись при условии

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

Укажите коллекцию, ID записи, непустой набор ожидаемых полей, непустой набор новых значений и имя результата:

ID – строка с положительным целым числом в пределах int64. Значения в expected и values передаются строками, в том числе для чисел и логических полей; действие применяет типы схемы коллекции. Оба набора содержат от 1 до 256 полей и поддерживают подстановки.

{
  "collection": "requests",
  "record_id": "{{ctx.selected_id}}",
  "expected": {"state": "new"},
  "values": {"state": "processing"},
  "save_to_ctx": "transition"
}

Если два запуска одновременно пытаются изменить одну запись из new в другое состояние, оба не должны получить успешный результат. После первого изменения прежнее ожидаемое состояние перестаёт совпадать.

Ответ содержит также updated: true или false. При конфликте текущие значения записи не раскрываются. Не заменяйте конфликт безусловной перезаписью: перечитайте доступные данные и выберите следующий шаг по текущей ситуации.

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

Кнопки и следующие действия

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

Результат коллекции содержит _record_id. У обычного HTTP-списка такого поля может не быть: используйте его собственный ключ, например id. Конструктор не создаёт вымышленные ID коллекции для произвольных объектов.

Имена коллекций, поля и статусы выбираете вы. Например, одинаковая цепочка «получить список → отобрать → сгруппировать → выбрать шаг» может обрабатывать результаты опроса, обращения в поддержку, сообщения или данные внешнего API.

Ограничения и ошибки

Вход и выход ограничены 10000 строками и 16777216 байтами. Превышение предела даёт ошибку, а не скрытое обрезание. Максимум строк окна по умолчанию 100; явный limit=0 использует это значение. В числовом режиме пустая строка считается ошибочным числом; отсутствие поля и null обрабатываются как отсутствующие значения.

Фильтров может быть до 64, полей сортировки до 8, полей удаления повторов до 16, полей проекции до 256. Для группировки можно выбрать до 4 полей и до 64 метрик. Ветвление поддерживает до 64 условий, сравниваемое значение до 4096 байт и регулярное выражение до 1024 байт.

Числа обрабатываются как точные десятичные значения. Обычная запись ограничена 256 байтами, степень в записи с e – от −256 до 256. Допускается также длинная каноническая десятичная запись до 1030 байт, чтобы результат вычисления можно было передать следующему действию. В ней нет e, начального +, лишних ведущих и конечных нулей. Общая граница значения – 516 цифр целой и 512 цифр дробной части. Выход за неё даёт ошибку; кроме описанного округления среднего, числа не округляются.

Ошибочный JSON, несовместимый результат, неверное число или условие показываются как ошибки, не как «Ничего не найдено». Журнал объясняет количество обработанных строк, выбранную ветку и статус изменения, не выводя исходные значения записей в обычный журнал.

Использование через MCP

get_workflow_guide возвращает текущие схемы, параметры, ограничения и примеры. Для проверки используйте transform_list, aggregate_list, evaluate_conditions. В инструменты списков передаются сами данные в data, а не ключ контекста source.

update_record_if действительно изменяет запись и требует прав на запись коллекций. Указывайте нужного бота и region. Прочитать данные в одном боте и изменить совпавший ID в другом нельзя.

Подробнее о подключении и правах: MCP.