Как установить параметр запроса в 1С

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

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

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

Основной синтаксис: как объявить и установить параметр

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

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

Запрос.УстановитьПараметр("Группа", ВыбраннаяГруппа);
Результат = Запрос.Выполнить().Выгрузить();

Имя параметра в методе указывается без символа & — только в тексте запроса. Регистр имени не важен: &Группа и &ГРУППА — один и тот же параметр. Один параметр можно использовать в тексте запроса несколько раз, устанавливать его при этом нужно только один раз.

Типы значений параметров: что можно передавать

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

Особое внимание требуют даты. Если передать дату без времени ('20260101'), сравнение «меньше или равно» по такому параметру не захватит записи, сделанные в течение этого дня. Для периодов корректнее использовать конец дня — функцию КонецДня() в коде или виртуальные таблицы с параметром вида &КонецПериода, куда передаётся граница.

Пустые ссылки и Неопределено — разные значения. Передача Неопределено в параметр, который сравнивается со ссылочным полем, часто приводит к пустой выборке или к ошибке несоответствия типов. Если отбор по параметру не нужен, лучше использовать шаблон условия (&ОтборНеЗадан ИЛИ Поле = &Значение) вместо передачи Неопределено.

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

Параметры запроса (&Имя)

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

Конкатенация строк в тексте запроса

Риск ошибок экранирования, проблемы с типами дат и строк, потенциальная уязвимость. Допустимо только для имён таблиц через шаблоны.

Параметры виртуальных таблиц

Передаются в скобках после имени таблицы (РегистрНакопления.Остатки(&Период, ...)). Эффективнее отбора в ГДЕ, так как фильтрация выполняется на уровне виртуальной таблицы.

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

Для отбора по нескольким значениям параметру присваивают массив или список значений, а в тексте запроса используют оператор В. Это стандартная замена цепочкам условий через ИЛИ.

МассивГрупп = Новый Массив;
МассивГрупп.Добавить(Группа1);
МассивГрупп.Добавить(Группа2);

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

Если нужен отбор по иерархии (группа со всеми вложенными), используйте оператор В ИЕРАРХИИ(&Группа). При этом в параметр можно передать как одну группу, так и массив групп — оба варианта корректно работают с В ИЕРАРХИИ.

Пустой массив в условии В вернёт пустую выборку — это частая причина «исчезнувших» данных. Если пустой список должен означать «без отбора», добавьте в условие проверку: (&СписокПуст ИЛИ Поле В (&Список)), передав отдельный булев параметр.

Таблица значений как параметр запроса

Когда нужно сопоставить данные базы с произвольным набором строк (например, загруженным из файла), таблицу значений передают как параметр и материализуют во временную таблицу через конструкцию ПОМЕСТИТЬ. В тексте запроса такой параметр указывается как источник данных в предложении ИЗ.

Запрос.Текст =
"ВЫБРАТЬ
|	ВнешниеДанные.Артикул КАК Артикул,
|	ВнешниеДанные.Количество КАК Количество
|ПОМЕСТИТЬ ВТ_Данные
|ИЗ
|	&ТаблицаДанных КАК ВнешниеДанные
|;
|ВЫБРАТЬ
|	ВТ_Данные.Артикул КАК Артикул,
|	Номенклатура.Ссылка КАК Номенклатура
|ИЗ
|	ВТ_Данные КАК ВТ_Данные
|		ЛЕВОЕ СОЕДИНЕНИЕ Справочник.Номенклатура КАК Номенклатура
|		ПО ВТ_Данные.Артикул = Номенклатура.Артикул";

Запрос.УстановитьПараметр("ТаблицаДанных", ТаблицаИзФайла);

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

Параметры в запросах с временными таблицами и пакетных запросах

В пакетном запросе (несколько операторов ВЫБРАТЬ, разделённых точкой с запятой) параметры едины для всего пакета: установленный один раз параметр доступен в каждом подзапросе. Это удобно, когда один и тот же период или организация используются во всех временных таблицах пакета.

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

Для уничтожения временных таблиц используется оператор УНИЧТОЖИТЬ ИмяТаблицы в тексте запроса. Параметры при этом не затрагиваются — они живут в рамках объекта запроса до его выполнения.

Параметры в СКД и динамических списках

В системе компоновки данных параметры объявляются на закладке «Параметры» конструктора, а в тексте запроса набора данных также обозначаются через &. Программно значение задаётся через коллекцию КомпоновщикНастроек.Настройки.ПараметрыДанных, а не через УстановитьПараметр.

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

Ключевое отличие от обычного запроса: у параметра СКД есть флаг Использование. Установленное значение без включённого флага не попадёт в запрос — типичная причина того, что отчёт формируется «без учёта отбора». В динамических списках параметры произвольного запроса меняются через Список.Параметры.УстановитьЗначениеПараметра("Имя", Значение).

1. 1
   Создайте объект Запрос и задайте текст с параметрами через &Имя
2. 2
   Установите каждый параметр методом УстановитьПараметр до вызова Выполнить
3. 3
   Проверьте типы передаваемых значений: даты, ссылки, массивы
4. 4
   Выполните запрос и проверьте выборку на ожидаемом наборе данных
5. 5
   При пустом результате выведите значения параметров в отладчике и сверьте с данными базы

Типичные ошибки и способы их диагностики

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

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

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

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

Запрос выполняется без ошибок

Норма

Выполнить() отрабатывает, выборка открывается

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

Ошибка «Параметр не установлен» или «Несоответствие типов»

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

Норма

Совпадает с ожидаемым при ручной проверке тех же условий

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

Пустая выборка или явно лишние строки

Значение параметра в отладчике

Норма

Тип и значение соответствуют полю сравнения

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

Неопределено, неверный тип, дата без времени

Повторное использование параметра

Норма

Один параметр корректно работает в нескольких местах текста

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

Дублирование параметров с разными именами под одну задачу

Часто задаваемые вопросы

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

Технически метод вызвать можно, но на уже полученный результат это не повлияет. Чтобы применить новое значение, запрос нужно выполнить повторно. Для перебора значений в цикле объект Запрос создаётся один раз, а параметр меняется перед каждым вызовом Выполнить().

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

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

Почему запрос с параметром-строкой не находит данные, хотя значение есть?

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

Чем параметры виртуальных таблиц отличаются от обычных параметров запроса?

Параметры виртуальных таблиц указываются в скобках после имени таблицы и применяются до соединения с остальными данными, что обычно быстрее отбора в ГДЕ. Устанавливаются они тем же методом УстановитьПараметр. Не все отборы доступны как параметры виртуальной таблицы — состав зависит от конкретной таблицы.

Как посмотреть, какие параметры требует готовый текст запроса?

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

Можно ли сделать параметр необязательным?

Да, стандартный приём — добавить в условие проверку-флаг: (&ОтборОтключен ИЛИ Поле = &Значение) и передавать два параметра. В СКД необязательность реализуется настройкой доступности параметра и флагом Использование, а в динамических списках — включением и отключением параметра программно.