Consultas de inserción insert

Las consultas de inserción siempre deben usar un objeto constructor de consultas. En algunas bases de datos se requiere un manejo especial para campos LOB (Large OBject, por ejemplo TEXT en MySQL) y BLOB (Binary Large OBject), por lo que se necesita un nivel de abstracción para que los controladores de bases de datos individuales puedan implementar cualquier manejo especial que requieran.

Las consultas de inserción se inician usando el método insert() de la siguiente manera:

$query = $connection->insert('mytable', $options);

Esto crea un objeto de consulta de inserción que insertará uno o más registros en la tabla mytable. Tenga en cuenta que no se requieren llaves para el nombre de la tabla, ya que el constructor de consultas lo manejará automáticamente.

El objeto de consulta de inserción usa una API fluida. Es decir, todos los métodos (excepto execute()) retornan el mismo objeto de consulta, permitiendo encadenar llamadas a métodos. En muchos casos, esto significa que el objeto de consulta ni siquiera necesita guardarse en una variable.

El objeto de consulta de inserción soporta varios patrones de uso diferentes para satisfacer diversas necesidades. En general, el flujo de trabajo consiste en indicar los campos en los que se insertará la consulta, definir los valores que la consulta insertará en esos campos y ejecutar la consulta. Los modelos de uso más comunes y recomendados se enumeran a continuación.

Forma compacta

La forma preferida para la mayoría de las consultas de inserción es la forma compacta:

$result = $connection->insert('mytable')
  ->fields([
    'title' => 'Example',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ])
  ->execute();

Esto equivaldrá a la siguiente consulta:

INSERT INTO {mytable} (title, uid, created) VALUES ('Example', 1, 1221717405);

El fragmento anterior une las partes clave del proceso de inserción.

$connection->insert('mytable')

Esta línea crea un nuevo objeto de consulta de inserción para la tabla mytable.

  ->fields([
    'title' => 'Example',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ])

El método fields() acepta varias formas de parámetros, pero el uso más común es un arreglo asociativo. Las claves del arreglo son las columnas de la tabla donde se insertarán los datos, y los valores son los valores correspondientes para insertar. Esto producirá una única consulta de inserción para la tabla especificada.

 ->execute();

El método execute() indica que se ejecute la consulta. Si no se llama a este método, la consulta no se ejecuta.

A diferencia de otros métodos del objeto de consulta de inserción que retornan el propio objeto, execute() retorna el valor del campo autoincremental (tipo secuencial en hook_schema()) que fue llenado por la consulta de inserción, si existe. Por eso el valor retornado se asigna a $result en el ejemplo anterior. Si no existe un campo autoincremental, el valor retornado por execute() no está definido y no se debe confiar en él.

En el caso típico, este es el formato preferido para consultas de inserción.

Forma degenerada

$result = $connection->insert('mytable')
  ->fields(['title', 'uid', 'created'])
  ->values([
    'title' => 'Example',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ])
  ->execute();

Esta es una forma un poco más detallada del ejemplo anterior y tendrá exactamente el mismo resultado.

  ->fields(['title', 'uid', 'created'])

Cuando fields() se llama con un arreglo indexado en lugar de uno asociativo, solo se establecen los campos (columnas de la base de datos) que serán usados en la consulta, sin asignarles ningún valor. Esto es útil para ejecutar consultas de múltiples páginas más adelante.

  ->values([
    'title' => 'Example',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ])

Esta llamada establece un arreglo asociativo de nombres de campos con los valores que se deben insertar en esos campos. El método values() también puede aceptar un arreglo indexado. Si se usa un arreglo indexado, el orden de los valores debe coincidir con el orden de los campos indicados en fields(). Si se usa un arreglo asociativo, el orden puede ser cualquiera. Por lo general, el arreglo asociativo es preferible por legibilidad.

Esta forma de consulta se usa raramente, ya que la forma compacta es preferible. En la mayoría de los casos, la única razón para separar fields() y values() es para ejecutar consultas de múltiples páginas.

Forma con múltiples inserciones

El objeto de consulta de inserción también puede aceptar múltiples conjuntos de valores. Es decir, values() puede llamarse varias veces para poner en cola múltiples sentencias de inserción. Cómo se maneje esto dependerá de las capacidades de la base de datos en uso. En la mayoría de bases de datos, múltiples sentencias de inserción se ejecutan juntas dentro de una transacción para mayor integridad de datos y velocidad. En MySQL se usará la sintaxis de inserción múltiple propia de MySQL.

$values = [
  [
    'title' => 'Example',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ],
  [
    'title' => 'Example 2',
    'uid' => 1,
    'created' => \Drupal::time()->getRequestTime(),
  ],
  [
    'title' => 'Example 3',
    'uid' => 2,
    'created' => \Drupal::time()->getRequestTime(),
  ],
];
$query = $connection->insert('mytable')->fields(['title', 'uid', 'created']);
foreach ($values as $record) {
  $query->values($record);
}
$query->execute();

En el ejemplo anterior, las tres sentencias de inserción se ejecutarán juntas como una sola operación, usando el método más eficiente para el controlador de base de datos específico en uso. Note que aquí guardamos el objeto de consulta en una variable para poder iterar sobre $values y llamar repetidamente al método values().

En el caso degenerado, el ejemplo anterior es equivalente a las siguientes tres consultas:

INSERT INTO {mytable} (title, uid, created) VALUES ('Example', 1, 1221717405);
INSERT INTO {mytable} (title, uid, created) VALUES ('Example2', 1, 1221717405);
INSERT INTO {mytable} (title, uid, created) VALUES ('Example3', 2, 1221717405);

Note que en la consulta con múltiples inserciones, el valor retornado por execute() no está definido y no debe ser confiable, ya que puede variar según el controlador de base de datos.

Inserción a partir de resultados de consulta select

Si desea llenar una tabla con resultados de otras tablas, debe elegir entre hacer un SELECT desde las tablas origen, recorrer los datos en PHP e insertarlos en la tabla nueva, o ejecutar una consulta INSERT INTO ... SELECT FROM donde cada registro devuelto por la consulta SELECT se pasa a la consulta INSERT.

En este ejemplo queremos construir la tabla mytable con nid y nombre de usuario para todos los nodos en el sistema que son de tipo page.

<?php
// Construir la consulta SELECT.
$query = $connection->select('node', 'n');
// Unir con la tabla users.
$query->join('users', 'u', 'n.uid = u.uid');
// Añadir los campos que queremos.
$query->addField('n','nid');
$query->addField('u','name');
// Añadir condición para solo obtener nodos tipo page.
$query->condition('type', 'page');

// Ejecutar la inserción.
$connection->insert('mytable')
  ->from($query)
  ->execute();
?>

Valores por defecto

Normalmente, si no especifica un valor para un campo dado y la tabla tiene un valor por defecto definido en el esquema, la base de datos insertará automáticamente ese valor por defecto por usted. Sin embargo, en algunos casos puede ser necesario indicar explícitamente a la base de datos que use el valor por defecto. Esto incluye cuando desea usar todos los valores por defecto para toda la fila. Para indicar explícitamente a la base de datos que use el valor por defecto para un campo dado, existe el método useDefaults().

$query->useDefaults(['field1', 'field2']);

Esta línea indica a la consulta que use los valores por defecto para los campos field1 y field2. Tenga en cuenta que especificar el mismo campo en useDefaults() y en fields() o values() es un error y se lanzará una excepción.

$connection->insert() o $connection->query()

Esta es una pregunta frecuente. (Ver los comentarios en esta página.) ¿Cuál es la diferencia entre insert() y query()?

Con insert(), cada columna se especifica como una entrada separada en el arreglo de campos, y el código puede limpiar el valor de cada columna. query() acepta una cadena SQL sin posibilidad de validar columnas individualmente. Si usa query() con marcadores de posición, el código puede validar los valores de las columnas, pero los marcadores de posición son solo una opción, y no hay forma de garantizar que su SQL no contenga valores que no hayan pasado por los marcadores.

insert() pasa la consulta a través de un conjunto de hooks para permitir que otros módulos validen y modifiquen sus consultas. Esta es la forma correcta de interactuar con otros módulos. query() es un poco más rápido porque no pasa la consulta por hooks. Puede ahorrar tiempo de procesamiento, pero su código no permitirá que otros módulos ayuden a su código.

insert() generalmente funciona mejor con otras bases de datos y futuras versiones de Drupal.