Гибкая выборка в D7 ORM: Мастер-класс по классу Query

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

Для таких задач в D7 ORM существует специальный класс-конструктор — \Bitrix\Main\Entity\Query.

По сути, ::getList() — это всего лишь удобная «обертка» над Query.

Использование Query напрямую дает вам полный контроль над каждым аспектом запроса.

Когда использовать Query вместо getList?

• Когда фильтры, сортировка или выбираемые поля добавляются в зависимости от множества условий.
• Когда нужно построить сложный подзапрос.
• Когда нужно получить итоговый SQL-текст запроса для отладки, не выполняя его.

Шаг 1: Создание объекта Query

Для начала нужно создать экземпляр класса, передав ему объект сущности.

use Bitrix\Main\Loader;
use Bitrix\Iblock\ElementTable;
use Bitrix\Main\Entity\Query; // Импортируем класс Query

Loader::includeModule('iblock');

// Получаем сущность
$entity = ElementTable::getEntity();

// Создаем объект конструктора запросов
$query = new Query($entity);

Или, используя статический хелпер, что короче и предпочтительнее:

$query = ElementTable::query();

Шаг 2: Построение запроса

Теперь мы можем «собирать» наш запрос по частям, используя сеттеры.

$query = ElementTable::query();

// Установка полей для выборки (аналог select)
$query->setSelect(['ID', 'NAME', 'CODE']);

// Установка фильтрации (аналог filter)
$query->setFilter(['=IBLOCK_ID' => 5, '=ACTIVE' => 'Y']);

// Установка сортировки (аналог order)
$query->setOrder(['SORT' => 'ASC']);

// Установка лимита и смещения (аналог limit и offset)
$query->setLimit(10);
$query->setOffset(20);

Динамическое добавление условий

В этом и есть главная сила Query. Вы можете добавлять условия по мере необходимости.

$query = ElementTable::query();
$query->setSelect(['ID', 'NAME']);
$query->setFilter(['=IBLOCK_ID' => 5]);

// Если в запросе есть параметр поиска, добавляем фильтр по имени
if (!empty($_GET['q'])) {
    $query->addFilter('%NAME', $_GET['q']);
}

// Если выбрана сортировка, добавляем ее
if ($_GET['sort'] === 'name') {
    $query->addOrder('NAME', 'ASC');
} else {
    $query->addOrder('ID', 'DESC');
}

• set… — полностью перезаписывает параметр.
• add… — добавляет значение к параметру (например, addFilter, addOrder).

Шаг 3: Выполнение запроса и получение результата

После того как запрос собран, его нужно выполнить методом exec(). Он возвращает стандартный объект \Bitrix\Main\DB\Result.

// Выполняем собранный запрос
$result = $query->exec();

// Обрабатываем результат как обычно
while ($row = $result->fetch()) {
    echo $row['NAME'] . '<br>';
}

Отладка: Получение SQL-запроса

Иногда нужно посмотреть, какой именно SQL-запрос сгенерировал ORM. Метод getQuery() вернет вам готовую строку.

$query = ElementTable::query()
    ->setSelect(['ID', 'NAME'])
    ->setFilter(['=IBLOCK_ID' => 5])
    ->setLimit(10);

// Получаем SQL-строку, не выполняя запрос
$sql = $query->getQuery();

echo $sql;
// Выведет: SELECT `iblock_element`.`ID` AS `ID`, `iblock_element`.`NAME` AS `NAME` FROM `b_iblock_element` `iblock_element` WHERE `iblock_element`.`IBLOCK_ID` = 5 LIMIT 10

Вывод:
Класс Query — это профессиональный инструмент для построения сложных и динамических запросов в D7 ORM. Он дает полный контроль над каждым этапом формирования запроса и является незаменимым помощником при работе с нетривиальными фильтрами, а также при отладке.

D7 ORM, Query class, Bitrix ORM, setSelect, setFilter, addOrder, setLimit, exec, getQuery, построитель запросов.