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

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

Использование параметров — стандартный и единственно корректный способ передавать переменные данные в запрос. Альтернатива в виде склейки строк («подставить значение прямо в текст запроса») приводит к ошибкам типов, проблемам с датами и ссылками, а также делает код уязвимым и трудно поддерживаемым. Платформа 1С сама выполняет типизацию параметра и корректно формирует обращение к СУБД.

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

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

Запрос в 1С — это статический текст на встроенном языке запросов. Он не может напрямую обращаться к переменным модуля. Чтобы передать в запрос значение из кода (дату документа, ссылку на контрагента, массив товаров), используется механизм параметров: в тексте ставится метка &ИмяПараметра, а перед выполнением запроса значение привязывается к этой метке.

Такой подход решает сразу несколько задач. Во-первых, платформа сама преобразует значение в формат, понятный СУБД: дату — в формат даты, ссылку — в двоичное представление, булево — в логический тип. Во-вторых, текст запроса остаётся неизменным при разных значениях, что позволяет СУБД повторно использовать план выполнения и ускоряет работу. В-третьих, исключается класс ошибок, связанный с ручным форматированием строк, дат и чисел.

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

В тексте запроса параметр записывается с амперсандом без пробела: ГДЕ Продажи.Номенклатура = &Номенклатура. Имя параметра подчиняется обычным правилам идентификаторов: буквы, цифры, подчёркивание, начинаться должно с буквы или подчёркивания. Регистр имён не важен, но принято писать осмысленные имена — &НачалоПериода, а не &П1.

Значение устанавливается методом УстановитьПараметр(Имя, Значение) до вызова Выполнить() или Выгрузить(). Типичный фрагмент кода выглядит так:

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

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

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

Обратите внимание: в УстановитьПараметр имя передаётся строкой без амперсанда. Это одна из частых ошибок новичков — написать "&НачалоПериода" и получить сообщение о том, что параметр не задан.

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

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

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

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

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

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

Виртуальные таблицы регистров (Обороты, Остатки, ОстаткиИОбороты, СрезПервых, СрезПоследних) принимают параметры в круглых скобках сразу после имени таблицы. Например, у таблицы остатков регистра накопления первым параметром идёт период, затем условие отбора в виде строки, далее — измерения для итогов.

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

Параметр-условие виртуальной таблицы передаётся строкой вида "Номенклатура В (&СписокНоменклатуры)", где внутри строки снова используется параметр запроса. Такая вложенность допустима и широко применяется.

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

Параметры в СКД и консоли запросов

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

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

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

Типичные ошибки и как их избежать

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

Ещё одна группа проблем связана с типами: передача строки вместо ссылки, даты без времени там, где нужна граница периода, Неопределено вместо пустой ссылки. Для границ периода рекомендуется использовать объект Граница с видом «Включая»/«Исключая», чтобы точно контролировать попадание документов на границе интервала.

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

Как проверить, что параметры работают правильно

Базовая проверка — отладчик: поставьте точку останова после установки параметров и посмотрите коллекцию Запрос.Параметры. Там видны имена, типы и значения всех установленных параметров. Если значение Неопределено там, где ожидалась ссылка, проблема находится до запроса — в логике получения данных.

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

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

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

Коллекция Запрос.Параметры в отладчике

Норма

Все параметры заполнены, типы соответствуют ожидаемым

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

Значение Неопределено или не тот тип

Выполнение в консоли запросов с теми же значениями

Норма

Результат совпадает с ожиданием по данным

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

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

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

Норма

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

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

Пограничные документы теряются — проверьте вид границы

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

Можно ли передать в параметр таблицу значений?

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

Что произойдёт, если передать пустой массив в условие В (&Список)?

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

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

В тексте запроса нет доступа к переменным модуля вообще — запрос выполняется на уровне СУБД. Параметр — это единственный механизм передачи значения из кода в запрос, при этом платформа типизирует значение и корректно экранирует данные.

Нужно ли устанавливать параметр, если он есть в тексте, но ветка запроса не используется?

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

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

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

Почему в СКД отчёт выдаёт пустой результат, хотя запрос в консоли работает?

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