Руководство по установке параметра запроса в 1С Предприятие

Работа с данными в платформе 1С:Предприятие невозможна без использования языка запросов. В отличие от стандартного SQL, запросы в 1С обладают мощной типизацией и специфическим синтаксисом, который требует особого подхода к передаче переменных. Новички часто сталкиваются с ошибками при попытке подставить значения в текст запроса, что приводит к неработоспособности отчетов или обработок. Понимание механизма передачи значений критически важно для написания безопасного и производительного кода.

Процесс установки параметра запроса позволяет динамически формировать выборку данных в зависимости от условий, заданных пользователем или логикой программы. Это фундаментальный навык для любого разработчика системы 1С. В этой статье мы детально разберем, как правильно использовать метод Запрос.УстановитьПараметр, рассмотрим типичные ошибки и изучим инструменты отладки запросов.

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

Основы работы с объектом Запрос в 1С

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

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

Рассмотрим базовый пример создания запроса с параметром. Допустим, нам нужно найти документ по его номеру. Мы объявляем параметр &НомерДокумента в тексте запроса, а затем используем метод установки значения. Синтаксис метода прост: первым аргументом передается имя параметра без знака амперсанда, вторым — само значение.

⚠️ Внимание: Имя параметра в методе УстановитьПараметр указывается БЕЗ символа «&». Если вы напишете Запрос.УстановитьПараметр("&Код", Значение), платформа выдаст ошибку выполнения, так как не найдет параметр с именем, содержащим спецсимвол.

Хотя платформа 1С обладает механизмами приведения типов, явное несоответствие (например, передача строки в числовое поле) может привести к ошибкам или пустой выборке. Всегда проверяйте типы данных в метаданных.

Синтаксис метода УстановитьПараметр

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

Рассмотрим конкретный пример кода на встроенном языке. Здесь мы создаем запрос, устанавливаем параметр типа Число и выполняем его. Обратите внимание на объявление переменной и передачу её в метод.

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

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

В данном примере параметр &Владелец ожидает значение типа СправочникОбъект или СправочникСсылка. Мы передаем ссылку на элемент справочника, найденную по наименованию. Платформа автоматически обработает эту ссылку и подставит её внутреннее представление в SQL-запрос, генерируемый для СУБД.

Частой ошибкой является попытка установить параметр, которого нет в тексте запроса. В таком случае система не выдаст ошибку сразу при вызове метода, но при выполнении запроса (Запрос.Выполнить()) возникнет исключение «Параметр запроса не найден». Поэтому важно следить за опечатками в именах.

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

Одной из самых мощных возможностей языка запросов 1С является возможность передавать в параметры не только скалярные значения, но и целые таблицы значений. Это позволяет реализовать конструкцию IN (ВЫРАЗИТЬ.. В) без написания громоздких условий через ИЛИ. Для этого используется объект ТаблицаЗначений.

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

• 📋 Создайте объект ТаблицаЗначений и добавьте необходимые колонки.
• 📝 Заполните таблицу данными, которые нужно использовать для фильтрации.
• 🔗 Передайте таблицу в метод УстановитьПараметр как обычное значение.
• ⚙️ В тексте запроса обращайтесь к параметру как к таблице в предложении ИЗ или ВНУТРЕННЕЕ СОЕДИНЕНИЕ.

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

ТЗ = Новый ТаблицаЗначений;
ТЗ.Колонки.Добавить("Код", ТипОписанияТипов("Строка(50)"));

СтрокаТЗ = ТЗ.Добавить();
СтрокаТЗ.Код = "ТОВАР001";

СтрокаТЗ = ТЗ.Добавить();
СтрокаТЗ.Код = "ТОВАР002";

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

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

Такой подход значительно ускоряет работу запроса при фильтрации по большому количеству значений по сравнению с конструкцией ГДЕ Поле В (Знач1, Знач2..), особенно если список формируется динамически. Платформа оптимизирует план выполнения для временных таблиц.

Использование конструктора запросов

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

Конструктор также помогает правильно объявить параметры. При добавлении условия отбора, в котором используется переменная, конструктор предложит создать параметр. Вы сможете задать его имя и тип. Это снижает риск опечаток при ручном вводе имени параметра в методе УстановитьПараметр.

Элемент интерфейса	Назначение	Где используется
Дерево полей	Выбор таблиц и полей для выборки	Левая панель конструктора
Параметры	Список объявленных параметров запроса	Вкладка "Параметры"
Условия отбора	Формирование части ГДЕ запроса	Нижняя часть окна
Текст запроса	Предпросмотр сгенерированного кода	Правая панель или отдельное поле

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

Использование конструктора особенно полезно при работе со сложными виртуальными таблицами, такими как РегистрНакопления.Остатки или РегистрБухгалтерии.ХозяйственныеОперации. Виртуальные таблицы имеют сложный синтаксис параметров (период, организация, виды регистров), и конструктор помогает сформировать их правильно, не требуя знания всех нюансов наизусть.

Отладка и анализ параметров запроса

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

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

⚠️ Внимание: Консоль запросов работает с правами текущего пользователя. Если ваш запрос обращается к данным, доступ к которым ограничен правами доступа (РЛС), в консоли вы можете получить пустой результат, даже если запрос написан верно. Проверяйте права доступа при отладке.

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

Секрет быстрой отладки

В окне отладчика можно изменить значение параметра запроса «на лету» перед выполнением строки. Найдите параметр в дереве объекта Запрос, измените его значение и продолжите выполнение — запрос уйдет с новыми данными без перезапуска программы.

Если вы получаете ошибку «Неверный тип значения параметра», используйте функцию ТипЗнч() для проверки типа передаваемой переменной. Часто бывает, что ожидается СправочникСсылка, а передается СправочникОбъект или строковое представление. Явное приведение типа решит проблему.

Типичные ошибки и способы их решения

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

Вторая частая проблема — забытая установка параметра. Если в тексте запроса есть &Параметр, а метод УстановитьПараметр для него не вызван, выполнение прервется с исключением. Хорошим тоном считается группировать все установки параметров сразу после присваивания текста запроса.

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

• ❌ Ошибка: Передача Null в параметр, который не допускает пустых значений в логике запроса.
• ❌ Ошибка: Использование имени параметра с амперсандом в методе установки.
• ❌ Ошибка: Несоответствие количества колонок в таблице значений и структуре, ожидаемой в JOIN.
• ✅ Решение: Всегда проверяйте типы переменных перед установкой параметров.

Для избежания ошибок при работе со сложными типами, такими как ПланВидовХарактеристикСсылка или ПеречислениеСсылка, рекомендуется явно указывать тип в описании типа переменной перед присваиванием. Это поможет IDE подсветить проблему еще до запуска кода.

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

Для передачи пустого значения используйте встроенную константу Неопределено. В тексте запроса это будет обработано как NULL. Пример: Запрос.УстановитьПараметр("Контрагент", Неопределено). Убедитесь, что условие в запросе корректно обрабатывает NULL (например, использует ИСТИНА при проверке на неопределенность, если это требуется логикой).

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

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

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

Убедитесь, что в тексте запроса имя параметра начинается с символа & и написано без пробелов. Также проверьте, что параметр не затерт комментариями или не находится внутри строковой константы (в кавычках). Консоль анализирует только активный текст запроса.

Как передать структуру в параметр запроса?

Напрямую передать структуру Структура в параметр запроса нельзя, так как запросы оперируют табличными данными и простыми типами. Если нужно передать набор разнородных данных, используйте ТаблицаЗначений с соответствующими колонками или передавайте значения по отдельности через разные параметры.

Влияет ли регистр букв в имени параметра?

Да, имена параметров в 1С чувствительны к регистру. Параметр &Код и параметр &код — это разные параметры. Метод УстановитьПараметр также требует точного совпадения регистра имени. Рекомендуется придерживаться единого стиля именования, например, с заглавной буквы.