(PECL mongo >=0.9.0)
MongoCollection::insert — Inserta un array en la colección
$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.
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.
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).
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.
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).
|
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($persona, true);
// ahora $person tiene un campo _id, así que si intentamos guardarlo
// de nuevo, obtendremos una excepción
try {
$colección->insert($persona, true);
} catch(MongoCursorException $e) {
echo "No se puede guardar dos veces la misma persona!\n";
}
?>