A1sCode — День 5: A1sQ: Параметры запросов (BuildQ)

Важно

Unload: Unload(Текст, П1?, …, П8?)
ExecuteQ: ExecuteQ(Текст, П1?, …, П8?)
Параметры передаются позиционно и соответствуют порядку &Парам в тексте.
BuildQ — не про выполнение, а про удобную сборку текста запроса (условные WHERE/ORDER/LIMIT).

Паттерн BuildQ: условные части WHERE

Добавляем фрагменты только если есть значения. Порядок &параметров в тексте совпадает с порядком в вызове.

Пример: маска и признак «только группы»


Функция НоменклатураФильтр(Лимит = 20, Маска = "", ТолькоГруппы = Ложь) Экспорт
    // 1) База
    ТекстQ = "
    |ВЫБРАТЬ ПЕРВЫЕ &Лимит
    |    Ном.Ссылка       КАК ID,
    |    Ном.Наименование КАК Name
    |ИЗ Справочник.Номенклатура КАК Ном
    ";

    // 2) WHERE (опциональные куски)
    ЕстьУсловия = Ложь;
    Если НЕ ПустаяСтрока(Маска) Тогда
        ТекстQ = ТекстQ + "
        |ГДЕ Ном.Наименование ПОДОБНО &Маска
        ";
        ЕстьУсловия = Истина;
    КонецЕсли;

    Если ТолькоГруппы Тогда
        ТекстУсл = "Ном.ЭтоГруппа = &ТолькоГруппы";
        Если ЕстьУсловия Тогда
            ТекстQ = ТекстQ + "
            |И " + ТекстУсл;
        Иначе
            ТекстQ = ТекстQ + "
            |ГДЕ " + ТекстУсл;
            ЕстьУсловия = Истина;
        КонецЕсли;
    КонецЕсли;

    // 3) ORDER
    ТекстQ = ТекстQ + "
    |УПОРЯДОЧИТЬ ПО Name
    ";

    // 4) Вызов Unload с позиционными параметрами в порядке появления в тексте:
    // &Лимит [,&Маска] [,&ТолькоГруппы]
    Если НЕ ПустаяСтрока(Маска) И ТолькоГруппы Тогда
        Возврат A1sQ.Unload(ТекстQ, Лимит, Маска, Истина);
    ИначеЕсли НЕ ПустаяСтрока(Маска) Тогда
        Возврат A1sQ.Unload(ТекстQ, Лимит, Маска);
    ИначеЕсли ТолькоГруппы Тогда
        Возврат A1sQ.Unload(ТекстQ, Лимит, Истина);
    Иначе
        Возврат A1sQ.Unload(ТекстQ, Лимит);
    КонецЕсли;
КонецФункции

Примечание: для читаемости держите порядок &параметров в тексте очевидным.

Паттерн BuildQ: диапазон дат и пагинация


Функция РеализацииЗаПериод(Начало, Конец, Сдвиг = 0, Лимит = 50) Экспорт
    // Пагинация: OFFSET &Сдвиг ROWS FETCH FIRST &Лимит ROWS ONLY (если платформа/СУБД поддерживают)
    ТекстQ = "
    |ВЫБРАТЬ
    |    Док.Ссылка         КАК ID,
    |    Док.Дата           КАК Dt,
    |    Док.СуммаДокумента КАК Amount
    |ИЗ Документ.РеализацияТоваровУслуг КАК Док
    |ГДЕ Док.Дата МЕЖДУ &Начало И &Конец
    |УПОРЯДОЧИТЬ ПО Dt
    ";

    // Вариант 1: просто TOP (ПЕРВЫЕ)
    Если Сдвиг = 0 Тогда
        ТекстQ = "
        |ВЫБРАТЬ ПЕРВЫЕ &Лимит
        |    Док.Ссылка         КАК ID,
        |    Док.Дата           КАК Dt,
        |    Док.СуммаДокумента КАК Amount
        |ИЗ Документ.РеализацияТоваровУслуг КАК Док
        |ГДЕ Док.Дата МЕЖДУ &Начало И &Конец
        |УПОРЯДОЧИТЬ ПО Dt
        ";
        Возврат A1sQ.Unload(ТекстQ, Лимит, Начало, Конец); // порядок: &Лимит, &Начало, &Конец
    КонецЕсли;

    // Вариант 2: если требуется сдвиг — используйте ExecuteQ и фильтруйте вручную или применяйте совместимые конструкции
    // (пример покажем через ExecuteQ — День 4)
    Возврат A1sQ.ExecuteQ(ТекстQ, Начало, Конец);
КонецФункции

Если платформа не поддерживает OFFSET/FETCH, делаем сдвиг на уровне приложения (через ExecuteQ и пропуск первых N строк).

Паттерн BuildQ: выбор колонок и алиасы

Выбирайте только нужные поля — ускоряет обработку.
Ставьте читаемые алиасы: КАК ID, КАК Name, КАК Amount.
Алиасы — это имена колонок в ТаблицаЗначений и в выборке Выбрать().


ТекстQ = "
|ВЫБРАТЬ ПЕРВЫЕ &Лимит
|    Ном.Ссылка       КАК ID,
|    Ном.Наименование КАК Name
|ИЗ Справочник.Номенклатура КАК Ном
|ГДЕ Ном.Наименование ПОДОБНО &Маска
|УПОРЯДОЧИТЬ ПО Name
";
Таб = A1sQ.Unload(ТекстQ, 10, "%кабель%");
Имена = Таб.ВыгрузитьКолонку("Name"); // удобно для UI

Ещё примеры (шаблоны BuildQ)

Динамический ORDER BY


Функция НомВПорядке(ПолеСорт = "Name", Лимит = 20) Экспорт
    // Безопасный whitelist полей
    Доступные = Новый Множество;
    Доступные.Добавить("Name");
    Доступные.Добавить("ID");

    Если НЕ Доступные.Содержит(ПолеСорт) Тогда
        ПолеСорт = "Name";
    КонецЕсли;

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

    Возврат A1sQ.Unload(ТекстQ, Лимит);
КонецФункции

Секции WHERE, которые легко выключать


Функция НомФильтр(Лимит = 50, Маска = "", ЕстьОстатки = Неопределено) Экспорт
    ТекстQ = "
    |ВЫБРАТЬ ПЕРВЫЕ &Лимит
    |    Ном.Ссылка       КАК ID,
    |    Ном.Наименование КАК Name
    |ИЗ Справочник.Номенклатура КАК Ном
    ";

    ЕстьУсловия = Ложь;

    Если НЕ ПустаяСтрока(Маска) Тогда
        ТекстQ = ТекстQ + "
        |ГДЕ Ном.Наименование ПОДОБНО &Маска
        ";
        ЕстьУсловия = Истина;
    КонецЕсли;

    Если ТипЗнч(ЕстьОстатки) = Тип("Булево") Тогда
        ТекстУсл = "ЕСТЬNULL(Остатки.КоличествоОстаток, 0) " + ?(ЕстьОстатки, "> 0", "= 0");
        Если ЕстьУсловия Тогда
            ТекстQ = ТекстQ + "
            |И " + ТекстУсл;
        Иначе
            ТекстQ = ТекстQ + "
            |ГДЕ " + ТекстУсл;
            ЕстьУсловия = Истина;
        КонецЕсли;
    КонецЕсли;

    ТекстQ = ТекстQ + "
    |УПОРЯДОЧИТЬ ПО Name
    ";

    // Порядок параметров: &Лимит, [&Маска]
    Если НЕ ПустаяСтрока(Маска) Тогда
        Возврат A1sQ.Unload(ТекстQ, Лимит, Маска);
    Иначе
        Возврат A1sQ.Unload(ТекстQ, Лимит);
    КонецЕсли;
КонецФункции

Практика (15–30 минут)

Соберите запрос с опциональными условиями (&Маска, &ТолькоГруппы), вызовите Unload c корректным порядком параметров.
Сделайте выборку документов за период: &Начало, &Конец, лимит через ПЕРВЫЕ &Лимит.
Добавьте whitelist-сортировку по полю (Name/ID).
Получите массив имён через ВыгрузитьКолонку("Name").

Чек-лист

□ Понимаю позиционные параметры (П1..П8) и порядок в тексте.
□ Умею собирать WHERE/ORDER блоки условно (BuildQ-паттерн).
□ Держу алиасы и набор колонок минимальными.

Что дальше

День 6: QT — быстрые запросы-шаблоны (шорткаты для частых операций).