Построитель запроса в 1С: назначение, возможности и примеры использования

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

Основной сценарий применения — динамические отборы. Когда пользователь на форме выбирает произвольный набор условий (по контрагенту, периоду, складу, номенклатуре), заранее написать один статический запрос под все комбинации невозможно. Построитель берёт базовый текст запроса и добавляет в него только те условия, которые реально заданы, автоматически формируя секцию ГДЕ и параметры.

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

Что такое построитель запроса и зачем он нужен

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

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

Типовые задачи, где построитель незаменим:

• универсальные отчёты, где пользователь сам выбирает условия отбора;
• обработки подбора данных с произвольным набором фильтров;
• динамические списки с настраиваемой пользователем фильтрацией (в обычных формах);
• выборки, где состав условий зависит от логики программы (например, разные отборы для разных ролей).

Как устроен построитель: основные свойства и методы

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

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

Итоговый запрос получают методом ПолучитьЗапрос(). Он возвращает полноценный объект Запрос, у которого уже заполнены текст и параметры. Дальше работа идёт как обычно: Выполнить(), Выгрузить(), обход выборки.

Базовый пример использования построителя запроса

Типовой код работы с построителем выглядит так: создаётся объект, устанавливается текст запроса, добавляются отборы, получается и выполняется запрос.

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

Построитель.ЗаполнитьНастройки();

Если ЗначениеЗаполнено(Группа) Тогда
    ЭлементОтбора = Построитель.Отбор.Добавить("Номенклатура.Родитель");
    ЭлементОтбора.ВидСравнения = ВидСравнения.ВИерархии;
    ЭлементОтбора.Значение = Группа;
    ЭлементОтбора.Использование = Истина;
КонецЕсли;

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

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

Метод ЗаполнитьНастройки() автоматически создаёт элементы отбора по шаблонам из фигурных скобок — тогда не нужно добавлять их вручную, достаточно установить значение и флаг использования у нужного элемента. Это удобно, когда состав возможных отборов фиксирован, а активируются они по условию.

Динамические отборы: главный сценарий применения

Рассмотрим практическую ситуацию: форма подбора товаров, где пользователь может фильтровать по группе, части наименования, признаку «не помеченные на удаление». Заранее неизвестно, какие фильтры он включит. Без построителя пришлось бы писать либо восемь вариантов текста запроса, либо собирать строку вручную с проверками.

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

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

Отбор по списку значений и по интервалу

Для отбора по нескольким значениям используется вид сравнения ВСписке, а значением назначается массив или список значений. Для диапазонов дат или чисел — вид сравнения Интервал или ИнтервалВключаяГраницы, где значение задаётся через свойства ЗначениеС и ЗначениеПо. Построитель сам сформирует корректное условие и параметры.

Отборы по полям через точку

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

Построитель запроса против альтернатив: что выбрать

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

Практическое правило: если отчёт должен настраиваться пользователем в управляемом интерфейсе — берите СКД. Если нужна программная динамическая выборка в серверной логике или в обычных формах — построитель запроса оправдан. Если условий два-три и они известны заранее — проще статический запрос.

Сохранение и восстановление настроек построителя

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

При восстановлении настроек проверяйте, что поля, на которые ссылаются сохранённые отборы, всё ещё присутствуют в тексте запроса. Если запрос-шаблон изменился (например, после обновления конфигурации), старые настройки могут ссылаться на несуществующие поля — это вызовет ошибку. Оборачивайте УстановитьНастройки() в попытку/исключение и при сбое сбрасывайте настройки к значениям по умолчанию.

Частые ошибки и ограничения построителя

Несмотря на удобство, у построителя есть подводные камни, которые регулярно приводят к ошибкам у начинающих разработчиков.

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

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

Главный инструмент проверки — свойство Построитель.ПолучитьЗапрос().Текст или отладка текста после настройки. Выведите итоговый текст запроса (например, через Сообщить() в отладочном режиме) и выполните его в консоли запросов с теми же параметрами — так вы увидите и структуру условий, и результат.

Если запрос возвращает не то, что ожидалось, в первую очередь проверяйте три вещи: совпадает ли имя в Отбор.Добавить() с путём поля в шаблоне, установлен ли флаг Использование, и тот ли вид сравнения выбран (например, Равно вместо ВИерархии для групп справочника).

FAQ: частые вопросы о построителе запроса