Запросы

Блоки данных работают через SQL-запросы к подключённым источникам. Запрос описывается в конфигурации блока, проверяется до выполнения, а результат сохраняется.

Выполнение и проверка

• выполнение — POST /api/query/execute к любому подключённому источнику;
• проверка до выполнения — POST /api/query/validate: синтаксис, колонки, источники;
• любой запрос ограничен 30 секундами и 10 000 строками — защита от случайных «SELECT * FROM огромная_таблица»;
• описание запроса поддерживает Scriban-переменные документа.

Кэширование

• сохранённые результаты ускоряют повторные открытия отчёта;
• статистика сохранённых результатов — GET /api/query/cache/statistics;
• очистка — POST /api/query/cache/clear.

Серверные вычисления

Тяжёлая аналитика считается на сервере: гистограммы (POST /api/query/histogram) и диаграммы размаха (POST /api/query/boxplot) не гоняют данные в клиент целиком — на клиент уходит готовый результат.

Привязка к блоку

Запрос живёт в конфигурации блока и привязывается по queryId. Валидатор проверяет существование запроса и его источника — подробнее в разделе Проверки и авто-коррекция.

Значения в запросе

• подстановки вида @имя и :имя передаются базе как параметры запроса — не склейкой текста, поэтому постороннее значение не может «дописать» SQL;
• значение берётся из переменных документа, читательских настроек отчёта, фильтров в шапке и клика по графику; если имя задано в адресе отчёта, побеждает оно;
• если значение не задано, параметр равен пустому (NULL): запрос не падает, а условие «фильтр не выбран» просто не срабатывает;
• список значений тоже передаётся одним параметром — каждая база получает его своим способом.

ИИ и производительность

Не хотите писать SQL? Опишите словами, что нужно — ИИ напишет или исправит запрос (подробнее — агент в отчёте). Рекомендации по производительности: фильтруйте по датам, считайте агрегаты в SQL, а не в блоке, и используйте лимит строк.

← Оглавление документации