Метод upsert

Метод upsert применяется к запросу Query Builder и выполняет вставку новых записей, либо обновление существующих, если запись с указанными ключами уже присутствует в таблице. Первым параметром передаётся массив данных для вставки или обновления, вторым - массив уникальных ключей или колонок для проверки существования записи, третьим - массив колонок, которые следует обновить в случае конфликта.

Синтаксис

<?php
	DB::table($table)->upsert($values, $uniqueBy, $update);
?>

Пример с одной записью

Давайте вставим нового пользователя, либо обновим существующего с email 'user@example.com':

<?php
	use IlluminateSupportFacadesDB;
	
	$res = DB::table('users')->upsert(
		[
			'email' => 'user@example.com',
			'name' => 'John Doe',
			'age' => 25
		],
		['email'],
		['name', 'age']
	);
	
	echo $res;
?>

Результат выполнения кода:

"1"

Метод возвращает количество затронутых строк.

Пример с несколькими записями

Давайте вставим сразу несколько пользователей, обновляя их имена и возраст при совпадении email:

<?php
	use IlluminateSupportFacadesDB;
	
	$res = DB::table('users')->upsert(
		[
			[
				'email' => 'user1@example.com',
				'name' => 'Alice',
				'age' => 30
			],
			[
				'email' => 'user2@example.com',
				'name' => 'Bob',
				'age' => 28
			]
		],
		['email'],
		['name', 'age']
	);
	
	echo $res;
?>

Результат выполнения кода:

"2"

Пример с обновлением всех колонок

Давайте обновим все поля при совпадении уникального ключа:

<?php
	use IlluminateSupportFacadesDB;
	
	$res = DB::table('users')->upsert(
		[
			'id' => 1,
			'email' => 'updated@example.com',
			'name' => 'New Name',
			'age' => 35
		],
		['id'],
		['email', 'name', 'age']
	);
	
	echo $res;
?>

Результат выполнения кода:

"1"

При совпадении первичного ключа id все перечисленные колонки будут обновлены.

Пример с составным уникальным ключом

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

<?php
	use IlluminateSupportFacadesDB;
	
	$res = DB::table('product_categories')->upsert(
		[
			'product_id' => 5,
			'category_id' => 10,
			'order' => 2
		],
		['product_id', 'category_id'],
		['order']
	);
	
	echo $res;
?>

Результат выполнения кода:

"1"

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

метод insert,
который вставляет новые записи в таблицу
метод update,
который обновляет существующие записи
метод updateOrInsert,
который выполняет обновление или вставку записи
метод insertGetId,
который вставляет запись и возвращает её идентификатор