Как передать параметр в запросе 1С: технологии и примеры

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

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

Базовый принцип работы с параметрами

Передача значений в запрос осуществляется через специальный объект — МенеджерЗапроса. Именно он отвечает за подготовку текста запроса к выполнению и подстановку реальных значений вместо имен параметров. Параметры в тексте запроса всегда начинаются с символа &, за которым следует имя, например, &ПараметрКонтрагента.

Важно понимать, что параметры обрабатываются на стороне платформы до отправки запроса к СУБД. Это означает, что вы не можете передать в параметр имя таблицы или имя поля — только конкретные значения данных. Попытка подменить структуру запроса через параметр приведет к ошибке синтаксиса.

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

Синтаксис объявления и присвоения значений

Для начала работы необходимо объявить переменную типа Запрос и установить ей текст. В теле запроса используются имена параметров. Далее создается объект МенеджерЗапроса, который привязывается к этому запросу. Именно через этот объект происходит установка значений.

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

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

МенеджерЗапроса = Запрос.МенеджерЗапроса;
МенеджерЗапроса.Параметры.ВидНоменклатуры = Справочники.ВидыНоменклатуры.НайтиПоНаименованию("Товары");

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

Обратите внимание на использование символа | в начале строк текста запроса — это стандарт оформления многострочных строк в языке 1С. Имя параметра &ВидНоменклатуры в тексте должно точно совпадать с ключом, используемым при присвоении значения в коллекции параметров менеджера.

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

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

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

Верхняя граница временного интервала выборки

Имя параметра	Тип данных	Описание использования
&Организация	СправочникСсылка	Фильтрация документов по конкретной организации
&ПериодНачала	Дата	Нижняя граница временного интервала выборки
&ПериодОкончания	Дата
&ТолькоПроведенные	Булево	Флаг отбора только проведенных документов

При формировании условия с несколькими параметрами важно следить за порядком их объявления в коллекции. Хотя менеджер запроса сопоставляет их по имени, логическая структура кода должна быть прозрачной. Если какой-то параметр может быть не задан (неопределен), это требует отдельной обработки в тексте запроса через проверку на ЕСТЬNULL.

Типизация и неявное приведение значений

Одной из самых частых причин падения производительности запросов является некорректная типизация параметров. Если в базе данных поле имеет тип Число(15, 4), а вы передаете в параметр значение типа Число без уточнения или строку, СУБД может вынуждена выполнить неявное приведение типов для каждой строки таблицы.

Это приводит к тому, что индексы перестают использоваться эффективно, и вместо мгновенного поиска по индексу происходит полный скан таблицы. Всегда старайтесь передавать в параметр значение того же типа и размерности, что и поле в базе данных. Для сложных составных типов (например, СправочникСсылка.Номенклатура или ДокументСсылка.РеализацияТоваровУслуг) это критически важно.

⚠️ Внимание: Передача пустой строки "" вместо значения типа Неопределено в параметр, ожидающий ссылку, может привести к ошибке выполнения или неожиданному результату выборки. Используйте Неопределено для обозначения отсутствия значения.

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

Передача коллекций значений в запрос

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

Вы можете создать объект СписокЗначений или Массив, наполнить его нужными ссылками или значениями и передать этот объект целиком в один параметр запроса. В тексте запроса такой параметр используется в условии В(...) (IN). Платформа автоматически развернет коллекцию в список значений для СУБД.

СписокНоменклатуры = Новый СписокЗначений;
СписокНоменклатуры.Добавить(Справочники.Номенклатура.НайтиПоКоду("0001"));
СписокНоменклатуры.Добавить(Справочники.Номенклатура.НайтиПоКоду("0005"));

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

Использование коллекций значительно упрощает код и повышает его читаемость. Кроме того, это безопаснее, чем динамическое конструирование строки запроса с подстановкой GUID'ов через запятую. Однако стоит помнить, что передача очень больших коллекций (тысячи элементов) также может иметь накладные расходы на сериализацию данных.

Ограничения размеров коллекций

Хотя платформа технически позволяет передавать большие массивы, оптимальным считается размер до 1000 элементов. При превышении этого порога рассмотрите возможность использования временных таблиц для передачи набора данных.

Оптимизация и защита от SQL-инъекций

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

С точки зрения оптимизации, параметризированные запросы позволяют СУБД кэшировать планы выполнения. Если вы каждый раз подставляете значения прямо в текст запроса (конкатенация строк), СУБД вынуждена компилировать новый план для каждого уникального текста, что создает лишнюю нагрузку на процессор сервера.

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

⚠️ Внимание: Никогда не конкатенируйте пользовательские строки напрямую в текст запроса для подстановки значений. Это не только небезопасно, но и лишает вас преимуществ кэширования планов выполнения запросов сервером 1С.

Частые ошибки и методы отладки

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

Еще одна проблема — передача Неопределено в параметр, который не допускает пустых значений в условии сравнения. В таких случаях текст запроса должен предусматривать ветвление: если параметр задан, то сравниваем, иначе игнорируем условие. Это реализуется через конструкцию ЕСТЬNULL(&Параметр) ИЛИ Поле = &Параметр.

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

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

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

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

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

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

Используйте встроенную функцию ТекущаяДата() при присвоении значения. Например: МенеджерЗапроса.Параметры.ТекущаяДата = ТекущаяДата();. Убедитесь, что тип параметра в запросе совместим с типом Дата.

Влияет ли порядок параметров на скорость выполнения?

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