wpdb::replace()publicWP 3.0.0

Replaces a row in the table.

A REPLACE works exactly like an INSERT, except that if an old row in the table has the same value as a new row for a PRIMARY KEY or a UNIQUE index, the old row is deleted before the new row is inserted.

Examples:

$wpdb->replace(
	'table',
	array(
		'ID'      => 123,
		'column1' => 'foo',
		'column2' => 'bar',
	)
);
$wpdb->replace(
	'table',
	array(
		'ID'      => 456,
		'column1' => 'foo',
		'column2' => 1337,
	),
	array(
		'%d',
		'%s',
		'%d',
	)
);

Method of the class: wpdb{}

No Hooks.

Return

Int|false. The number of rows affected, or false on error.

Usage

global $wpdb;
$wpdb->replace( $table, $data, $format );
$table(string) (required)
Table name.
$data(array) (required)
Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped). A primary key or unique index is required to perform a replace operation. Sending a null value will cause the column to be set to NULL - the corresponding format is ignored in this case.
$format(string[]|string)
An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data. A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
Default: null

Examples

0

#1 Replace the row with the main key ID = 1

Assuming that the table consists of three columns ID, column1, column2.

The row will be added if it does not exist or completely updated if it does. Here it is important to specify values for all fields because fields without values will get defaulted, even if they had data before.

$wpdb->replace( 'table_name', [
	'ID'      => 1,
	'column1' => 'value1',
	'column2' => 123
] );
0

#2 Specify the formats

$wpdb->replace( 
	'table', 
	[ 'column' => 'foo', 'field' => 1337 ], 
	[ '%s', '%d' ] 
);

Notes

Changelog

Since 3.0.0 Introduced.

wpdb::replace() code WP 6.4.3

public function replace( $table, $data, $format = null ) {
	return $this->_insert_replace_helper( $table, $data, $format, 'REPLACE' );
}