Подготовить вставку с обновлением SqlHelper::prepareMerge

Модуль: main — подключать отдельно не нужно

Доступно с версии: 15.5.0

Метод SqlHelper::prepareMerge строит запрос, который добавляет строку, а если строка с таким ключом уже есть — обновляет ее. Значения метод экранирует и преобразует по типам колонок.

Сигнатура метода в классе Bitrix\Main\DB\SqlHelper:

abstract public function prepareMerge($tableName, array $primaryFields, array $insertFields, array $updateFields);

Параметры

Обязательные параметры обозначены *

Параметр Тип Описание
tableName* string Задает имя таблицы. Таблица должна существовать
primaryFields* string[] Задает колонки уникального ключа. Реализация MySQL не использует параметр. В PostgreSQL список не должен быть пустым
insertFields* array Задает значения для вставки в виде имя колонки => значение
updateFields* array Задает значения для обновления в виде имя колонки => значение. Метод подставляет объект SqlExpression собранным SQL-фрагментом

Тип tableName в таблице описывает назначение аргумента. Сигнатура PHP не объявляет его.

Возвращаемое значение

Метод возвращает массив из одного элемента — текста запроса.

Реализация Запрос
MysqliSqlHelper INSERT INTO ... VALUES (...) ON DUPLICATE KEY UPDATE ...
PgsqlSqlHelper INSERT INTO ... VALUES (...) ON CONFLICT (<primaryFields>) DO UPDATE SET ...

Метод возвращает пустой текст запроса, если в insertFields или updateFields нет ни одной колонки таблицы. В PostgreSQL то же происходит при пустом primaryFields.

Исключения

Исключение Когда возникает
Bitrix\Main\DB\SqlQueryException В MySQL таблицы нет
Bitrix\Main\DB\ConnectionException Подключиться к базе данных не удалось
Bitrix\Main\ArgumentException Код передал для колонки даты и времени непустое значение, но не объект Bitrix\Main\Type\Date
\Error Код передал для колонки даты без времени непустое значение, но не объект Bitrix\Main\Type\Date

Примеры

Пример. Код дважды выполняет вставку с обновлением. Вторая вставка увеличивает счетчик существующей строки:

<?php
use Bitrix\Main\Application;
use Bitrix\Main\DB\SqlExpression;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$connection = Application::getConnection();
$helper = $connection->getSqlHelper();

$connection->queryExecute('CREATE TABLE demo_api_counters (CODE VARCHAR(20) NOT NULL PRIMARY KEY, CNT INT NOT NULL)');

try
{
    for ($i = 0; $i < 2; $i++)
    {
        [$sql] = $helper->prepareMerge(
            'demo_api_counters',
            ['CODE'],
            ['CODE' => 'kg', 'CNT' => 1],
            ['CNT' => new SqlExpression('?# + 1', 'CNT')]
        );
        $connection->queryExecute($sql);
    }

    echo $connection->queryScalar('SELECT CNT FROM demo_api_counters');
}
finally
{
    $connection->dropTable('demo_api_counters');
}

Код выведет 2.

Смотрите также