---
title: "Запросы"
id: "1342"
type: "page"
slug: "queries"
published_at: "2026-08-15T23:32:28+00:00"
modified_at: "2026-10-17T12:50:57+00:00"
url: "https://pastukhov.com/agents/analytics/docs/queries/"
markdown_url: "https://pastukhov.com/agents/analytics/docs/queries.md"
excerpt: "Блоки данных работают через SQL-запросы к подключённым источникам. Запрос описывается в конфигурации блока, проверяется до…"
---

# Запросы

[https://pastukhov.com/agents/analytics/docs/queries/.md](https://pastukhov.com/agents/analytics/docs/queries/.md)

Блоки данных работают через 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`) не гоняют данные в клиент целиком — на клиент уходит готовый результат.

## Обработка результата скриптом

Результат запроса можно дополнительно обработать своим Python-скриптом: переименовать колонки, перевести суммы в другую валюту, отфильтровать строки, досчитать показатель. Скрипт получает готовую таблицу и возвращает такую же — но уже изменённую.

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

Подробнее о том, как завести скрипты, — в разделе [Python-скрипты](/agents/analytics/docs/scripts)
.

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

Запрос живёт в конфигурации блока и привязывается по `queryId`. Валидатор проверяет существование запроса и его источника — подробнее в разделе [Проверки и авто-коррекция](/agents/analytics/docs/validation)
.

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

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

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

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

[← Оглавление документации](/agents/analytics/docs)