Сравнение с BI-коннекторам, прямому SQL и заказным API-эндпоинтам

Запросы Интеграма: что умеет движок отчётов — от автосоединений до WITH RECURSIVE

BI-коннекторам, прямому SQL и заказным API-эндпоинтам

Обложка статьи: Что умеет движок запросов

Запрос в Интеграме — сохранённое декларативное определение, которое ядро при каждом вызове компилирует в один SQL-запрос со всеми соединениями, группировками и подзапросами; соединения выводятся из метаданных, писать JOIN вручную не нужно. Один и тот же запрос отдаёт людям HTML-отчёт, коду — JSON по тому же адресу, ИИ-агенту — данные через MCP, а сортировка, пагинация, итоги и фильтры управляются параметрами URL.

Когда данным приложения нужны вычисления, выбор обычно между тремя путями: дать аналитику прямой SQL к базе, тащить данные в BI-инструмент через коннектор или заказывать программисту отдельные эндпоинты. У каждого пути своя граница: SQL-доступ нужно выдавать и отзывать, коннектор приносит копию со своей актуальностью и своей моделью прав, а каждый новый срез данных — новая задача на разработку. Запрос Интеграма закрывает эту нишу внутри базы. Это сохранённое декларативное определение — какие колонки, из каких таблиц, с какими условиями и итогами, — которое ядро компилирует в SQL при каждом вызове. Определение хранится записями той же базы: запрос можно создать, поправить или скопировать в другое приложение без выкладки кода, тем же API, которым правят данные.

Контекст

Движок запросов обслуживает всех потребителей данных приложения. Типичные обращения к одному и тому же запросу:

  • пользователь открывает отчёт в интерфейсе — с фильтрами, группировками и сводной таблицей;
  • ссылка открывает готовый срез: диапазон дат и отбор по подразделению переданы параметрами URL;
  • дашборд питается теми же отчётами: панель — это запрос, а не отдельный коннектор с кэшем;
  • внешняя система по расписанию забирает данные адресом вида report/17021?JSON_KV;
  • ИИ-агент вызывает запрос через MCP-сервер или ИИ-чат и получает данные с правами пользователя.

Вопросы и ответы

Чем запрос Интеграма отличается от SQL-представления (view)?

Представление — объект схемы базы, который создаёт и меняет администратор СУБД. Запрос Интеграма — записи самой базы: его создаёт и правит владелец приложения в интерфейсе или через API, без выкладки кода. При каждом вызове ядро компилирует определение в SQL со всеми соединениями, а соединения выводятся из метаданных автоматически.

Какие форматы отдаёт запрос Интеграма?

HTML-страницу отчёта, JSON_KV (массив объектов), JSON_DATA (первая строка) и JSON с метаданными колонок — типами, форматами и правами. Ответ помечается заголовками X-Query-Id и X-Query-Name, по которым потребитель знает, на каком запросе построены его данные.

Как передать параметр в отчёт из ссылки?

Параметрами FR_<имя> и TO_<имя> по «Имени в отчёте»: диапазон дат, конкретная запись или подразделение едут в адресе, и ссылка открывает готовый срез. Внутри определения работают встроенные переменные [TODAY], [USER_ID], [ROLE_ID] и внешние параметры _request_.X.

Может ли ИИ-агент вызвать запрос?

Да: через MCP-сервер integram-mcp (выполнение, структура, создание и клонирование отчётов, умный и естественный поиск нужного запроса) или напрямую REST-адресом report/<имя>?JSON_KV с учётной записью и правами агента. ИИ-чат платформы строит ответ на собственном запросе той же базы.

Поддерживаются ли иерархии и рекурсивные запросы?

Да, функция RECURSIVE превращает запрос в рекурсивный CTE и умеет оба вида иерархий: дерево по ссылке таблицы на саму себя (подразделения, категории) и дерево подчинённых записей. Результат возвращается множеством id и вкладывается в другие запросы подзапросом.

Как ограничить внешнюю систему одним отчётом, не открывая таблицы?

Выдать учётной записи системы право на сам запрос — тогда она видит только его результат, а не таблицы. Как устроены права запроса и почему это похоже на хранимую процедуру, разобрано в статье «Запрос как хранимая процедура».