/ /

Operaciones de escritura masiva

Overview

En esta guía, puedes aprender a realizar múltiples operaciones de escritura en una sola llamada a la base de datos utilizando operaciones de escritura en bloque.

Considera un escenario en el que quieres insertar un documento, actualizar varios otros documentos y luego borrar un documento. Si utiliza métodos individuales, cada operación requiere su propia llamada a la base de datos.

Al utilizar una operación de guardar masiva, puedes realizar múltiples operaciones de guardar en menos llamadas a la base de datos. Puedes realizar operaciones de guardar en bloque en los siguientes niveles:

Cliente: si tu aplicación se conecta a MongoDB Server versión 8.0 o posterior, puedes usar el método MongoDB\Client::bulkWrite() para realizar operaciones de escritura masiva en varias colecciones y bases de datos dentro del mismo clúster. Este método realiza todas las operaciones de guardar en una sola llamada a la base de datos. Para obtener más información sobre esta funcionalidad, consulta la Mongo.bulkWrite() referencia en el manual del servidor de MongoDB.
Colección: Se puede utilizar el método MongoDB\Collection::bulkWrite() para realizar operaciones de guardado masivo en una única colección. Este método hace una llamada a la base de datos para cada tipo de operación de escritura. Por ejemplo, el método puede realizar múltiples operaciones de actualización en una sola llamada, pero realiza dos llamadas separadas a la base de datos para una operación de inserción y una operación de reemplazo.

Datos de muestra

Los ejemplos de esta guía utilizan las colecciones sample_restaurants.restaurants y sample_mflix.movies del Atlas datasets de muestra. Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta Comienza con Atlas.

Guardado Masivo del Cliente

Cuando se utiliza la librería de PHP v2.1 y se conecta a una implementación que ejecuta MongoDB Server 8.0 o posterior, se puede utilizar el método MongoDB\Client::bulkWrite() para guardar en varias bases de datos y colecciones en el mismo clúster. Este método realiza todas las operaciones de guardar en una sola llamar.

Primero, utiliza el constructor MongoDB\ClientBulkWrite para crear una instancia de BulkWriteCommand que especifique las operaciones de escritura a realizar. El siguiente código demuestra cómo crear una instancia de ClientBulkWrite a partir de una instancia de MongoDB\Collection usando el método createWithCollection():

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);

Luego, llama a uno o más de los siguientes métodos de escritura en la instancia ClientBulkWrite para construir la operación de escritura masiva:

deleteOne()
deleteMany()
insertOne()
replaceOne()
updateOne()
updateMany()

Para seleccionar un namespace diferente para las operaciones de guardar posteriores, llama al método withCollection() en la instancia ClientBulkWrite, como se muestra en el siguiente código:

$movieCollection = $client->sample_mflix->movies;
$bulkWrite = $bulkWrite->withCollection($movieCollection);

Las siguientes secciones muestran cómo crear y usar la clase ClientBulkWrite para especificar las operaciones de escritura en una escritura masiva. La sección Realizar la Operación Masiva demuestra cómo pasar el objeto ClientBulkWrite al método bulkWrite() para realizar la operación masiva.

Operaciones de inserción

Para especificar una operación de inserción, llama al método insertOne() en tu instancia ClientBulkWrite.

El siguiente ejemplo especifica la inserción de documentos en las colecciones sample_restaurants.restaurants y sample_mflix.movies:

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
$bulkWrite = $bulkWrite->withCollection($movieCollection);
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);

Operaciones de actualizar

Para especificar una operación de actualización en el primer documento coincidente, llama al método updateOne() en tu instancia ClientBulkWrite.

El siguiente ejemplo especifica una actualización $set al primer documento en la colección sample_restaurants.restaurants que tiene un name valor de 'Dandelion Bakery':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);

Para actualizar varios documentos, llama al método updateMany(). La operación especificada actualiza todos los documentos que coinciden con el filtro de query.

El siguiente ejemplo especifica una actualización $set a todos los documentos coincidentes en la colección sample_restaurants.restaurants que tienen un valor name de 'Starbucks':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->updateMany(
    ['name' => 'Starbucks'],
    ['$set' => ['cuisine' => 'Coffee (Chain)']],
);

Reemplazar operaciones

Para especificar una operación de reemplazo en el primer documento que coincida, llama al método replaceOne() en tu instancia ClientBulkWrite.

El siguiente ejemplo especifica una operación de reemplazo en el primer documento de la colección sample_restaurants.restaurants que tiene un valor de name de 'Dandelion Bakery':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->replaceOne(
    ['name' => 'Dandelion Bakery'],
    ['name' => 'Flower Patisserie', 'cuisine' => 'Bakery & Cafe'],
);

Operaciones de borrar

Para especificar una operación de borrado en el primer documento que coincida, llama al método deleteOne() en su instancia de ClientBulkWrite.

El siguiente ejemplo especifica la eliminación del primer documento en la colección sample_restaurants.restaurants que tiene un valor de borough de 'Queens':

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteOne(
    ['borough' => 'Queens'],
);

Para borrar varios documentos, llama al método deleteMany(). La operación especificada borra todos los documentos que coincidan con el filtro de query.

El siguiente ejemplo especifica la eliminación de todos los documentos en la colección sample_restaurants.restaurants que tienen un valor name que contiene dos caracteres 'p' consecutivos:

$restaurantCollection = $client->sample_restaurants->restaurants;
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
$bulkWrite->deleteMany(
    ['name' => ['$regex' => 'p{2,}']],
);

Realizar la Operación Masiva

Después de que construyas la instancia ClientBulkWrite para especificar tus operaciones de guardado, pásala al método MongoDB\Client::bulkWrite(). Por defecto, estos métodos ejecutan las operaciones en el orden que se definió al construir ClientBulkWrite.

El siguiente código demuestra cómo utilizar el método bulkWrite() para realizar una operación de escritura masiva en múltiples namespaces:

$restaurantCollection = $client->sample_restaurants->restaurants;
$movieCollection = $client->sample_mflix->movies;
// Creates the bulk write command and sets the target namespace.
$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection($restaurantCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['name' => 'Mongo Deli', 'cuisine' => 'Sandwiches']);
// Specifies a `$set` update to one document with the upsert option
// enabled.
$bulkWrite->updateOne(
    ['name' => 'Dandelion Bakery'],
    ['$set' => ['grade' => 'B+']],
    ['upsert' => true],
);
// Changes the target namespace.
$bulkWrite = $bulkWrite->withCollection($movieCollection);
// Specifies insertion of one document.
$bulkWrite->insertOne(['title' => 'The Green Ray', 'year' => 1986]);
// Specifies deletion of documents in which `title` has two consective
// 'd' characters.
$bulkWrite->deleteMany(
    ['title' => ['$regex' => 'd{2,}']],
);
// Specifies replacement of one document.
$bulkWrite->replaceOne(
    ['runtime' => ['$gte' => 200]],
    ['title' => 'Seven Samurai', 'runtime' => 203],
);
// Performs the bulk write operation.
$result = $client->bulkWrite($bulkWrite);
// Prints a summary of results.
echo 'Inserted documents: ', $result->getInsertedCount(), PHP_EOL;
echo 'Modified documents: ', $result->getModifiedCount(), PHP_EOL;
echo 'Deleted documents: ', $result->getDeletedCount(), PHP_EOL;

Inserted documents: 2
Modified documents: 2
Deleted documents: 200

Personalizar guardado masivo

Puedes modificar el comportamiento de la operación de escritura masiva del cliente pasando un arreglo al constructor ClientBulkWrite que especifique los valores de las opciones como parámetro. La siguiente tabla describe las opciones que se pueden establecer en el arreglo:

Opción	Descripción
`bypassDocumentValidation`	Especifica si la operación omite la validación del documento. Esto permite modificar documentos que no cumplen con los requisitos de validación del esquema, si los hubiera. Para obtener más información sobre la validación del esquema, consulte la sección «Validación de esquema» en el manual del servidor MongoDB. El valor predeterminado `false` es.
`comment`	Adjunta un comentario a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server.
`let`	Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser expresiones constantes o cerradas que no hagan referencia a campos de documentos. Para obtener más información, consulta la instrucción let en el manual de MongoDB Server.
`ordered`	Si se establece en `true`: Cuando un solo guardar falla, la operación se detiene sin realizar los guardados restantes y lanza una excepción. Si se establece en `false`: Cuando un solo guardar falla, la operación continúa intentando las operaciones de guardar restantes, si las hay, y luego lanza una excepción. El valor por defecto es `true`.
`verboseResults`	Especifica si se deben devolver resultados detallados. El valor por defecto es `false`.

El siguiente ejemplo crea una instancia de ClientBulkWrite y configura la opción ordered en false:

$bulkWrite = MongoDB\ClientBulkWrite::createWithCollection(
    $restaurantCollection,
    ['ordered' => false],
);

Nota

Comportamiento desordenado

Las operaciones masivas desordenadas no garantizan el orden de ejecución. El orden puede diferir de la forma en que los enumeres para optimizar el tiempo de ejecución. Supón que especificas las siguientes operaciones de guardar en una escritura bulk desordenada:

$bulkWrite->insertOne(['_id' => 4045, 'title' => 'The Green Ray']);
$bulkWrite->deleteOne(['_id' => 4045]);

Debido a que la librería podría ejecutar primero cualquier operación, el resultado puede mostrar uno o ningún documento borrado.

También puede pasar opciones al invocar el método bulkWrite() para especificar la sesión cliente o el nivel de confirmación de escritura (write concern) que se usará en la operación.

Valor de retorno

El método MongoDB\Client::bulkWrite() devuelve un objeto MongoDB\BulkWriteCommandResult. Esta clase contiene los siguientes métodos:

Método	Descripción
`getInsertedCount()`	Devuelve el número total de documento guardado por todas las operación de inserción en el comando de guardar masiva.
`getMatchedCount()`	Devuelve el número total de documento que coinciden con todas las operación y reemplazo en el comando de guardar por lotes.
`getModifiedCount()`	Devuelve el número total de documentos modificados por todas las operaciones de actualización y reemplazo en el comando de escritura masiva.
`getUpsertedCount()`	Devuelve el número total de documentos insertados o actualizados por todas las operaciones de actualización y sustitución en el comando de guardado masivo.
`getDeletedCount()`	Devuelve el número total de documentos borrados por todas las operaciones de borrado en el comando de guardar masivo.
`getInsertResults()`	Devuelve un mapa con los resultados de cada operación de inserción exitosa. Cada operación está representada por una clave entera que contiene un documento con información correspondiente a la operación, como el valor `_id` insertado.
`getUpdateResults()`	Devuelve un mapa de los resultados de cada operación de actualizar exitoso. Cada operación está representada por una clave entera, que contiene un documento con información correspondiente a la operación.
`getDeleteResults()`	Devuelve un mapa con los resultados de cada operación de eliminación exitosa. Cada operación está representada por una clave entera que contiene un documento con información correspondiente a dicha operación.
`isAcknowledged()`	Devuelve un booleano que indica si el servidor reconoció la operación masiva.

Guardar masivo de colecciones

Para ejecutar una operación de escritura masiva, pasa un arreglo de operaciones de escritura al método MongoDB\Collection::bulkWrite(). Utiliza la siguiente sintaxis para especificar las operaciones de escritura:

[
    [ 'deleteMany' => [ $filter ] ],
    [ 'deleteOne'  => [ $filter ] ],
    [ 'insertOne'  => [ $document ] ],
    [ 'replaceOne' => [ $filter, $replacement, $options ] ],
    [ 'updateMany' => [ $filter, $update, $options ] ],
    [ 'updateOne'  => [ $filter, $update, $options ] ],
]

Tip

Para obtener más información sobre las operaciones de borrar, inserción, reemplazo y actualizar, consulta Operaciones CRUD.

Cuando llamas al método bulkWrite(), la biblioteca ejecuta automáticamente las operaciones de escritura en el orden que especificas en el arreglo. Para aprender a indicar a bulkWrite() que ejecute las operaciones de escritura en un orden arbitrario, consulta Personalizar operación de escritura masiva

Ejemplo

Este ejemplo ejecuta las siguientes operaciones de escritura en la colección restaurants:

Insert operation para insertar un documento en el que el valor name sea 'Mongo's Deli'
Operación de actualización para actualizar el campo cuisine de un documento en el que el valor name es 'Mongo's Deli'
Operación de borrado para borrar todos los documentos en los que el valor de borough sea 'Manhattan'

$restaurantCollection = $client->sample_restaurants->restaurants;
$result = $restaurantCollection->bulkWrite(
    [
        [
            'insertOne' => [
                ['name' => 'Mongo\'s Deli'],
                ['cuisine' => 'Sandwiches'],
                ['borough' => 'Manhattan'],
                ['restaurant_id' => '1234'],
            ],
        ],
        [
            'updateOne' => [
                ['name' => 'Mongo\'s Deli'],
                ['$set' => ['cuisine' => 'Sandwiches and Salads']],
            ],
        ],
        [
            'deleteMany' => [
                ['borough' => 'Manhattan'],
            ],
        ],
    ],
);

Nota

Cuando la biblioteca ejecuta una operación de lote, utiliza el nivel de confirmación de escritura (write concern) de la colección de destino. El driver reporta todos los errores de nivel de confirmación de escritura (write concern) después de intentar todas las operaciones, independientemente del orden de ejecución.

Personalizar la operación de guardar masiva

Puede modificar el comportamiento del método MongoDB\Collection::bulkWrite() al pasar un arreglo que especifique valores de opción como parámetro. La siguiente tabla describe las opciones que puedes establecer en el arreglo:

Opción	Descripción
`bypassDocumentValidation`	Especifica si la operación omite la validación del documento. Esto permite modificar documentos que no cumplen con los requisitos de validación del esquema, si los hubiera. Para obtener más información sobre la validación del esquema, consulte la sección «Validación de esquema» en el manual del servidor MongoDB. El valor predeterminado `false` es.
`codec`	Establece el códec que se utilizará para codificar o decodificar documentos. Las escrituras masivas utilizan el códec para `insertOne()` las `replaceOne()` operaciones y. Para obtener más información, consulte Codificar datos con códecs de tipo.
`writeConcern`	Establece el nivel de confirmación de escritura (write concern) para la operación. Para más información, consulta nivel de confirmación de escritura (Write Concern) en el manual de MongoDB Server.
`let`	Especifica un documento con una lista de valores para mejorar la legibilidad de la operación. Los valores deben ser expresiones constantes o cerradas que no hagan referencia a campos de documentos. Para obtener más información, consulta la instrucción let en el manual de MongoDB Server.
`ordered`	Si se establece en `true`: Cuando un solo guardar falla, la operación se detiene sin realizar los guardados restantes y lanza una excepción. Si se establece en `false`: Cuando un solo guardar falla, la operación continúa intentando las operaciones de guardar restantes, si las hay, y luego lanza una excepción. El valor por defecto es `true`.
`comment`	Adjunta un comentario a la operación. Para obtener más información, consulte la guía insertar campos de comando en el manual de MongoDB Server.
`session`	Especifica la sesión del cliente a asociar con la operación.

El siguiente ejemplo llama al método bulkWrite() para realizar una operación de inserción y eliminación, y establece la opción ordered en false:

$result = $restaurantCollection->bulkWrite(
    [
        [
            'insertOne' => [
                ['name' => 'Mongo\'s Pizza'],
                ['cuisine' => 'Italian'],
                ['borough' => 'Queens'],
                ['restaurant_id' => '5678'],
            ],
        ],
        [
            'deleteOne' => [
                ['restaurant_id' => '5678'],
            ],
        ],
    ],
    ['ordered' => false],
);

Si la librería ejecuta primero la operación de inserción, se elimina un documento. Si ejecuta primero la operación de borrar, no se borrarán documentos.

Nota

Comportamiento desordenado

Las operaciones masivas no ordenadas no ofrecen garantías del orden de ejecución. El orden puede diferir de la manera en que los enumeras para optimizar el tiempo de ejecución.

Valor de retorno

El método MongoDB\Collection::bulkWrite() devuelve un objeto MongoDB\BulkWriteResult. Esta clase contiene los siguientes métodos:

Método	Descripción
`getInsertedCount()`	Devuelve el número total de documento guardado por todas las operación de inserción en el comando de guardar masiva.
`getInsertedIds()`	Devuelve un mapa de valores de campo `_id` para los documentos insertados por todas las operaciones de inserción en el comando de escritura masiva.
`getMatchedCount()`	Devuelve el número total de documento que coinciden con todas las operación y reemplazo en el comando de guardar por lotes.
`getModifiedCount()`	Devuelve el número total de documentos modificados por todas las operaciones de actualización y reemplazo en el comando de escritura masiva.
`getUpsertedCount()`	Devuelve el número total de documentos insertados o actualizados por todas las operaciones de actualización y sustitución en el comando de guardado masivo.
`getUpsertedIds()`	Devuelve un mapa de valores de campo `_id` para los documentos insertados o actualizados por todas las operaciones de actualización y reemplazo en el comando de escritura masiva.
`getDeletedCount()`	Devuelve el número total de documentos borrados por todas las operaciones de borrado en el comando de guardar masivo.
`isAcknowledged()`	Devuelve un booleano que indica si el servidor reconoció la operación masiva.

Información Adicional

Para aprender cómo realizar operaciones de guardar individuales, consulta los siguientes guías:

Documentación de la API

Para aprender más sobre cualquiera de los métodos o tipos analizados en esta guía, consulta la siguiente documentación de API:

Guardado Masivo del Cliente
Guardar masivo de colecciones
- MongoDB\Collection::bulkWrite()
- MongoDB\BulkWriteResult

Volver

Delete Documents

Transacciones