Highload-блоки в Битрикс — когда и зачем использовать

<?php
use Bitrix\Highloadblock\HighloadBlockTable;

$result = HighloadBlockTable::add([
    'NAME' => 'Cities',
    'TABLE_NAME' => 'b_hlbd_cities',
]);
if ($result->isSuccess()) {
    $hlblockId = $result->getId();
    // Добавляем поля
    $userField = new \CUserTypeEntity();
    // Название города
    $userField->Add([
        'ENTITY_ID' => 'HLBLOCK_' . $hlblockId,
        'FIELD_NAME' => 'UF_NAME',
        'USER_TYPE_ID' => 'string',
        'MANDATORY' => 'Y',
        'EDIT_FORM_LABEL' => ['ru' => 'Название'],
        'LIST_COLUMN_LABEL' => ['ru' => 'Название'],
    ]);
    // Код региона
    $userField->Add([
        'ENTITY_ID' => 'HLBLOCK_' . $hlblockId,
        'FIELD_NAME' => 'UF_REGION_CODE',
        'USER_TYPE_ID' => 'string',
        'MANDATORY' => 'N',
    ]);
    // Население (число)
    $userField->Add([
        'ENTITY_ID' => 'HLBLOCK_' . $hlblockId,
        'FIELD_NAME' => 'UF_POPULATION',
        'USER_TYPE_ID' => 'integer',
        'MANDATORY' => 'N',
    ]);
}

<?php
use Bitrix\Main\Loader;
use Bitrix\Highloadblock\HighloadBlockTable;
Loader::includeModule('highloadblock');
// По ID
$hlblock = HighloadBlockTable::getById(1)->fetch();
// По имени
$hlblock = HighloadBlockTable::getList([
    'filter' => ['NAME' => 'Cities']
])->fetch();
// Получаем класс для работы с данными
$entity = HighloadBlockTable::compileEntity($hlblock);
$entityClass = $entity->getDataClass();
// Теперь $entityClass — это полноценный DataManager
// Например: CityTable (автогенерируемое имя)

<?php
// CREATE — добавление
$result = $entityClass::add([
    'UF_NAME' => 'Москва',
    'UF_REGION_CODE' => '77',
    'UF_POPULATION' => 12600000,
]);
if ($result->isSuccess()) {
    $id = $result->getId();
}
// READ — чтение
$cities = $entityClass::getList([
    'select' => ['ID', 'UF_NAME', 'UF_POPULATION'],
    'filter' => ['>=UF_POPULATION' => 1000000],
    'order' => ['UF_POPULATION' => 'DESC'],
    'limit' => 10,
])->fetchAll();
// Одна запись по ID
$city = $entityClass::getById(1)->fetch();
// UPDATE — обновление
$result = $entityClass::update($id, [
    'UF_POPULATION' => 12700000,
]);
// DELETE — удаление
$result = $entityClass::delete($id);

<?php
// Сложный фильтр
$cities = $entityClass::getList([
    'filter' => [
        'LOGIC' => 'OR',
        [
            '>=UF_POPULATION' => 1000000,
        ],
        [
            'UF_REGION_CODE' => '77', // Москва
        ],
    ],
    'order' => ['UF_NAME' => 'ASC'],
])->fetchAll();
// Подсчёт
$count = $entityClass::getCount([
    '>=UF_POPULATION' => 500000,
]);
// Группировка и агрегация
$stats = $entityClass::getList([
    'select' => [
        'UF_REGION_CODE',
        new \Bitrix\Main\Entity\ExpressionField('TOTAL', 'COUNT(*)'),
        new \Bitrix\Main\Entity\ExpressionField('AVG_POP', 'AVG(%s)', ['UF_POPULATION']),
    ],
    'group' => ['UF_REGION_CODE'],
])->fetchAll();

<?php
// Создаём HL-блок UserActionsLog с полями:
// UF_USER_ID (integer)
// UF_ACTION (string)
// UF_DATA (text)
// UF_CREATED_AT (datetime)
class UserActionLogger
{
    private static $entityClass = null;
    public static function getEntityClass(): string
    {
        if (self::$entityClass === null) {
            $hlblock = HighloadBlockTable::getList([
                'filter' => ['NAME' => 'UserActionsLog']
            ])->fetch();
            $entity = HighloadBlockTable::compileEntity($hlblock);
            self::$entityClass = $entity->getDataClass();
        }
        return self::$entityClass;
    }
    public static function log(int $userId, string $action, array $data = []): void
    {
        $class = self::getEntityClass();
        $class::add([
            'UF_USER_ID' => $userId,
            'UF_ACTION' => $action,
            'UF_DATA' => json_encode($data, JSON_UNESCAPED_UNICODE),
            'UF_CREATED_AT' => new \Bitrix\Main\Type\DateTime(),
        ]);
    }
    public static function getUserActions(int $userId, int $limit = 100): array
    {
        $class = self::getEntityClass();
        return $class::getList([
            'filter' => ['UF_USER_ID' => $userId],
            'order' => ['UF_CREATED_AT' => 'DESC'],
            'limit' => $limit,
        ])->fetchAll();
    }
}
// Использование
UserActionLogger::log($USER->GetID(), 'order.create', ['order_id' => 12345]);

<?php
// HL-блок Brands:
// UF_NAME, UF_CODE, UF_LOGO, UF_SORT, UF_ACTIVE
class BrandRepository
{
    private string $entityClass;
    public function __construct()
    {
        $hlblock = HighloadBlockTable::getList([
            'filter' => ['NAME' => 'Brands']
        ])->fetch();
        $entity = HighloadBlockTable::compileEntity($hlblock);
        $this->entityClass = $entity->getDataClass();
    }
    public function getActiveList(): array
    {
        $class = $this->entityClass;
        return $class::getList([
            'filter' => ['UF_ACTIVE' => true],
            'order' => ['UF_SORT' => 'ASC', 'UF_NAME' => 'ASC'],
            'cache' => ['ttl' => 3600, 'cache_joins' => true],
        ])->fetchAll();
    }
    public function getByCode(string $code): ?array
    {
        $class = $this->entityClass;
        return $class::getList([
            'filter' => ['UF_CODE' => $code, 'UF_ACTIVE' => true],
            'limit' => 1,
        ])->fetch() ?: null;
    }
}

-- Добавляем индекс вручную
ALTER TABLE b_hlbd_cities ADD INDEX idx_region (UF_REGION_CODE);
ALTER TABLE b_hlbd_cities ADD INDEX idx_population (UF_POPULATION);
-- Составной индекс
ALTER TABLE b_hlbd_user_actions ADD INDEX idx_user_date (UF_USER_ID, UF_CREATED_AT);

<?php
// Встроенное кэширование D7
$items = $entityClass::getList([
    'filter' => [...],
    'cache' => [
        'ttl' => 3600, // 1 час
        'cache_joins' => true,
    ],
])->fetchAll();

// Или через Bitrix Cache
$cache = \Bitrix\Main\Data\Cache::createInstance();
if ($cache->initCache(3600, 'brands_list')) {
    $brands = $cache->getVars()['brands'];
} elseif ($cache->startDataCache()) {
    $brands = (new BrandRepository())->getActiveList();
    $cache->endDataCache(['brands' => $brands]);
}