/ /

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.

Piensa en un escenario en el que necesitas insertar un documento en una colección, actualizar varios otros documentos y luego borrar un documento. Si utilizas métodos individuales, cada operación requiere su propia llamada a la base de datos. En su lugar, puedes usar una operación por lotes para reducir el número de llamadas a la base de datos.

Datos de muestra

Los ejemplos de esta guía utilizan la colección restaurants en la base de datos sample_restaurants de los conjuntos de datos de muestra de Atlas. Para acceder a esta colección desde tu aplicación PHP, instancia un MongoDB\Client que se conecte a un clúster Atlas y asigna el siguiente valor a tu variable $collection:

$collection = $client->sample_restaurants->restaurants;

Para aprender a crear un clúster gratuito de MongoDB Atlas y cargar los conjuntos de datos de muestra, consulta Comienza con Atlas.

Operaciones masivas

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

[
    [ '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 se llama al método bulkWrite(), la biblioteca ejecuta automáticamente las operaciones de escritura en el orden especificado en el arreglo. Para aprender cómo indicar a bulkWrite() que ejecute las operaciones de guardado en un orden arbitrario, consulta Modificar comportamiento de guardado en bloque.

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'

$result = $collection->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'],
            ],
        ],
    ],
);

Modificar el comportamiento de guardar masivo

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 de documentos. Esto le permite modificar documentos que no cumplen los requisitos de validación de esquema, si los hay. Para obtener más información sobre la validación de esquemas, consulte Validación de esquemas en el manual de MongoDB Server. Por defecto, se establece en `false`.
`codec`	Establece el códec que se utilizará para codificar o decodificar documentos. Los guardados en lote utilizan el códec para las operaciones `insertOne()` y `replaceOne()`. 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 guardado falla, la operación se detiene sin realizar los guardados restantes y lanza una excepción. Si se establece en `false`: cuando un solo guardado falla, la operación continúa intentando las operaciones de guardado restantes, si las hay, y luego lanza una excepción. Se establece por defecto en `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 = $collection->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

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 las siguientes funciones miembro:

Función	Descripción
`getDeletedCount()`	Devuelve el número de documentos borrados, si los hay.
`getInsertedCount()`	Devuelve el número de documentos insertados, si los hay.
`getInsertedIds()`	Devuelve un mapa de valores de campo `_id` para los Documentos insertados, si corresponde.
`getMatchedCount()`	Devuelve el número de documentos coincidentes durante las operaciones de actualización y reemplazo, si corresponde.
`getModifiedCount()`	Devuelve el número de documentos modificados, si los hay.
`getUpsertedCount()`	Devuelve el número de documentos actualizados o insertados, si los hay.
`getUpsertedIds()`	Devuelve un mapa de los valores de campo `_id` para los documentos actualizados o insertados, de haberlos.
`isAcknowledged()`	Devuelve un valor booleano que indica si se reconoció la operación en bloque.

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:

Volver

Delete Documents

Transacciones