class Merge

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 ...

Other databases (most notably MySQL, PostgreSQL and SQLite) will emulate this statement by running a SELECT and then INSERT or UPDATE.

By default, the two table names are identical and they are passed into the the constructor. table_name_2 can be specified by the MergeQuery::conditionTable() method. It can be either a string or a subquery.

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

• class \Drupal\Core\Database\Query\Query implements PlaceholderInterface
  • class \Drupal\Core\Database\Query\Merge implements ConditionInterface uses QueryConditionTrait

File

core/lib/Drupal/Core/Database/Query/Merge.php, line 46

Namespace

Drupal\Core\Database\Query

Members

Name	Modifiers	Type	Description
Merge::$conditionTable	protected	property	The table or subquery to be used for the condition.
Merge::$defaultFields	protected	property	An array of fields which should be set to their database-defined defaults.
Merge::$expressionFields	protected	property	Array of fields to update to an expression in case of a duplicate record.
Merge::$insertFields	protected	property	An array of fields on which to insert.
Merge::$insertValues	protected	property	An array of values to be inserted.
Merge::$needsUpdate	protected	property	Flag indicating whether an UPDATE is necessary.
Merge::$table	protected	property	The table to be used for INSERT and UPDATE.
Merge::$updateFields	protected	property	An array of fields that will be updated.
Merge::conditionTable	protected	function	Sets the table or subquery to be used for the condition.
Merge::execute	public	function	Runs the query against the database. Overrides Query::execute
Merge::expression	public	function	Specifies fields to be updated as an expression.
Merge::fields	public	function	Sets common field-value pairs in the INSERT and UPDATE query parts.
Merge::insertFields	public	function	Adds a set of field->value pairs to be inserted.
Merge::key	public	function	Sets a single key field to be used as condition for this query.
Merge::keys	public	function	Sets the key fields to be used as conditions for this query.
Merge::STATUS_INSERT		constant	Returned by execute() if an INSERT query has been executed.
Merge::STATUS_UPDATE		constant	Returned by execute() if an UPDATE query has been executed.
Merge::updateFields	public	function	Adds a set of field->value pairs to be updated.
Merge::useDefaults	public	function	Specifies fields for which the database-defaults should be used.
Merge::__construct	public	function	Constructs a Merge object. Overrides Query::__construct
Merge::__toString	public	function	Implements PHP magic __toString method to convert the query to a string. Overrides Query::__toString
Query::$comments	protected	property	An array of comments that can be prepended to a query.
Query::$connection	protected	property	The connection object on which to run this query.
Query::$connectionKey	protected	property	The key of the connection object.
Query::$connectionTarget	protected	property	The target of the connection object.
Query::$nextPlaceholder	protected	property	The placeholder counter.
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::comment	public	function	Adds a comment to the query.
Query::getComments	public	function	Returns a reference to the comments array for the query.
Query::nextPlaceholder	public	function	Gets the next placeholder value for this query object. Overrides PlaceholderInterface::nextPlaceholder
Query::uniqueIdentifier	public	function	Returns a unique identifier for this object. Overrides PlaceholderInterface::uniqueIdentifier
Query::__clone	public	function	Implements the magic __clone function.
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.
QueryConditionTrait::$condition	protected	property	The condition object for this query.
QueryConditionTrait::andConditionGroup	public	function	Creates a new group of conditions ANDed together. Overrides ConditionInterface::andConditionGroup
QueryConditionTrait::arguments	public	function	Gets a complete list of all values to insert into the prepared statement. Overrides ConditionInterface::arguments
QueryConditionTrait::compile	public	function	Compiles the saved conditions for later retrieval. Overrides ConditionInterface::compile
QueryConditionTrait::compiled	public	function	Check whether a condition has been previously compiled. Overrides ConditionInterface::compiled
QueryConditionTrait::condition	public	function	Helper function: builds the most common conditional clauses. Overrides ConditionInterface::condition
QueryConditionTrait::conditionGroupFactory	public	function	Creates an object holding a group of conditions. Overrides ConditionInterface::conditionGroupFactory
QueryConditionTrait::conditions	public	function	Gets a complete list of all conditions in this conditional clause. Overrides ConditionInterface::conditions
QueryConditionTrait::exists	public	function	Sets a condition that the specified subquery returns values. Overrides ConditionInterface::exists
QueryConditionTrait::isNotNull	public	function	Sets a condition that the specified field be NOT NULL. Overrides ConditionInterface::isNotNull
QueryConditionTrait::isNull	public	function	Sets a condition that the specified field be NULL. Overrides ConditionInterface::isNull
QueryConditionTrait::notExists	public	function	Sets a condition that the specified subquery returns no values. Overrides ConditionInterface::notExists
QueryConditionTrait::orConditionGroup	public	function	Creates a new group of conditions ORed together. Overrides ConditionInterface::orConditionGroup
QueryConditionTrait::where	public	function	Adds an arbitrary WHERE clause to the query. Overrides ConditionInterface::where