Как работает построитель отчета в 1С

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

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

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

Что такое построитель отчета и где он применяется

Построитель отчета — это объект встроенного языка 1С:Предприятие, создаваемый конструктором Новый ПостроительОтчета(). Его задача — снять с разработчика рутинную работу по динамической модификации запроса: добавлению условий «ГДЕ», сортировок, группировок и итогов в зависимости от того, что выбрал пользователь на форме отчета.

Классический сценарий выглядит так: в модуле объекта отчета задан базовый текст запроса, на форме размещены элементы для отборов (период, контрагент, номенклатура), а при нажатии кнопки «Сформировать» построитель собирает итоговый запрос и выводит результат в табличный документ. Такой подход массово использовался в конфигурациях «Управление торговлей 10.3», «УПП 1.3» и других решениях на обычных формах.

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

Как устроен механизм: от текста запроса до результата

Работа построителя строится вокруг свойства Текст, в которое помещается исходный запрос. После присвоения текста построитель анализирует его структуру: определяет доступные поля (свойство ДоступныеПоля), которые можно использовать в отборах, порядке и итогах. Имена доступных полей соответствуют псевдонимам полей выборки запроса.

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

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

Настройка отборов, порядка и итогов

Отборы — основная причина использования построителя. Элемент отбора добавляется методом Отбор.Добавить("ИмяПоля"), после чего задаются свойства: ВидСравнения (равно, в списке, в иерархии и другие), Значение (или ЗначениеС/ЗначениеПо для интервалов) и Использование, включающее условие в итоговый запрос. Если флаг использования снят, условие в запрос не попадает.

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

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

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

Пример кода: отчет по продажам с отбором

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

Процедура СформироватьОтчет(ТабДок) Экспорт

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

Построитель.Параметры.Вставить("НачалоПериода", НачалоПериода);
Построитель.Параметры.Вставить("КонецПериода", КонецДня(КонецПериода));

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

Построитель.Выполнить();
Построитель.Вывести(ТабДок);

КонецПроцедуры

Обратите внимание: отбор по номенклатуре не прописан в тексте запроса — построитель сам добавит условие в итоговый запрос. Если снять у элемента флаг Использование, запрос выполнится без этого условия, и текст исходного запроса менять не потребуется.

Построитель отчета и СКД: что выбрать

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

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

Сравнение вариантов

ПостроительОтчета

Подходит для обычных форм и простых отчетов с программной логикой; ограничение — слабые пользовательские настройки и устаревшая модель форм

СКД

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

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

Нужен, когда требуется только динамически изменить текст запроса без вывода отчета; не формирует табличный документ сам

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

Самая частая ошибка — обращение к отбору по имени поля, которого нет среди доступных. Это происходит из-за отсутствия псевдонима в запросе или опечатки. Вторая типичная ситуация: разработчик добавляет отбор, но забывает установить Использование = Истина, и условие молча не применяется — отчет показывает лишние данные без какой-либо ошибки.

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

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

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

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

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

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

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

Норма

В тексте присутствуют условия по всем включенным отборам

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

Условия отсутствуют — проверьте Использование и псевдонимы полей

Свойство Результат.Пустой после Выполнить()

Норма

Ложь при ожидаемых данных, Истина трактуется как штатная пустая выборка

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

Пусто при заведомо существующих данных — ошибка в отборах или параметрах периода

Скорость формирования

Норма

Отчет формируется за приемлемое время на рабочем объеме данных

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

Резкая деградация — анализируйте план запроса и индексы

FAQ

Чем ПостроительОтчета отличается от ПостроительЗапроса?

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

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

Технически объект доступен, но штатный вывод через Вывести() ориентирован на табличный документ и обычные формы. На управляемых формах принято использовать СКД; построитель там применяют разве что как вспомогательный механизм формирования запроса с последующим ручным заполнением данных формы.

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

Создайте элемент отбора, установите ВидСравнения.ВСписке (или НеВСписке) и присвойте свойству Значение объект СписокЗначений с нужными элементами. Не забудьте включить Использование — иначе условие не попадет в итоговый запрос.

Почему отбор по полю выдает ошибку «Поле не найдено»?

Построитель ищет поле среди доступных, которые формируются по псевдонимам секции ВЫБРАТЬ. Проверьте, что поле присутствует в выборке и имеет псевдоним, точно совпадающий с именем в Отбор.Добавить(), включая регистр символов в некоторых случаях обращения.

Как посмотреть итоговый текст запроса, который выполняет построитель?

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

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

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