Выполнение запросов

Для начала работы с базой данных получите объект соединения:

/** @var \Bitrix\Main\DB\Connection $db */
        $db = \Bitrix\Main\Application::getConnection();

Как выполнять SELECT-запросы

Сделать базовый запрос:

$result = $db->query('SELECT `ID`, `NAME` FROM b_user');

Ограничить количество результатов:

// Вернет первые 10 записей
        $result = $db->query('SELECT `ID`, `NAME` FROM b_user', 10);
        // SQL: SELECT `ID`, `NAME` FROM b_user LIMIT 0,10

Ограничить количество результатов со смещением:

// Вернет 10 записей, начиная с 5-й
        $result = $db->query('SELECT `ID`, `NAME` FROM b_user', 5, 10);
        // SQL: SELECT `ID`, `NAME` FROM b_user LIMIT 5,10

Получить скалярное значение:

// Вернет значение первого столбца первой строки
        $id = $db->queryScalar('SELECT `ID`, `NAME` FROM b_user');
        // SQL: SELECT `ID`, `NAME` FROM b_user LIMIT 0,1

Выполнить запрос без возврата результата:

$db->queryExecute('UPDATE b_user SET ACTIVE = "Y" WHERE DATE_REGISTER > "2024-01-01"');

Важно

Параметры binds в методах query, queryScalar и queryExecute не обеспечивают защиту от SQL-инъекций. Для защиты используйте SqlExpression или SqlHelper.

Как выполнять INSERT-запросы

Добавить одну запись:

$id = $db->add('my_table', [
            'NAME' => 'example',
            'CONTENT' => 'Про "базы" данных'
        ]);
        // SQL: INSERT INTO `my_table`(`NAME`, `CONTENT`) VALUES ('example', 'про \" базы \'')

Сделать массовое добавление записей:

$lastId = $db->addMulti('my_table', [
            [
                'NAME' => 'example one',
                'CONTENT' => 'Первая статья'
            ],
            [
                'NAME' => 'example two',
                'CONTENT' => "Вторая статья"
            ]
        ]);
        // SQL: INSERT INTO `my_table` (`NAME`, `CONTENT`) VALUES ('example one', 'про \" базы \''), ('example two', '\';SELECT * FROM b_user WHERE ID = 1')

Методы add() и addMulti() преобразуют значения и проверяют существование столбцов в таблице. Если указанного столбца нет, метод исключает его из запроса:

/**
         * Выполнится запрос:
         * INSERT INTO `b_user`(`NAME`) VALUES ('habr')
         */
        $insertedId = $db->add('b_user', [
            'NAME' => 'example',
            'NOT_EXISTS_COLUMN' => 'что я тут делаю?', // Этот столбец пропустят, так как его нет в таблице
        ]);

Методы работы с таблицами

Создать новую таблицу

Создает новую таблицу метод createTable. Параметры метода:

  • $tableName — имя создаваемой таблицы,

  • $arFields — массив полей таблицы в формате 'FIELD_NAME' => FieldObject.

$db->createTable('my_table', [
        
            // Поле ID — целочисленный идентификатор
            // Используем IntegerField с параметрами:
            'ID' => new \Bitrix\Main\ORM\Fields\IntegerField('ID', [
                'primary' => true,      // Указываем что это первичный ключ
                'autocomplete' => true  // Включаем автоинкремент, то есть значение будет увеличиваться автоматически
            ]),
        
            // Поле NAME — строковое поле для хранения названия
            // Используем StringField с параметрами:
            'NAME' => new \Bitrix\Main\ORM\Fields\StringField('NAME', [
                'size' => 255  // Максимальная длина строки — 255 символов
            ]),
        ]);

Удалить существующую таблицу

Удаляет таблицу метод dropTable. В методе нужно указать название таблицы.

$db->dropTable('my_table');

Создать индекс

Создает индекс метод createIndex. Параметры метода:

  • $indexName — имя создаваемого индекса,

  • $tableName — имя таблицы,

  • $columns — массив имен столбцов для индекса,

  • $unique — флаг уникальности индекса, по умолчанию false.

$db->createIndex('idx_name', 'my_table', ['NAME'], true);

Создать первичный ключ для таблицы

Создает первичный ключ метод createPrimaryIndex. Параметры метода:

  • $tableName — имя таблицы,

  • $columnNames — массив имен столбцов, входящих в первичный ключ.

$db->createPrimaryIndex('my_table', ['ID']);

Удалить столбец из таблицы

Удаляет столбец метод dropColumn. Параметры метода:

  • $tableName — имя таблицы,

  • $columnName — имя удаляемого столбца.

$db->dropColumn('my_table', 'DESCRIPTION');

Переименовывать таблицу

Переименовывает таблицу метод renameTable. Параметры метода:

  • $oldTableName — текущее имя таблицы,

  • $newTableName — новое имя таблицы.

$db->renameTable('old_table', 'new_table');

Очистить данные в таблице

Очищает данные метод truncateTable. В методе нужно указать имя таблицы.

$db->truncateTable('my_table');

Проверить существование таблицы

Проверяет существование таблицы метод isTableExists. Метод возвращает true если таблица существует, false если нет.

$db->isTableExists('my_table');

Вернуть описание полей таблицы

Возвращает описание полей таблицы метод getTableFields. Метод возвращает ассоциативный массив с описанием полей таблицы.

$fields = $db->getTableFields('my_table');

Как работать с результатами запросов

Выполнение запроса на чтение возвращает объект \Bitrix\Main\DB\Result, который предоставляет несколько способов работы с данными.

Использовать как итератор:

$result = $connection->query('SELECT * FROM b_user');
        foreach ($result as $row) {
            $id = $row['ID'];
        }

Читать построчно:

while ($row = $result->fetch()) {
            $id = $row['ID'];
        }

Разница между fetch() и fetchRaw()

  • fetch() — автоматически преобразует данные согласно настройкам системы.

  • fetchRaw() — возвращает данные в оригинальном формате.

// fetch() — с преобразованием типов
        $row = $result->fetch();
        // [
        //    'ID' => 1,
        //    'ACTIVE' => 'Y',
        //    'DATE_REGISTER' => Bitrix\Main\Type\DateTime Object
        // ]
        
        // fetchRaw() — оригинальные данные
        $row = $result->fetchRaw();
        // [
        //    'ID' => 1,
        //    'ACTIVE' => 'Y', 
        //    'DATE_REGISTER' => '2021-12-29 09:50:14'
        // ]

Конвертеры и модификаторы данных

Добавляйте свои конвертеры столбцов и модификаторы выборки, чтобы преобразовывать данные перед использованием.

Конвертер столбца. Преобразует значение одного столбца. Это полезно, если нужно изменить формат данных. Например, можно изменить формат даты:

$resultIterator = \Bitrix\Main\Application::getConnection()->query(
            'SELECT ID, ACTIVE, DATE_REGISTER FROM b_user'
        );
        
        // Конвертер для столбца DATE_REGISTER (преобразует строку в timestamp)
        $resultIterator->setConverters([
            'DATE_REGISTER' => static fn($value) => $value ? strtotime($value) : null,
        ]);

Модификатор выборки. Обрабатывает всю выборку данных. Это полезно, если требуется добавить вычисляемые поля или сложную логику обработки. Например, можно добавить новое поле на основе существующих:

// Модификатор добавляет поле ACTIVE_BOOL (true/false на основе ACTIVE)
        $resultIterator->addFetchDataModifier(static function(array $row) {
            $row['ACTIVE_BOOL'] = $row['ACTIVE'] === 'Y';
            return $row;
        });

Данные после обработки:

foreach ($resultIterator as $row) {
            /**
             * [ID] => 1
             * [ACTIVE] => Y
             * [DATE_REGISTER] => 1640771366
             * [ACTIVE_BOOL] => true
             */
            print_r($row);
            break;
        }

Дополнительные методы

// Количество выбранных строк
        $count = $result->getSelectedRowsCount();
        
        // Объект драйвера БД. Например, для MySQL это экземпляр класса mysqli_result
        $resource = $result->getResource();
        
        // Список полей в результате
        $fields = $result->getFields();

Объект Result поддерживает только последовательное чтение данных — после прохода по результатам повторный запрос данных невозможен.

Предыдущая
Конфигурация
Следующая
Формирование запросов