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

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

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

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

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

Параметр в тексте запроса записывается с префиксом «&». Его можно использовать в условиях ГДЕ, в соединениях таблиц, в параметрах виртуальных таблиц и даже в списке выбираемых полей. Имя параметра подчиняется обычным правилам идентификаторов 1С: без пробелов, начинается с буквы.

Значение присваивается методом УстановитьПараметр(Имя, Значение) до вызова Выполнить() или Выгрузить(). Если параметр указан в тексте, но значение ему не присвоено, при выполнении возникнет ошибка «Не задано значение параметра».

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

Запрос.УстановитьПараметр("Контрагент", ВыбранныйКонтрагент);
Запрос.УстановитьПараметр("НачалоПериода", НачалоМесяца(ТекущаяДатаСеанса()));
Запрос.УстановитьПараметр("КонецПериода", КонецМесяца(ТекущаяДатаСеанса()));

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

Обратите внимание: в методе УстановитьПараметр имя передаётся строкой без символа «&». Это частая ошибка новичков — написать УстановитьПараметр("&Контрагент", ...), после чего платформа не находит параметр.

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

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

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

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

СписокСкладов = Новый Массив;
СписокСкладов.Добавить(СкладОсновной);
СписокСкладов.Добавить(СкладРозничный);

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

Запрос.УстановитьПараметр("СписокСкладов", СписокСкладов);

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

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

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

Запрос.Текст =
"ВЫБРАТЬ
|	Сведения.Сотрудник,
|	Сведения.Оклад
|ИЗ
|	РегистрСведений.ОкладыСотрудников.СрезПоследних(&Период, Подразделение = &Подразделение) КАК Сведения";

Запрос.УстановитьПараметр("Период", КонецДня(ДатаОтчета));
Запрос.УстановитьПараметр("Подразделение", ВыбранноеПодразделение);

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

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

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

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

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

Удобный приём: сначала отладьте запрос в консоли с конкретными значениями параметров, а затем перенесите текст в код и замените установку значений программными выражениями. Это снижает риск синтаксических ошибок при написании сложных запросов «вслепую».

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

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

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

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

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

Список.Параметры.УстановитьЗначениеПараметра("Организация", ТекущаяОрганизация);

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

Где какой способ применять

Запрос.УстановитьПараметр

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

Параметры СКД

Отчёты с пользовательскими настройками. Параметры видны пользователю, поддерживают значения по умолчанию и стандартные периоды.

Параметры динамического списка

Формы списков с произвольным запросом. Устанавливаются через УстановитьЗначениеПараметра при создании формы.

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

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

Отдельно выделим проблему границ периода. Поле Дата документа хранит время с точностью до секунды. Если передать в &КонецПериода начало дня (00:00:00), все документы этого дня, кроме проведённых ровно в полночь, выпадут из выборки. Используйте КонецДня(Дата) или функцию запроса КОНЕЦПЕРИОДА(&Дата, ДЕНЬ).

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

Как проверить, что параметр применился корректно

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

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

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

Количество строк выборки

Норма

Совпадает с числом записей при ручном отборе в форме списка

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

Пусто или строк заметно меньше — проверяйте тип и значение параметра

Тип переданного значения

Норма

Тип значения совпадает с типом поля (ссылка к ссылке, дата к дате)

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

Строка вместо ссылки, Неопределено вместо пустой ссылки

Границы периода

Норма

Документы первого и последнего дня периода попадают в выборку

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

Документы последнего дня выпадают — конец периода задан как 00:00:00

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

Норма

Отбор указан в скобках виртуальной таблицы, запрос работает быстро

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

Отбор в ГДЕ по полю, доступному как параметр, — лишнее чтение данных

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

FAQ: частые вопросы о параметрах запроса 1С

Можно ли использовать один параметр несколько раз в тексте запроса?

Да. Один и тот же параметр &Имя можно упоминать в разных частях запроса — в условиях, соединениях, параметрах виртуальных таблиц. Значение устанавливается один раз через УстановитьПараметр и применяется везде, где встречается это имя.

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

Используйте конструкцию с проверкой: ГДЕ (&Отбор = НЕОПРЕДЕЛЕНО ИЛИ Поле = &Отбор). Тогда при передаче Неопределено условие фактически отключается. В СКД аналогичную задачу решает снятие флага использования параметра в настройках.

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

Передайте таблицу значений как обычный параметр и в первом пакете запроса выберите её через ПОМЕСТИТЬ ВременнаяТаблица с указанием полей через «&Таблица.ИмяКолонки». Для работы временных таблиц объекту Запрос нужно назначить МенеджерВременныхТаблиц.

Почему условие В (&Список) возвращает пустой результат?

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

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

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

Можно ли задать значение параметра по умолчанию?

В объекте Запрос — нет, значение нужно устанавливать явно перед каждым выполнением. В СКД значение по умолчанию задаётся на закладке «Параметры» в колонке «Значение», и оно подставится, если пользователь не изменил настройку.