Trabajar con bases de datos en Drupal 7 - Lección 8 - Consultas de inserción (INSERT INTO)

12/05/2025, by Ivan

Las consultas de inserción siempre deben usar el constructor de consultas. Algunas bases de datos requieren controladores especiales para campos LOB (Large OBject, como texto en MySQL) y BLOB (Binary Large OBject), por lo que se necesita un nivel de abstracción para que los controladores de BD individuales puedan implementar estos controladores.

Las consultas de inserción comienzan utilizando la función db_insert():

<?php
$query = db_insert('node', $options);
?>

La consulta de inserción crea un objeto de consulta que inserta uno o más registros en la tabla node. Observa que no es necesario usar llaves {}, el constructor de consultas gestiona los nombres de tabla automáticamente.

La inserción utiliza una API fluida. Esto significa que todos los métodos (incluido execute()) devuelven el propio objeto de consulta, permitiendo el encadenamiento de métodos.

Las consultas de inserción admiten varios patrones según el objetivo. Primero se definen los campos en los que se insertarán los datos, luego se describen los valores que se insertarán. Los patrones más comunes se describen a continuación.

Forma compacta

La forma preferida para la mayoría de los casos:

<?php
$nid = db_insert('node')
  ->fields(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
  ->execute();
?>

Esta consulta es equivalente a:

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

Este fragmento vincula claves y valores para insertar.

<?php
db_insert('node')
?>

Esta línea crea el objeto de consulta para la tabla node.

<?php
  ->fields(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
?>

El método fields() acepta un array asociativo. Las claves son los nombres de los campos y los valores son los datos que se insertarán.

<?php
  ->execute();
?>

A diferencia de otros métodos, execute() devuelve el valor del campo auto-increment, por ejemplo, nid en la tabla node. Si no hay un campo auto-increment, el valor devuelto será indefinido.

Forma simplificada

<?php
$nid = db_insert('node')
  ->fields(array('title', 'uid', 'created'))
  ->values(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
  ->execute();
?>

Equivalente a:

  ->fields(array('title', 'uid', 'created'))

Cuando fields() recibe un array indexado, solo se definen los campos (sin valores). Esto se usa para inserciones múltiples.

  ->values(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))

values() puede aceptar un array asociativo o indexado. Si es indexado, el orden debe coincidir con los campos definidos en fields().

Inserción múltiple (multi-insert)

Un objeto de inserción puede recibir múltiples conjuntos de valores mediante llamadas consecutivas a values(). En la mayoría de BD, esto se ejecutará dentro de una sola transacción.

<?php
$values = array(
  array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ),
  array(
    'title' => 'Example 2',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ),
  array(
    'title' => 'Example 3',
    'uid' => 2,
    'created' => REQUEST_TIME,
  ),
);
$query = db_insert('node')->fields(array('title', 'uid', 'created'));
foreach ($values as $record) {
  $query->values($record);
}
$query->execute();
?>

El código anterior inserta 3 registros en una sola operación.

Esto es equivalente a:

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

Ten en cuenta que execute() en este caso devuelve un valor indefinido, no debe confiarse en él.

Inserción desde SELECT (tabla resumen)

Si deseas llenar una tabla con resultados de otra, puedes hacerlo con INSERT INTO ... SELECT FROM.

Drupal 6

<?php
db_query('INSERT INTO {mytable} (nid, name) SELECT n.nid, u.name FROM {node} n LEFT JOIN {users} u on n.uid = u.uid WHERE n.type = "%s"', array ('page'));
?>

Drupal 7

<?php
$query = db_select('node', 'n');
$query->join('users', 'u', 'n.uid = u.uid');
$query->addField('n','nid');
$query->addField('u','name');
$query->condition('type', 'page');

db_insert('mytable')
  ->from($query)
  ->execute();
?>

Valores por defecto (default values)

En condiciones normales, si no se proporciona un valor y hay uno por defecto en la definición de la tabla, la BD lo usará automáticamente. Sin embargo, puedes forzar el uso de valores por defecto explícitamente con useDefaults():

<?php
$query->useDefaults(array('field1', 'field2'));
?>

Esto obliga al uso de valores por defecto en esos campos. No se debe definir el mismo campo en fields() o values() si ya está en useDefaults(), o causará un error.

Extra Block Types (EBT) - Nueva experiencia con Layout Builder❗

❗Extra Paragraph Types (EPT) - Nueva experiencia con Paragraphs