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

Как передать параметр в запрос 1С через УстановитьПараметр

Параметры отделяют данные от текста запроса: не нужно вставлять строковые представления ссылок, дат и чисел. Платформа сама передаёт значение нужного типа в СУБД. Базовый синтаксис параметра — &Имя:

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

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

Сигнатура и назначение метода сверены с синтакс-помощником: метод устанавливает параметр запроса, доступный в его тексте. Одно значение параметра в запросе 1С можно использовать несколько раз; устанавливать его повторно для каждого вхождения не требуется.

1С 8.3: запрос и типы параметров

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

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

Если параметр сравнивается с полем составного типа, при необходимости явно ограничьте тип через ВЫРАЗИТЬ(). Это делает условие однозначным и иногда помогает СУБД выбрать подходящий индекс.

Массив или список значений для условия В (&Список)

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

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

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

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

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

Таблицу значений можно передать параметром в источник пакетного запроса и поместить во временную таблицу. У всех колонок исходной таблицы должны быть явно заданы типы. Запросу назначают МенеджерВременныхТаблиц, после чего временную таблицу используют в следующих пакетах:

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

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

Необязательные параметры в запросе 1С без динамической склейки

Необязательные параметры в запросе 1С лучше реализовать неизменным текстом и отдельными признаками использования отборов. Так запрос остаётся читаемым, а значения по-прежнему передаются типизированно:

Запрос.Текст =
    "ВЫБРАТЬ
    |   Документы.Ссылка
    |ИЗ
    |   Документ.РеализацияТоваровУслуг КАК Документы
    |ГДЕ
    |   (&БезОтбораОрганизации
    |       ИЛИ Документы.Организация = &Организация)
    |   И (&БезОтбораСкладов
    |       ИЛИ Документы.Склад В (&СписокСкладов))";

Запрос.УстановитьПараметр("БезОтбораОрганизации", НЕ ЗначениеЗаполнено(Организация));
Запрос.УстановитьПараметр("Организация", Организация);
Запрос.УстановитьПараметр("БезОтбораСкладов", СписокСкладов.Количество() = 0);
Запрос.УстановитьПараметр("СписокСкладов", СписокСкладов);

Даже когда флаг отключает условие, задайте второй параметр: платформа проверяет наличие всех параметров, упомянутых в тексте. Для критичных по производительности отчётов сравните план такого запроса с несколькими заранее подготовленными вариантами текста: условие с ИЛИ может ухудшить использование индекса.

Параметры даты: НачалоДня и КонецДня

Границы периода рассчитывайте в коде и передавайте готовыми датами. Для полного дня используйте НачалоДня() и КонецДня(). Это исключает потерю документов из-за времени в значении даты:

ДатаНачала = НачалоДня(ВыбраннаяДатаНачала);
ДатаОкончания = КонецДня(ВыбраннаяДатаОкончания);

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

Для соседних периодов надёжнее полуоткрытый интервал: Дата >= &Начало и Дата < &СледующаяГраница. Он не создаёт пересечений на последней секунде и удобен для месяцев, часов и произвольной точности хранения даты.

NULL, Неопределено и пустые значения параметров

NULL в языке запросов означает отсутствие значения после соединения или в источнике данных. Неопределено — значение встроенного языка, которое можно передать параметром, но сравнение поля с ним не является универсальной проверкой «пустоты». Для NULL применяйте ЕСТЬ NULL или ЕСТЬNULL(Поле, ЗначениеЗамены); ссылки проверяйте сравнением с пустой ссылкой нужного типа.

// Проверка значения, появившегося после левого соединения
ГДЕ ДанныеПравойТаблицы.Ссылка ЕСТЬ NULL

// Пустая ссылка передаётся типизированным параметром
Запрос.УстановитьПараметр(
    "ПустойКонтрагент",
    Справочники.Контрагенты.ПустаяСсылка());

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

Частые ошибки при передаче параметров запроса

• Имя не совпадает. В тексте указано &Организация, а в коде установлен параметр Организации. Регистр обычно несущественен, но spelling должен совпадать.
• Амперсанд добавлен в имя метода. Правильно: УстановитьПараметр("Склад", Склад), без символа амперсанда в строке имени.
• Параметр установлен после выполнения. Все значения задаются до Выполнить() или ВыполнитьПакет().
• Передан неверный тип. Строка вместо ссылки или строка вместо даты приводит к несовместимости типов либо неверному результату.
• Список использован без В. Массив нельзя сравнивать оператором равенства; нужна конструкция Поле В (&Список).
• Пустой список неожиданно убрал все строки. Если он должен отключать отбор, передайте отдельный флаг.
• У таблицы значений не заданы типы колонок. При помещении во временную таблицу платформа не сможет определить типы полей.
• Конец периода равен началу дня. Документы с ненулевым временем не попадут в выборку; используйте КонецДня() или следующую исключающую границу.
• NULL спутан с Неопределено. Для результата левого соединения проверяйте ЕСТЬ NULL, а не равенство параметру.

Частые вопросы о параметрах запроса 1С