General class for an abstracted MERGE query operation.

An ANSI SQL:2003 compatible database would run the following query:

MERGE INTO table_name_1 USING table_name_2 ON (condition)
  WHEN MATCHED THEN
  UPDATE SET column1 = value1 [, column2 = value2 ...]
  WHEN NOT MATCHED THEN
  INSERT (column1 [, column2 ...]) VALUES (value1 [, value2 ...

MySQL does not directly implement MERGE queries and will emulate this statement by running an UPDATE, and if that does not match any rows, then an INSERT.

The condition is built exactly like SelectQuery or UpdateQuery conditions, the UPDATE query part is built similarly like an UpdateQuery and finally the INSERT query part is built similarly like an InsertQuery. However, both UpdateQuery and InsertQuery has a fields method so MergeQuery::updateFields() and MergeQuery::insertFields() needs to be called instead. MergeQuery::fields() can also be called which calls both of these methods as the common case is to use the same column-value pairs for both INSERT and UPDATE. However, this is not mandatory. Another convenient wrapper is MergeQuery::key() which adds the same column-value pairs to the condition and the INSERT query part.

Several methods (key(), fields(), insertFields()) can be called to set a key-value pair for the INSERT query part. Subsequent calls for the same fields override the earlier ones. The same is true for UPDATE and key(), fields() and updateFields().

Hierarchy

Expanded class hierarchy of MergeQuery

Related topics

File

core/includes/database/query.inc, line 1268
Non-specific Database query code. Used by all engines.

Members

Contains filters are case sensitive
Name Modifierssort descending Type Description
MergeQuery::STATUS_INSERT constant Returned by execute() if an INSERT query has been executed.
MergeQuery::STATUS_UPDATE constant Returned by execute() if an UPDATE query has been executed.
MergeQuery::$table protected property The table to be used for INSERT and UPDATE.
MergeQuery::$insertFields protected property An array of fields on which to insert.
MergeQuery::$defaultFields protected property An array of fields which should be set to their database-defined defaults.
MergeQuery::$insertValues protected property An array of values to be inserted.
MergeQuery::$updateFields protected property An array of fields that will be updated.
MergeQuery::$expressionFields protected property Array of fields to update to an expression in case of a duplicate record.
MergeQuery::$needsUpdate protected property Flag indicating whether an UPDATE is necessary.
MergeQuery::$result protected property The result of the merge query.
MergeQuery::$condition protected property The condition object for this query.
Query::$connection protected property The connection object on which to run this query.
Query::$connectionTarget protected property The target of the connection object.
Query::$connectionKey protected property The key of the connection object.
Query::$queryOptions protected property The query options to pass on to the connection object.
Query::$uniqueIdentifier protected property A unique identifier for this query object.
Query::$nextPlaceholder protected property The placeholder counter.
Query::$comments protected property An array of comments that can be prepended to a query.
MergeQuery::__construct public function Constructs a MergeQuery object. Overrides Query::__construct
MergeQuery::updateFields public function Adds a set of field->value pairs to be updated.
MergeQuery::expression public function Specifies fields to be updated as an expression.
MergeQuery::insertFields public function Adds a set of field->value pairs to be inserted.
MergeQuery::useDefaults public function Specifies fields for which the database-defaults should be used.
MergeQuery::fields public function Sets common field-value pairs in the INSERT and UPDATE query parts.
MergeQuery::key public function Sets the key field(s) to be used as conditions for this query.
MergeQuery::condition public function Implements QueryConditionInterface::condition(). Overrides QueryConditionInterface::condition
MergeQuery::isNull public function Implements QueryConditionInterface::isNull(). Overrides QueryConditionInterface::isNull
MergeQuery::isNotNull public function Implements QueryConditionInterface::isNotNull(). Overrides QueryConditionInterface::isNotNull
MergeQuery::exists public function Implements QueryConditionInterface::exists(). Overrides QueryConditionInterface::exists
MergeQuery::notExists public function Implements QueryConditionInterface::notExists(). Overrides QueryConditionInterface::notExists
MergeQuery::conditions public function Implements QueryConditionInterface::conditions(). Overrides QueryConditionInterface::conditions
MergeQuery::arguments public function Implements QueryConditionInterface::arguments(). Overrides QueryConditionInterface::arguments
MergeQuery::where public function Implements QueryConditionInterface::where(). Overrides QueryConditionInterface::where
MergeQuery::compile public function Implements QueryConditionInterface::compile(). Overrides QueryConditionInterface::compile
MergeQuery::compiled public function Implements QueryConditionInterface::compiled(). Overrides QueryConditionInterface::compiled
MergeQuery::__toString public function Implements PHP magic __toString method to convert the query to a string. Overrides Query::__toString
MergeQuery::execute public function Runs the query against the database. Overrides Query::execute
MergeQuery::getResult public function Return the result of the merge query.
Query::__sleep public function Implements the magic __sleep function to disconnect from the database.
Query::__wakeup public function Implements the magic __wakeup function to reconnect to the database.
Query::__clone public function Implements the magic __clone function.
Query::uniqueIdentifier public function Returns a unique identifier for this object. Overrides QueryPlaceholderInterface::uniqueIdentifier
Query::nextPlaceholder public function Gets the next placeholder value for this query object. Overrides QueryPlaceholderInterface::nextPlaceholder
Query::comment public function Adds a comment to the query.
Query::getComments public function Returns a reference to the comments array for the query.