Связи между ORM-сущностями (referenceField)

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

Что такое ReferenceField

Bitrix\Main\ORM\Fields\Relations\Reference (и его прежний алиас ReferenceField) описывает связь текущей сущности с другой. Поле объявляется в getMap() и хранит не значение, а правило соединения — целевую сущность и условие Join::on().

Минимальный пример: заказ ссылается на пользователя.

use Bitrix\Main\ORM\Fields\Relations\Reference;
use Bitrix\Main\ORM\Query\Join;

(new Reference(
  'USER',
  \Bitrix\Main\UserTable::class,
  Join::on('this.USER_ID', 'ref.ID')
))->configureJoinType('inner');

После этого поля пользователя доступны как USER.NAME, USER.EMAIL — ORM сама подставит нужный JOIN.

Условия соединения Join::on

Класс Bitrix\Main\ORM\Query\Join строит условие связи. Псевдонимы this и ref обозначают текущую и связанную сущности:

• Join::on('this.USER_ID', 'ref.ID') — простое равенство полей;
• ->where('ref.ACTIVE', 'Y') — дополнительное условие на связанную таблицу;
• ->whereColumn(...) — сравнение двух колонок;
• ->whereIn(...) и логические группы через with().

Составное условие связи выглядит так:

Join::on('this.SECTION_ID', 'ref.ID')
  ->where('ref.ACTIVE', 'Y')
  ->where('ref.IBLOCK_ID', 5);

Тип соединения: inner, left, right

Тип JOIN задаётся методом configureJoinType() у поля-ссылки либо автоматически подбирается запросом. По умолчанию, если в условии есть обязательные ограничения, ORM может выбрать LEFT.

Если поле объявлено как left, но в фильтре запроса появляется условие на USER.ACTIVE = 'Y', соединение может ужесточиться до inner — учитывайте это при отладке количества строк.

Выборка данных по связи

Обращение к связанным полям идёт через точечную нотацию в любом параметре getList(): select, filter, order, group.

$rows = OrderTable::getList([
  'select' => ['ID', 'SUM', 'USER_NAME' => 'USER.NAME'],
  'filter' => ['=USER.ACTIVE' => 'Y', '>SUM' => 1000],
  'order' => ['USER.LAST_NAME' => 'ASC'],
])->fetchAll();

• псевдоним в select ('USER_NAME' => 'USER.NAME') задаёт ключ в результате;
• цепочки связей допускают несколько уровней: USER.GROUP.NAME, если такие reference объявлены;
• ORM добавляет JOIN только когда поле связи реально используется в запросе.

Reference на лету через registerRuntimeField

Если связь нужна разово и незачем прописывать её в getMap(), объявите reference прямо в запросе через registerRuntimeField():

use Bitrix\Main\ORM\Fields\Relations\Reference;
use Bitrix\Main\ORM\Query\Join;

$result = OrderTable::query()
  ->registerRuntimeField(
    'PAYMENT',
    new Reference('PAYMENT', PaymentTable::class,
      Join::on('this.ID', 'ref.ORDER_ID'))
  )
  ->addSelect('PAYMENT.PAID')
  ->setFilter(['=PAYMENT.PAID' => 'Y'])
  ->exec();

Такой подход удобен, когда связь зависит от контекста (разные внешние таблицы) или сущность вам не принадлежит и править её getMap() нельзя.

Связь многие-ко-многим

«Многие-ко-многим» в Битрикс реализуется через промежуточную таблицу и два reference. Классический путь — объявить в основной сущности связь на связующую таблицу, а в ней — на целевую:

1. таблица ProductTable и TagTable;
2. связующая ProductTagTable с полями PRODUCT_ID, TAG_ID и reference на обе стороны;
3. в запросе идёте по цепочке PRODUCT_TAG.TAG.NAME.

Начиная с новых версий модуля main доступна и специализированная связь ManyToMany (Bitrix\Main\ORM\Fields\Relations\ManyToMany), которая скрывает промежуточную таблицу. Но для полного контроля над схемой чаще используют явные reference на связующую сущность.

Итог

ReferenceField переносит логику соединений из SQL в декларативную модель: один раз описываете Join::on() — и обращаетесь к полям связанных таблиц через точку в фильтрах, выборке и сортировке. Помните про тип соединения, ON-условия против WHERE и размножение строк при «один-ко-многим». Runtime-reference закрывает разовые связи без правки getMap().

Мы в B2Bsite проектируем модель данных со сложными связями между сущностями каталога, заказов и учётных систем. Если ваш проект перерос простые инфоблоки и нуждается в чистой ORM-схеме с корректными join'ами, поможем спроектировать и оптимизировать архитектуру данных.