К статье
Практический материал

Другое · 9 мин

Запрос с параметром WHERE в 1С

Как оформить параметризованный запрос 1С с условием WHERE: вставка параметров, проверка типов, ограничения и типичные ошибки при работе с данными.

В 1С:Предприятии запрос с параметром позволяет вынести переменное значение из текста запроса в отдельный набор параметров. Это делает текст запроса стабильным, а значение можно задать из кода перед выполнением. Такой подход особенно полезен, когда условие WHERE зависит от выбранного пользователем контрагента, документа, даты или другого справочника.

Параметр в тексте запроса помечается знаком амперсанда, например &Контрагент, а значение задаётся через коллекцию Параметры объекта Запрос. Язык запроса подставляет значение вместо параметра на этапе выполнения, поэтому сам текст запроса не меняется при изменении условий отбора.

Чтобы использовать параметр, сначала описывается текст запроса, затем в коде вставляется нужное значение. Примерно это выглядит так: текст содержит условие Где Контрагент = &Контрагент, а перед выполнением вызывается Запрос.Параметры.Вставить("Контрагент", Значение). После этого запрос выполняется обычным образом и возвращает отобранные данные.

Важно, что тип значения параметра должен соответствовать типу поля в условии. Если в базе хранится ссылка на справочник, в параметр нужно передавать именно ссылку, а не строку с наименованием. Несоответствие типов может привести к пустому результату или ошибке при выполнении.

Что означает параметризованный запрос в 1С

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

Использование параметров удобно, когда один и тот же запрос вызывается многократно с разными условиями. Например, отчёт по продажам может фильтроваться по менеджеру, периоду или складу, а текст запроса при этом не переписывается.

Как передать параметр в условие WHERE

В тексте запроса параметр указывается после знака амперсанда прямо в условии WHERE. Значение задаётся программно до выполнения запроса. Коллекция параметров позволяет вставлять ссылки, числа, даты, строки и другие типы, поддерживаемые языком запросов.

Порядок действий
  1. 1
    Опишите текст запроса с параметром в условии WHERE
  2. 2
    Задайте значение параметра через Параметры.Вставить перед выполнением
  3. 3
    Проверьте тип и заполнение значения
  4. 4
    Выполните запрос и сверьте результат с ожидаемым

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

Параметр справочника или документа

Для справочников и документов в параметр передаётся ссылка на объект. В условии WHERE достаточно сравнить поле реквизита с параметром. Язык запроса сам подставит внутренний идентификатор ссылки, поэтому в тексте не нужно указывать код или наименование в кавычках.

Параметр в текстеУпоминание &Имя в условии

Проверьте, что значение вставлено через Параметры.Вставить перед выполнением

Тип значенияСоответствие полю

Убедитесь, что передаётся ссылка, дата или число, а не текстовое представление

Результат выполненияНе пустой набор записей

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

Параметр даты или периода

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

Список значений в условии

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

Маршрут решения

Как выбрать действие

Нужно отобрать данные по значению из формы или справочникаИспользуйте параметризованный запрос с WHERE и передачей значения через Параметры
Нужно изменить имя поля или таблицу в зависимости от условияСобирайте текст запроса в коде отдельно, параметры оставьте только для значений

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

Где параметры использовать нельзя

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

Если запрос работает в конструкторе, но не в коде, сравните значения параметров и права доступа к данным.
ПЗ
Практическое замечание

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

Проверка типов и пустых значений

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

Если поле может содержать NULL, сравнение с параметром может вести себя иначе, чем ожидается. В языке запроса 1С есть способы работы с неопределёнными значениями, но их поведение зависит от контекста. Проверяйте такие случаи на реальных данных, а не только на тестовой выборке.

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

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

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

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

Количество строк
Норма

Соответствует ожидаемой выборке

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

Ноль строк или существенно больше ожидаемого

Значение параметра
Норма

Заполнено и соответствует типу поля

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

Выполнение в конструкторе
Норма

Запрос отрабатывает с теми же параметрами

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

Ошибка компиляции или неверный набор полей

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

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

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

Типичные ошибки
01
Передача наименования вместо ссылки на справочник приводит к пустому результату
02
Использование параметра вместо имени поля или таблицы вызывает ошибку запроса
03
Пустой параметр в обязательном условии возвращает не ту выборку без ошибки

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

Сравнение способов задания условия

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

Сравнение вариантов

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

Подходит для разовых проверок, сложнее поддерживать и менее безопасна при повторном использовании

Параметризованный запрос

Удобен для повторных вызовов с разными условиями, требует вставки значений через Параметры

Сборка текста запроса в коде

Позволяет менять поля и таблицы, но требует осторожной проверки результата

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

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

Итог

Что важно запомнить

Параметр WHERE подставляет только значение, задаётся через Параметры.Запрос, а имена полей и таблиц через параметры передать нельзя.

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

Нет, параметр языка запроса подставляет только значение. Имя поля, таблицы или часть условия нужно задавать непосредственно в тексте запроса или собирать текст в коде отдельно.

Что делать, если запрос возвращает пустой результат?

Проверьте значение и тип параметра, убедитесь, что запись существует в базе, и сравните выполнение в конструкторе запроса с теми же параметрами. Также учтите права доступа и возможные пустые ссылки.

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

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

Нужно ли проверять пустой параметр перед выполнением?

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