/ /

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 la versión 8.0 o posterior del servidor de MongoDB, puedes utilizar el MongoDB\Client::bulkWrite() método para realizar operaciones de guardar masiva en varias colecciones y bases de datos en el mismo clúster. Este método realiza todas las operaciones de escritura en una sola llamada a la base de datos. Para aprender más información sobre esta funcionalidad, consulta Mongo.bulkWrite() referencia en el manual del servidor 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

Al utilizar la librería PHP v2.1 y conectarse a una implementación que ejecuta MongoDB Server 8.0 o posterior, se puede usar la MongoDB\Client::bulkWrite() método 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, usa el desarrollador MongoDB\ClientBulkWrite para crear un BulkWriteCommand instancia que especifica las operaciones de guardar a realizar. El siguiente código demuestra cómo crear una instancia de ClientBulkWrite a partir de una instancia de MongoDB\Collection utilizando 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`	Specifies whether the operation bypasses document validation. This lets you modify documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. The default is `false`.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`ordered`	If set to `true`: When a single write fails, the operation stops without performing the remaining writes and throws an exception. If set to `false`: When a single write fails, the operation continues to attempt the remaining write operations, if any, then throws an exception. The default is `true`.
`verboseResults`	Specifies whether to return verbose results. The default is `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()`	Returns the total number of documents inserted by all insert operations in the bulk write command.
`getMatchedCount()`	Returns the total number of documents matched by all update and replace operations in the bulk write command.
`getModifiedCount()`	Returns the total number of documents modified by all update and replace operations in the bulk write command.
`getUpsertedCount()`	Returns the total number of documents upserted by all update and replace operations in the bulk write command.
`getDeletedCount()`	Return the total number of documents deleted by all delete operations in the bulk write command.
`getInsertResults()`	Returns a map of results of each successful insert operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation such as the inserted `_id` value.
`getUpdateResults()`	Returns a map of results of each successful update operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation.
`getDeleteResults()`	Returns a map of results of each successful delete operation. Each operation is represented by an integer key, which contains a document with information corresponding to the operation.
`isAcknowledged()`	Returns a boolean indicating whether the server acknowledged the bulk operation.

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`	Specifies whether the operation bypasses document validation. This lets you modify documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. The default is `false`.
`codec`	Sets the codec to use for encoding or decoding documents. Bulk writes use the codec for `insertOne()` and `replaceOne()` operations. For more information, see Encode Data with Type Codecs.
`writeConcern`	Sets the write concern for the operation. For more information, see Write Concern in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.
`ordered`	If set to `true`: When a single write fails, the operation stops without performing the remaining writes and throws an exception. If set to `false`: When a single write fails, the operation continues to attempt the remaining write operations, if any, then throws an exception. The default is `true`.
`comment`	Attaches a comment to the operation. For more information, see the insert command fields guide in the MongoDB Server manual.
`session`	Specifies the client session to associate with the operation.

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()`	Returns the total number of documents inserted by all insert operations in the bulk write command.
`getInsertedIds()`	Returns a map of `_id` field values for documents inserted by all insert operations in the bulk write command.
`getMatchedCount()`	Returns the total number of documents matched by all update and replace operations in the bulk write command.
`getModifiedCount()`	Returns the total number of documents modified by all update and replace operations in the bulk write command.
`getUpsertedCount()`	Returns the total number of documents upserted by all update and replace operations in the bulk write command.
`getUpsertedIds()`	Returns a map of `_id` field values for documents upserted by all update and replace operations in the bulk write command.
`getDeletedCount()`	Return the total number of documents deleted by all delete operations in the bulk write command.
`isAcknowledged()`	Returns a boolean indicating whether the server acknowledged the bulk operation.

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