MongoCollection::batchInsert

(PECL mongo >=0.9.0)

MongoCollection::batchInsert — Inserta múltiples documentos en esta colección

Descripción

public MongoCollection::batchInsert ( array $a [, array $options = array() ] ) : mixed

Parámetros

a

Un array de arrays u objetos. Si se utilizan objetos, estos no pueden tener propiedades protegidas o privadas.

Nota:
Si los documentos a insertar no poseen una clave o propiedad _id, se creará una nueva instancia de MongoId y se le asignará. Véase MongoCollection::insert() para información adicional sobre este comportamiento.

options

Un array de opciones para las operaciones de inserción de lotes. Las opciones disponibles actualmente son:

"continueOnError"

Booleano, por omisión es FALSE. Si se establece, la base de datos no parará de procesar un volumen de inserciones si una falla (p.ej. debido a IDs duplicados). Esto hace que el volumen de inserciones se comporte de manera similar a una insercioón única, excepto que con la llamada a MongoDB::lastError() se obtendrá un error establecido si cualquier inserción falla, no sólo la primera. Si ocurren varios errores, sólo se informará de más reciente, mediante MongoDB::lastError().

Nota:
Observe que continueOnError afecta únicamentea los errores del lado del servidor. Si se intenta insertar un documento que tiene errores (por ejemplo que contiene una clave con un nombre vacío), el documento no será transferido a la base de datos, ya que el controlador detecta este error y no continúa. continueOnError no tiene efecto sobre errores detectados por el controlador en los documentos.
"fsync"
Booleano, cuyo valor predeterminado es FALSE. Si el registro en el diario está habilitado, funciona exactamente igual que "j". Si no está habilidato, la operación de escriturá bloqueará hasta que se sincronice con los ficheros de la base de datos del disco. Si es TRUE, implica una inserción reconocida y sobrescribirá el ajuste "w" a 0.
Nota: Si está habilitada, se recomienda a los usuarios usar la opción "j" en lugar de "fsync". No use "fsync" y "j" simultáneamente, ya que resultará en un error.
"j"
Booleano, cuyo valor predeterminado es FALSE. Fuerza a la operación de escritura a bloquear hasta que sea sincronizada con el diario del disco. Si es TRUE, implica una escritura reconocida y sobrescribirá el ajuste "w" a 0.
Nota: Si se usa esta opción y el registro en el diario está deshabilitado, MongoDB 2.6+ emitirá un error y la escritura fallará; las versiones más antiguas del servidor simplemente ignoran esta opción.
"socketTimeoutMS"
Esta opción especifica el tiempo límite, en milisegundos, para las comunicaciones con socket. Si el servidor no responde en el periodo especificado, se lanzará una MongoCursorTimeoutException y no habrá forma de determinar si el servidor manejó realmente la escritura o no. Se podría especificar un valor de -1 para bloquear indefinidamente. El valor predeterminado para MongoClient es 30000 (30 segundos).
"w"
Véase WriteConcerns. El valor predeterminado de MongoClient es 1.
"wTimeoutMS"
Esta opción especifica el tiempo límite, en milisegundos, para el reconocimiento de un asunto de escritura. Solamente es aplicable cuando "w" sea mayor que 1, ya que el tiempo de espera está relacionado con la replecación. Si el asunto de escritura no se satisface dentro del tiempo límite, se lanzará una MongoCursorException. Se puede especificar un valor de 0 para bloquear indefinidamente. El valor predeterminado es 10000 (diez segundos).

Las siguientes opciones están obsoletas y no deberían usarse más:

"safe"
Obsoleto. Use la opción w de los asuntos de escritura.
"timeout"
Alias obsoleto de "socketTimeoutMS".
"wtimeout"
Alias obsoleto de "wTimeoutMS".

Valores devueltos

Si el parámetro w está establecido para aceptar la escritura, devuelve un array asociativo con el estado de las inserciones ("ok") y cualquier error que pudiera ocurrir ("err"). De lo contrario, devuelve TRUE si la inserción por lotes fue enviada con éxito, si no, FALSE.

Errores/Excepciones

Lanza una MongoException si cualquier documento insertado está vacío o si contiene claves de longitud cero. Intentar insertar un objeto con propiedades protegidas o privadas causará un error de clave de longitud cero.

Lanza una MongoCursorException si la opción "w" está establecida y la escritura falla.

Lanza una MongoCursorTimeoutException si la opción "w" está establecida a un valor mayor que uno y la operación toma más de MongoCursor::$timeout milisegundos en completarse. Esto no pondrá fin a la operación en el servidor, es un tiempo límite del lado del cliente. La operación en MongoCollection::$wtimeout es milisegundos.

Historial de cambios

Versión	Descripción
1.5.0	Se añadió la opción "wTimeoutMS", la cual remplaza a "wtimeout". Emite un error de nivel `E_DEPRECATED` cuando se usa "wtimeout". Se añadió la opción "socketTimeoutMS", la cual remplza a "timeout". Emite un error de nivel `E_DEPRECATED` cuando se usa "timeout". Emite un error de nivel `E_DEPRECATED` al usar "safe".
1.3.4	Se añadió la opción "wtimeout".
1.3.0	Se añadió la opción "w".
1.2.7	Se añadió la opción "continueOnError".
1.0.9	Se añadió la capacidad de pasar números enteros a la opción "safe", que anteriormente sólo aceptaba booleanos. Se añadió la opción "fsync".
1.0.5	Se añadió el parámetro `options`.

Ejemplos

Ejemplo #1 Ejemplo de MongoCollection::batchInsert()

Las inserciones por lotes son una forma rápida de añadir muchos elementos a la base de datos de una sola vez


<?php

$usuarios = array();
for ($i = 0; $i<100; $i++) {
  $usuarios[] = array('nombreUsuario' => 'usuario'.$i, 'i' => $i);
}

$mongo = new MongoClient();
$collection = $mongo->my_db->usuarios;
$collection->drop();

$collection->batchInsert($usuarios);

foreach ($usuarios as $usuario) {
  echo $usuario['_id']."\n"; // completado con instanceof MongoId
}

$usuarios = $collection->find()->sort(array('i' => 1));
foreach ($usuarios as $usuario) {
    var_dump($usuario['nombreUsuario']);
}

?>

El resultado del ejemplo sería algo similar a:

4bf43ac68ead0e1971000000
4bf43ac68ead0e1971010000
4bf43ac68ead0e1971020000
...
string(5) "usuario1"
string(5) "usuario2"
string(5) "usuario3"
...

Ejemplo #2 Ejemplo de MongoCollection::batchInsert() ignorando errores


<?php

$con = new Mongo;
$db = $con->demo;

$doc1 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010001'),
        'id' => 1,
        'desc' => "ONE",
);
$doc2 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'),
        'id' => 2,
        'desc' => "TWO",
);
$doc3 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010002'), // el mismo _id que el anteior
        'id' => 3,
        'desc' => "THREE",
);
$doc4 = array(
        '_id' => new MongoId('4cb4ab6d7addf98506010004'),
        'id' => 4,
        'desc' => "FOUR",
);

$c = $db->selectCollection('c');
$c->batchInsert(
    array($doc1, $doc2, $doc3, $doc4),
    array('continueOnError' => true)
);

$docs = $c->find();
foreach ($docs as $doc) {
    var_dump($doc['desc']);
}
?>

El resultado del ejemplo sería algo similar a:

string(3) "ONE"
string(3) "TWO"
string(4) "FOUR"

Ver también

MongoCollection::insert() - Inserta un documento en la colección
MongoCollection::update() - Actualizar registros basándose en los criterios proporcionados
MongoCollection::find() - Consulta esta colección, devolviendo un objeto MongoCursor para el conjunto de resultados
MongoCollection::remove() - Eliminar registros de esta colección
Documentación de MongoDB sobre » insert.

add a note

User Contributed Notes 1 note

down

charles dot a dot dacosta at gmail dot com ¶

8 years ago


Fatal error: Uncaught exception 'MongoException' with message 'current batch size is too large: 48000077, max: 48000000'

It would have been better to have seen a not in the manual.

add a note