Коллекции и данные

Коллекции — это собственные таблицы данных вашего бота. В них удобно складывать заявки, заказы, ответы из диалогов, очки в игре, записи на занятия — всё, что бот собирает у пользователей или получает из интеграций. Раздел находится в меню слева: Данные → Коллекции.

Что такое коллекция

Коллекция состоит из полей (схема, описывающая столбцы) и записей (строки с данными). Каждая запись — это набор значений по полям коллекции; внутри она хранится как гибкий JSON-документ, поэтому коллекция спокойно переживает добавление новых полей.

Имя коллекции уникально в пределах одного бота и используется как идентификатор в действиях реакций (например, leads, orders, scores).

Типы полей

При создании коллекции вы задаёте список полей и тип каждого:

text — строка (имя, email, комментарий).
number — число (сумма, количество, очки).
bool — да/нет (true / false).
datetime — дата и время.
json — вложенный объект или массив для сложных значений.

Тип влияет на то, как поле редактируется в интерфейсе и как значение приводится при сохранении. Схема не жёсткая: если в записи окажется поле вне схемы, оно сохранится и отобразится отдельным столбцом.

Создание коллекции

Откройте Данные → Коллекции и нажмите Добавить.
Укажите название (латиницей, без пробелов — так на неё проще ссылаться в реакциях).
Кнопкой Поле добавьте нужные столбцы и выберите тип каждого.
При необходимости задайте правила хранения (см. ниже) и сохраните.

Записи: просмотр и редактирование

На карточке коллекции есть кнопка с иконкой таблицы — она открывает окно Данные с записями этой коллекции:

Просмотр — все строки выводятся списком, по полю на ячейку, начиная с самых свежих.
Добавить запись — открывает форму по схеме коллекции; каждое поле редактируется по своему типу (переключатель для bool, поле ввода JSON для json и т. д.).
Изменить (карандаш) — правит существующую строку.
Удалить (корзина) — удаляет строку.

Записи также наполняются автоматически — действиями реакций бота (см. ниже). Ручное редактирование и автозапись работают с одной и той же коллекцией.

Хранение (retention)

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

Хранить максимум записей — при превышении лимита самые старые записи удаляются.
Хранить не дольше (дней) — записи старше указанного срока удаляются.

Очистка выполняется фоновым процессом периодически; правила можно комбинировать.

Работа с данными из реакций

Коллекции напрямую связаны с конструктором реакций. В действиях реакции доступны:

Создать запись — добавляет строку; значения берутся из шаблонов (например, {{user.id}}, {{message.text}}). Можно задать ключ дедупликации, чтобы повторный вызов обновлял ту же строку, а не плодил дубли.
Обновить записи — изменяет строки, подходящие под условие.
Запросить записи — читает строки в контекст выполнения как массив, чтобы дальше перебрать их.
Удалить записи — удаляет строки по условию.
Цикл (for-each) — проходит по массиву из контекста и выполняет вложенные действия для каждого элемента (например, разослать сообщение по списку из коллекции).

Так бот может вести CRM, копить заявки, начислять баллы и строить отчёты без внешней базы данных.

Доступ из Mini App

Записи коллекции можно читать из Telegram Mini App вашего бота: фронтенд запрашивает данные коллекции по имени с фильтрами и лимитом. Это позволяет показывать пользователю его заказы, историю или таблицу лидеров прямо внутри Telegram.

Советы

Давайте полям короткие машинные имена (email, total, paid) — их удобнее подставлять в шаблоны реакций.
Для идемпотентной записи (например, «одна заявка на пользователя») используйте ключ дедупликации.
Включайте retention для логов и временных данных, чтобы коллекция не разрасталась.
Тип json подойдёт, когда структура значения заранее не фиксирована.