MongoCollection
PHP Manual

MongoCollection::insert

(PECL mongo >=0.9.0)

MongoCollection::insertInserta un array en la colección

Descripción

public bool|array MongoCollection::insert ( array $a [, array $options = array() ] )

Todas las cadenas de texto que se envíen a la base de datos deben estar en UTF-8. Si un string no estuviera en UTF-8, se lanzaría una excepción MongoException. Para insertar (o para consultar) un texto que no sea UTF-8, utilice MongoBinData.

Parámetros

a

Un array.

options

Opciones de inserción.

  • "safe"

    Puede ser un booleano o un entero, por omisión FALSE. Si FALSE, el programa continua su ejecución sin esperar respuesta por parte de la base de datos. Si TRUE, el programa esperará la respuesta de la base de datos, y en caso de que la inserción no tenga éxito, emitirá una excepción de tipo MongoCursorException.

    Si se estuvieran utilizando réplicas, y el maestro cambiara, al usar "safe" se provocaría que el driver desconectaría del maestro, emitiría una excepción, y en la siguiente operación se tratría de encontrar un nuevo maestro (su aplicación debe decidir si reintentará realizar de nuevo la operación sobre un nuevo maestro).

    Si no utiliza "safe" con conjuntos de réplicas y el maestro cambia, no habrá forma de que el driver conozca el cambio. En este caso, continuará la ejecución y la escritura, silenciosamente, fallará.

    Si safe fuera un entero, replicará la inserción a ese número de máquinas antes de notificar un éxito (o lanzaría una excepción si al replicar se excediera el tiempo de espera; consulte wtimeout). Sobreescribe la variable w asignada a la colección.

  • "fsync"

    Booleano, por omisión FALSE. Obliga a que la inserción se sincronice en disco antes de notificar éxito. Si TRUE, se realiza de manera implícita una inserción segura (safe) y sobrescribirá el ajuste safe a FALSE.

  • "timeout"

    Entero, por omisión MongoCursor::$timeout. Si "safe" está habilitado, este valor indica por cuánto tiempo (en milisegundos) esperará el cliente la respuesta de la base de datos. Si la base de datos no respondiera en ese periodo de tiempo, se lanzaría una excepción de tipo MongoCursorTimeoutException.

Valores devueltos

Si safe está habilitado, devuelve un array con el estado de la inserción. En cualquier otro caso, devuelve un booleano indicando si el array no estaba vacío (un array vacío no se insertará).

Si se devuelve un array, las siguientes claves pueden estar presentes:

ok

Debería ser casi siempre 1 (a menos que last_error falle por sí mismo).

err

Si este campo es diferente de null, un error ocurrido en la operación anterior. Si este campo está establecido, será una cadena describiendo el error que ocurrió.

code

Si ocurrión un error de base de datos, el código de error relevante será devuelto al cliente.

errmsg

Este campo está establecido si algo va mal con un comando de base de datos. Está asociado con ok igual a 0. Por ejemplo, si se establece w y se agota el tiempo, errmsg será establecido a "timed out waiting for slaves" y ok será 0. Si este campo es establecido, será una cadena describiendo el error ocurrido.

n

Si la última operación fue de inserción, una actualización o una eliminación, será devuelto el número de objetos afectados.

wtimeout

Si la opción anterior agota el tiempo, espera una réplica.

waited

Cuánto esperará la operación antes de agotarse el tiempo.

wtime

Si w fue establecido y la operación tiene éxito, cuánto toma la réplica a los servidores w.

upserted

Si ocurre un upsert, este campo contendrá el nuevo campo _id del registro. Para upserts, estará presente este campo o updatedExisting (a menos que ocurra un error).

updatedExisting

Si un upsert actualiza un elemento existente, este campo será "true". Para upserts, estará presente este campo o upserted (a menos que ocurra un error).

Errores/Excepciones

Lanza MongoCursorException si la opción "safe" estuviera habilitada y fallara la inserción. (Versión 1.0.1+)

Lanza MongoCursorTimeoutException si la opción "safe" estuviera habilitada y la operación llevara más de MongoCursor::$timeout milisegundos para completarse. No detiene el proceso en el servidor; es sólo un tiempo de espera en el lado del cliente.

Historial de cambios

Versión Descripción
1.0.5 Cambiado el segundo parámetro a un array de opciones. Antes de 1.0.5, el segundo parámetro era un booleano indicando la opción "safe".
1.0.9 Añadido soporte para pasar enteros a la opción "safe" (antes sólo aceptaba booleanos) y añadida la opción "fsync".
1.0.9 Cambiado el tipo devuelto por un array que contiene información del error si se utiliza la opción "safe", de otro modo es un booleano como antes.
1.0.11 Si "safe" está habilitado y hay un error que no sea en el maestro, se desconecta.
1.2.0 Añadida la opción "timeout".
1.3.0 El parámetro options ya no solo acepta un booleano que indique inserción segura. En su lugar, ahora se debe hacer con array('safe' => true).

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::insert() con _id

Al insertar un objeto se le añadirá un campo _id, a no ser que se pase por referencia.

<?php

$m 
= new Mongo();
$db $m->selectDB('test');
$colección = new MongoCollection($db'phpmanual');

$a = array('x' => 12);
$colección->insert($a);
var_dump($a);

$b = array('x' => 12);
$ref = &$b;
$colección->insert($ref);
var_dump($ref);

?>

El resultado del ejemplo sería algo similar a:

array(2) {
  ["x"]=>
  int(12)
  ["_id"]=>
  object(MongoId)#4 (0) {
  }
}
array(12) {
  ["x"]=>
  int(1)
}

Ejemplo #2 Ejemplo de MongoCollection::insert() safe

Este ejemplo muestra cómo al insertar dos elementos con el mismo _id, se provoca que se lance una excepción MongoCursorException, ya que safe está habilitado.

<?php

$persona 
= array("nombre" => "Joe""edad" => 20);
$colección->insert($personatrue);

// ahora $person tiene un campo _id, así que si intentamos guardarlo
// de nuevo, obtendremos una excepción
try {
    
$colección->insert($personatrue);
} catch(
MongoCursorException $e) {
    echo 
"No se puede guardar dos veces la misma persona!\n";
}

?>

Ver también


MongoCollection
PHP Manual