Query Builder в Битрикс: полное руководство с примерами запросов и кода

При разработке современных проектов на 1С-Битрикс все чаще используется D7 API и ORM. Одним из важных инструментов ORM является Query Builder — специальный конструктор запросов, который позволяет гибко формировать выборки данных без написания сложного SQL-кода вручную. С помощью Query Builder разработчик может строить сложные запросы, использовать JOIN, добавлять вычисляемые поля, выполнять группировку данных и создавать динамические фильтры. В этой статье подробно рассмотрим возможности Query Builder в Битрикс и приведем практические примеры кода.

Что такое Query Builder

Query Builder — это объектный конструктор запросов в ORM Битрикс. Он позволяет формировать SQL-запросы через PHP-код. Вместо написания SQL:

SELECT ID, LOGIN
FROM b_user
WHERE ACTIVE = 'Y'
ORDER BY ID DESC

можно использовать Query Builder:

$query = \Bitrix\Main\UserTable::query();

$query
    ->setSelect(['ID', 'LOGIN'])
    ->setFilter(['ACTIVE' => 'Y'])
    ->setOrder(['ID' => 'DESC']);

При выполнении ORM автоматически сформирует необходимый SQL-запрос.

Зачем использовать Query Builder

Основные преимущества:

удобное построение сложных запросов;
безопасная работа с данными;
отсутствие ручного SQL;
поддержка JOIN;
поддержка агрегатных функций;
удобная фильтрация;
высокая читаемость кода;
интеграция с ORM D7.

Особенно полезен Query Builder в крупных проектах с большим количеством выборок данных.

Нужна помощь с Битрикс?

Создание объекта Query

Для начала необходимо создать объект запроса. Пример:

use Bitrix\Main\UserTable;

$query = UserTable::query();

Теперь объект $query можно настраивать различными методами.

Выбор необходимых полей

Метод setSelect() позволяет указать поля для выборки.

$query
    ->setSelect([
        'ID',
        'LOGIN',
        'EMAIL'
    ]);

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

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

После настройки запроса необходимо выполнить его.

$result = $query->exec();

while ($row = $result->fetch())
{
    print_r($row);
}

Метод exec() отправляет запрос в базу данных и возвращает объект результата.

Фильтрация данных

Для фильтрации используется метод setFilter(). Пример:

$query->setFilter([
    'ACTIVE' => 'Y'
]);

Получим только активных пользователей.

Фильтр по ID

$query->setFilter([
    'ID' => 10
]);

Фильтр по логину

$query->setFilter([
    'LOGIN' => 'admin'
]);

Поиск по части строки

$query->setFilter([
    '%EMAIL' => '@gmail.com'
]);

Query Builder поддерживает все стандартные операторы ORM.

Сортировка данных

Для сортировки используется метод setOrder().

$query->setOrder([
    'ID' => 'DESC'
]);

Можно сортировать сразу по нескольким полям:

$query->setOrder([
    'LAST_NAME' => 'ASC',
    'NAME' => 'ASC'
]);

Ограничение количества записей

Для ограничения выборки используется метод setLimit().

$query->setLimit(10);

Получим только первые десять записей. Аналог SQL:

LIMIT 10

Постраничная выборка

Для пагинации применяется метод setOffset().

$query
    ->setLimit(20)
    ->setOffset(40);

Будут выбраны записи с 41 по 60. Это удобно при выводе больших списков пользователей или товаров.

Использование runtime-полей

Одной из самых полезных возможностей Query Builder являются вычисляемые поля. Пример объединения имени и фамилии:

use Bitrix\Main\ORM\Fields\ExpressionField;

$query->registerRuntimeField(
    new ExpressionField(
        'FULL_NAME',
        "CONCAT(%s,' ',%s)",
        ['NAME', 'LAST_NAME']
    )
);

Теперь поле можно добавить в выборку:

$query->setSelect([
    'ID',
    'FULL_NAME'
]);

Результат будет содержать готовое полное имя пользователя.

Группировка данных

Для группировки используется метод setGroup(). Пример:

$query->setGroup([
    'ACTIVE'
]);

Аналог SQL:

GROUP BY ACTIVE

Группировка часто применяется в отчетах и статистике.

Подсчет количества записей

Можно использовать агрегатные функции. Пример:

use Bitrix\Main\ORM\Fields\ExpressionField;

$query->registerRuntimeField(
    new ExpressionField(
        'CNT',
        'COUNT(*)'
    )
);

$query->setSelect(['CNT']);

В результате будет получено количество записей.

JOIN через Query Builder

Одно из главных преимуществ Query Builder — работа со связями между таблицами. Для этого используется ReferenceField. Пример:

use Bitrix\Main\ORM\Fields\Relations\Reference;
use Bitrix\Main\UserGroupTable;
use Bitrix\Main\UserTable;

$query = UserGroupTable::query();

$query->registerRuntimeField(
    new Reference(
        'USER',
        UserTable::class,
        ['=this.USER_ID' => 'ref.ID']
    )
);

Теперь можно получать данные пользователя:

$query->setSelect([
    'USER.LOGIN',
    'USER.EMAIL'
]);

Фактически ORM сформирует SQL JOIN автоматически.

Получение SQL-запроса

Во время отладки полезно посмотреть итоговый SQL. Для этого используется:

echo $query->getQuery();

На экран будет выведен SQL-запрос, который ORM собирается выполнить. Это помогает быстро находить ошибки в фильтрах и связях.

Комплексный пример Query Builder

Рассмотрим полноценный запрос.

use Bitrix\Main\UserTable;

$query = UserTable::query();

$query
    ->setSelect([
        'ID',
        'LOGIN',
        'EMAIL'
    ])
    ->setFilter([
        'ACTIVE' => 'Y'
    ])
    ->setOrder([
        'ID' => 'DESC'
    ])
    ->setLimit(20);

$result = $query->exec();

while ($row = $result->fetch())
{
    print_r($row);
}

Данный запрос:

получает активных пользователей;
выбирает три поля;
сортирует по убыванию ID;
ограничивает выборку двадцатью записями.

Query Builder для собственных ORM-сущностей

Query Builder работает не только со стандартными таблицами Битрикс, но и с собственными сущностями на основе DataManager. Например:

use Local\ORM\ProductTable;

$query = ProductTable::query();

$query
    ->setSelect(['ID', 'NAME'])
    ->setOrder(['NAME' => 'ASC']);

Подход одинаков для любых ORM-классов.

Типичные ошибки при работе с Query Builder

Unknown field definition

Ошибка означает, что указано несуществующее поле. Необходимо проверить название поля в методе getMap().

Runtime field not found

Следует убедиться, что runtime-поле зарегистрировано до выполнения запроса.

Empty result

Причины:

неверный фильтр;
отсутствуют данные;
ошибка в JOIN;
неправильно указан namespace ORM-класса.

Низкая производительность

Часто возникает при выборке всех полей:

setSelect(['*'])

Лучше выбирать только необходимые поля.

Когда использовать Query Builder

Query Builder рекомендуется применять в следующих случаях:

сложные ORM-запросы;
статистика и отчеты;
динамические фильтры;
работа со связями между таблицами;
агрегатные функции;
кастомные сущности DataManager.

Для простых выборок достаточно использовать getList(), однако для сложной бизнес-логики Query Builder предоставляет значительно больше возможностей.

Заключение

Query Builder в Битрикс — это мощный инструмент ORM D7 для построения сложных SQL-запросов через объектный интерфейс. Он позволяет выполнять фильтрацию, сортировку, группировку, использовать JOIN и вычисляемые поля без написания SQL вручную. Использование Query Builder делает код более безопасным, удобным для сопровождения и соответствует современным стандартам разработки на платформе 1С-Битрикс.