Consultas de fusión merge

Las consultas de fusión representan un tipo especial de consulta híbrida. Aunque la sintaxis para ellas está definida en la especificación SQL 2003, prácticamente ninguna base de datos soporta la sintaxis estándar. Sin embargo, la mayoría proporciona una implementación alternativa usando una sintaxis específica para la base de datos. El constructor de consultas de fusión en Drupal abstrae el concepto de consulta de fusión en un objeto estructurado que puede compilarse con la sintaxis correspondiente para cada base de datos. A veces se les llama consultas "UPSERT", una combinación de UPDATE e INSERT.

En un sentido general, una consulta de fusión es una combinación de una consulta de inserción y una de actualización. Si se cumple una condición determinada, por ejemplo, si una fila con una clave primaria dada ya existe, se ejecuta la consulta de actualización. Si no, se ejecuta la consulta de inserción. En el caso más común, esto es equivalente a:

if ($connection->query("SELECT COUNT(*) FROM {example} WHERE id = :id", [':id' => $id])->fetchField()) {
  // Ejecutar una actualización usando WHERE id = $id
}
else {
  // Ejecutar una inserción, insertando $id para id 
}

La implementación real varía mucho de una base de datos a otra. Tenga en cuenta que aunque las consultas de fusión son conceptualmente una operación atómica, pueden o no ser realmente atómicas dependiendo de la implementación específica de la base de datos. Por ejemplo, la implementación de MySQL es una consulta atómica separada, pero el caso degenerado (arriba) no lo es.

Las idiomáticas más comunes para las consultas Merge se enumeran a continuación.

Simplemente configúralo

$connection->merge('example')
  ->key('name', $name)
  ->fields([
      'field1' => $value1,
      'field2' => $value2,
  ])
  ->execute();

En el ejemplo anterior indicamos a la consulta que trabaje con la tabla "example". Luego indicamos un campo clave 'name' con el valor $name. Después indicamos un arreglo de valores a establecer.

Si ya existe una fila donde el campo "name" tiene el valor $name, entonces los campos field1 y field2 se establecerán a los valores correspondientes en esa fila existente. Si no existe tal fila, se creará una donde name tenga el valor $name, field1 tenga el valor $value1 y field2 el valor $value2. Así, al final de la consulta el resultado final es el mismo sin importar si la fila existía o no.

Asignación condicional

En algunos casos puede ser necesario establecer los valores de manera diferente dependiendo de si ya existe un registro, tal como se define por los campos de key(). Hay dos formas de hacerlo.

$connection->merge('example')
  ->insertFields([
      'field1' => $value1,
      'field2' => $value2,
  ])
  ->updateFields([
    'field1' => $alternate1,
  ])
  ->key('name', $name)
  ->execute();

El ejemplo anterior se comportará igual que el primero, excepto que si el registro ya existe y lo estamos actualizando, para field1 se establecerá el valor $alternate1 en lugar de $value1, y field2 no se verá afectado. El método updateFields() acepta ya sea un arreglo asociativo de valores, o dos arreglos numéricos paralelos, uno de campos y otro de valores, que deben estar en el mismo orden.

$connection->merge('example')
  ->key('name', $name)
  ->fields([
      'field1' => $value1,
      'field2' => $value2,
  ])
  ->expression('field1', 'field1 + :inc', [':inc' => 1])
  ->execute();

En este ejemplo, si el registro ya existe, para field1 se establecerá su valor actual más 1. Esto lo hace muy útil para "consultas de conteo", cuando quieres incrementar un contador en la base de datos cada vez que ocurre un evento específico. field2 seguirá teniendo el mismo valor sin importar si el registro existe o no.

Tenga en cuenta que expression() puede llamarse varias veces, una por cada campo que deba establecerse a una expresión si el registro ya existe. El primer parámetro es el campo, el segundo un fragmento SQL que indica la expresión que debe asignarse al campo, y el tercer parámetro opcional es un arreglo de valores de marcadores para insertar en la expresión.

No es obligatorio que el campo usado en expression() ya esté presente en fields().

Dado el API anterior, es posible definir consultas que carezcan de sentido lógico, por ejemplo, si a un campo se le asigna que sea ignorado y también establecido con una expresión cuando el registro ya existe. Para minimizar posibles errores, se aplican las siguientes reglas:

• Si un campo tiene asignado expression(), tiene prioridad sobre updateFields().
• Si se especifican valores en updateFields(), solo esos campos serán modificados si el registro ya existe. Los campos no especificados en updateFields() no serán tocados.

Tenga en cuenta que todavía es posible definir consultas sin sentido. El desarrollador debe asegurarse de no especificar una consulta sin sentido, ya que el comportamiento en tal caso no está definido.