Построитель запроса в 1С: что это и как с ним работать

Построитель запроса в 1С — это объект встроенного языка, который позволяет программно формировать и модифицировать текст запроса, а также автоматически создавать по нему отчет с настройками, похожими на СКД. Разработчик передает построителю исходный текст запроса, а тот разбирает его, предоставляет программный доступ к полям, отборам, порядку и итогам, а затем формирует итоговый запрос с учетом всех изменений.

Термин часто путают с конструктором запросов — визуальным инструментом в конфигураторе, который помогает составить текст запроса мышкой, без ручного набора синтаксиса. Это разные вещи: конструктор работает на этапе разработки, а построитель — объект времени выполнения, который живет в коде и позволяет динамически менять запрос по действиям пользователя.

Практическая ценность построителя в том, что он берет на себя рутину: формирование итогового текста запроса, создание формы отчета с таблицей или диаграммой, настройку отборов и группировок. В типовых конфигурациях на его основе часто строятся универсальные отчеты, где пользователь сам выбирает поля и условия без обращения к программисту.

Чем построитель отличается от конструктора запросов и СКД

В экосистеме 1С есть три инструмента, которые новички регулярно смешивают. Конструктор запросов — диалоговое окно в конфигураторе, доступное по правой кнопке мыши в модуле. Он помогает визуально собрать текст запроса: выбрать таблицы, поля, связи, условия, — и вставляет готовый текст в код. Дальше этот текст живет как обычная строка.

Построитель запроса — программный объект (тип «ПостроительЗапроса»), создаваемый в коде оператором «Новый». Он разбирает переданный текст запроса и дает коллекции: «ВыбранныеПоля», «Отбор», «Порядок», «Измерения». Меняя эти коллекции, вы изменяете итоговый запрос без ручной склейки строк. Метод «ПолучитьЗапрос()» возвращает готовый объект «Запрос» с учетом всех правок.

СКД (система компоновки данных) — более мощный механизм отчетов, который пришел на смену построителю в типовых решениях. СКД гибче: поддерживает сложные макеты, иерархические группировки, ресурсы, варианты отчетов. Построитель проще и легче в освоении, поэтому до сих пор встречается в старых конфигурациях и подходит для несложных задач.

Как создать построитель и выполнить запрос

Минимальный сценарий работы выглядит так: создается объект построителя, в конструктор передается текст запроса, выполняется метод «Выполнить()», а результат обрабатывается через свойство «Результат». Текст запроса пишется на обычном языке запросов 1С — построитель никаких специальных конструкций не требует.

Построитель = Новый ПостроительЗапроса;
Построитель.Текст =
"ВЫБРАТЬ
| Номенклатура.Ссылка КАК Товар,
| Номенклатура.Код КАК Код
|ИЗ
| Справочник.Номенклатура КАК Номенклатура
|{ГДЕ
| (Номенклатура.Родитель = &Родитель)}";

Построитель.Выполнить();
Выборка = Построитель.Результат.Выбрать();

Пока Выборка.Следующий() Цикл
 Сообщить(Выборка.Товар);
КонецЦикла;

Обратите внимание на фигурные скобки вокруг секции ГДЕ — это расширение языка запросов для построителя. Такие скобки помечают элементы, которыми построитель может управлять: если пользователь не задал отбор, условие в фигурных скобках просто не попадет в итоговый текст запроса. Это ключевой механизм динамической настройки.

После выполнения результат доступен как обычный «РезультатЗапроса»: можно получить выборку, выгрузить в таблицу значений или передать в табличный документ. Никакой магии сверх стандартного объекта «Запрос» построитель на этом этапе не добавляет — его ценность именно в управлении текстом до выполнения.

Динамические отборы и настройки

Главный сценарий применения построителя — программное управление отборами. Коллекция «Построитель.Отбор» заполняется автоматически на основе секций в фигурных скобках и виртуальных таблиц. У каждого элемента отбора можно установить значение, вид сравнения и флаг «Использование».

1. 1
   Сформируйте текст запроса с секцией {ГДЕ (...)} в фигурных скобках
2. 2
   Создайте построитель и передайте ему текст запроса
3. 3
   Найдите нужный элемент в коллекции Построитель.Отбор по имени поля
4. 4
   Установите свойство Значение (или ЗначениеС/ЗначениеПо для интервала)
5. 5
   Выберите ВидСравнения: Равно, ВСписке, Между и т.д.
6. 6
   Установите Использование = Истина, чтобы отбор попал в запрос
7. 7
   Вызовите Выполнить() и обработайте результат

Если элемент отбора не найден автоматически, его можно добавить вручную методом «Добавить» с указанием пути к данным, например «Ссылка.Родитель». Это удобно, когда отбор нужен по полю, которого нет в исходном тексте запроса. Построитель сам допишет условие в итоговый текст.

Аналогично работают коллекции «Порядок» (сортировка результата) и «Измерения» (группировки для итогов). Пользовательская настройка в форме отчета по сути сводится к заполнению этих коллекций из элементов управления, а построитель превращает их в корректный запрос.

Быстрый отчет без СКД: вывод результата в форму

У построителя есть пара «ПостроительОтчета» — объект, который умеет не только выполнить запрос, но и автоматически оформить результат в табличный документ с шапкой, группировками и итогами. Именно так работали универсальные отчеты в старых типовых конфигурациях: пользователь настраивал отборы и группировки, а построитель отчета формировал печатную форму.

Типовой порядок действий: создается «ПостроительОтчета», задается текст запроса, вызывается «Выполнить()», затем результат выводится в элемент формы «ТабличноеПоле» или формируется «ТабличныйДокумент» через метод «Вывести()». Настройки (отборы, порядок, измерения) можно сохранять и восстанавливать между сеансами через методы «ПолучитьНастройки» и «УстановитьНастройки».

Для новых проектов на управляемых формах построитель отчета не подходит — платформа его там не поддерживает. Если вы сопровождаете старую конфигурацию на обычных формах, построитель остается рабочим инструментом, но при миграции отчетов на управляемое приложение их придется переписывать на СКД.

Типичные ошибки при работе с построителем

Самая частая проблема — отбор «не срабатывает»: условие задано, а результат не фильтруется. Причина почти всегда в том, что забыли установить флаг «Использование = Истина» либо условие в тексте запроса не обернуто в фигурные скобки, и построитель вообще не видит этот отбор.

Еще одна ловушка — изменение текста запроса после того, как настроены отборы и порядок. Присвоение свойства «Текст» заставляет построитель заново разобрать запрос, и все программно установленные настройки теряются. Правильный порядок: сначала окончательный текст, потом настройки.

При работе с виртуальными таблицами (остатки, обороты регистров) помните, что параметры виртуальной таблицы задаются в тексте запроса явно, а отборы построителя добавляются поверх. Смешение этих двух механизмов иногда приводит к неожиданно медленным запросам: отбор, который мог бы попасть в параметры виртуальной таблицы, применяется уже к развернутому набору данных.

Как проверить, что построитель сформировал правильный запрос

Отладка построителя строится на одном простом приеме: перед выполнением получите итоговый текст через «Построитель.ПолучитьЗапрос().Текст» и посмотрите, что реально будет выполнено. Это сразу показывает, попали ли в запрос отборы, правильно ли подставились условия и не потерялась ли сортировка.

Полезно также проверять тип значения отбора: если поле имеет составной тип или передается строка вместо ссылки, сравнение может молча не сработать. В таких случаях запрос выполняется без ошибки, но возвращает пустой результат, что вводит в заблуждение при отладке.

Когда построитель использовать не стоит

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

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

Частые вопросы о построителе запроса в 1С