wpdb::replace() – Method | Developer.WordPress.org

Replaces a row in the table or inserts it if it does not exist, based on a PRIMARY KEY or a UNIQUE index.

Description

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',
    )
);

Parameters

$tablestringrequired: Table name.
$dataarrayrequired: 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.
$formatstring[]|stringoptional: 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

Return

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

Source

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

View all references View on Trac View on GitHub

Uses	Description
wpdb::_insert_replace_helper()`wp-includes/class-wpdb.php`	Helper function for insert and replace.

Changelog

Version	Description
3.0.0	Introduced.

User Contributed Notes

Skip to note 3 content

guardiancrescent 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

The codex states
“This method returns a count to indicate the number of rows affected. This is the sum of the rows deleted and inserted. If the count is 1 for a single-row REPLACE, a row was inserted and no rows were deleted. If the count is greater than 1, one or more old rows were deleted before the new row was inserted.”

In MySQL databases however…
“It is possible that in the case of a duplicate-key error, a storage engine may perform the REPLACE as an update rather than a delete plus insert, but the semantics are the same.”

In this case 1 will be returned where 2 is expected.

Log in to add feedback
Skip to note 4 content

wplizer 3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

REPLACE internally performs a delete and then an insert. This can cause problems if you have a foreign key constraint pointing at that row.
Using INSERT … ON DUPLICATE KEY UPDATE avoids this problem and is therefore prefered.

Replace Into involves:
1.Try insert on the table
2. If 1 fails, delete row and insert new row

Insert on Duplicate Key Update involves:
1.Try insert on table
2.If 1 fails, update row

Insert on Duplicate Key update is faster usually…

Log in to add feedback

wpdb::replace( string $table, array $data, string[]|string $format = null ): int|false

In this article