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

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

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

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

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

Обычный запрос в 1С создаётся через объект Запрос: разработчик присваивает свойству Текст готовую строку на языке запросов и выполняет её. Такой подход отлично работает, пока структура выборки фиксирована. Но как только появляются условия «если пользователь выбрал контрагента — добавить отбор, если выбрал период — добавить параметр», текст приходится склеивать из кусков, что приводит к ошибкам синтаксиса и нечитаемому коду.

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

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

Чем построитель запроса отличается от обычного запроса и СКД

Выбор инструмента зависит от того, насколько заранее известна структура выборки и кто должен управлять настройками — разработчик или пользователь. Сравнение трёх подходов помогает сориентироваться.

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

Что выбрать

Объект Запрос

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

ПостроительЗапроса

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

СКД

Подходит для пользовательских отчётов в современных конфигурациях. Ограничение — избыточна для простых служебных выборок.

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

Работа с построителем начинается с создания объекта и передачи ему исходного текста запроса. Базовый текст можно задать в конструкторе или через свойство Текст, а дальше модифицировать программно.

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

// Добавляем отбор программно
ЭлементОтбора = Построитель.Отбор.Добавить("Товар");
ЭлементОтбора.ВидСравнения = ВидСравнения.ВСписке;
ЭлементОтбора.Значение = СписокТоваров;
ЭлементОтбора.Использование = Истина;

// Получаем готовый запрос и выполняем
Запрос = Построитель.ПолучитьЗапрос();
Результат = Запрос.Выполнить().Выгрузить();

Ключевой момент — флаг Использование у элемента отбора. Если он сброшен, отбор остаётся в коллекции, но в итоговый текст запроса не попадает. Именно так реализуется сценарий «пользователь не заполнил поле — отбор не применяется», без какой-либо склейки строк.

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

Работа с отборами и параметрами

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

Частая ситуация — отбор по периоду. Здесь удобнее добавить два элемента отбора на одно поле: один с видом сравнения «БольшеИлиРавно», второй — «МеньшеИлиРавно». Построитель корректно объединит их в тексте запроса оператором И.

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

Построитель отчёта: интерактивная настройка отчётов

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

Типовой сценарий: в модуле отчёта создаётся экспортная переменная ПостроительОтчета, заполняется его текст запроса, настраиваются измерения и показатели, а платформа строит интерфейс настройки автоматически. Результат выводится в табличный документ методом Вывести().

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

Маршрут решения

Как выбрать действие

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

Новый отчёт в управляемом приложении с пользовательскими настройкамиИспользуйте СКД — построитель отчёта в управляемых формах не работает

Служебная выборка в коде с динамическим составом отборовИспользуйте ПостроительЗапроса или аккуратную сборку текста запроса

Фиксированная выборка без вариантов настройкиДостаточно обычного объекта Запрос с готовым текстом

Типичные ошибки и ограничения

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

Вторая ошибка — попытка установить значение отбора, не указав вид сравнения, или использовать несовместимый вид сравнения для типа данных. Например, вид «Содержит» применим только к строкам, а «ВИерархии» — к ссылочным иерархическим типам. Нарушение приводит к ошибке при выполнении запроса.

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

Как проверить корректность сформированного запроса

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

Второй приём — проверка результата на тестовых данных с заведомо известным составом. Задайте отбор, при котором должна вернуться ровно одна известная запись, и сравните фактический результат. Если запись не найдена или найдено лишнее — проблема в виде сравнения или значении отбора.

Контрольные точки

Как проверить результат

Текст запроса после ПолучитьЗапрос()

Норма

Все активные отборы присутствуют в секции ГДЕ с корректными условиями

Тревожный признак

Отбор отсутствует в тексте или условие сформировано не так, как задумано

Результат на контрольных данных

Норма

Возвращаются ровно те записи, которые соответствуют условиям

Тревожный признак

Лишние или пропущенные записи — проверяйте вид сравнения и значение

Время выполнения на реальных объёмах

Норма

Выборка выполняется за приемлемое для операции время

Тревожный признак

Заметные задержки — анализируйте план запроса и индексы

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

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

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

Конструктор запроса — это визуальный инструмент в конфигураторе, который помогает разработчику написать текст запроса мышкой во время разработки. Построитель запроса — программный объект, который собирает запрос во время выполнения кода. Конструктор работает на этапе проектирования, построитель — в runtime.

Можно ли использовать построитель запроса в управляемых формах?

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

Как добавить отбор по списку значений?

Добавьте элемент в коллекцию Отбор, установите вид сравнения ВСписке, а в свойство Значение поместите объект СписокЗначений или массив с нужными ссылками. Не забудьте включить флаг Использование. Построитель сформирует условие с оператором В и параметром-списком.

Почему отбор не попадает в итоговый текст запроса?

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

Что выбрать для нового отчёта: построитель или СКД?

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

Влияет ли построитель на скорость выполнения запроса?

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