db.collection.bulkWrite() (método de mongosh)

Parámetros

El método bulkWrite() acepta los siguientes parámetros:

Operaciones de escritura

db.collection.bulkWrite( [
   { insertOne : { "document" : <document> } }
] )

db.collection.bulkWrite( [
   { updateOne :
      {
         "filter": <document>,
         "update": <document or pipeline>,
         "upsert": <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite( [
   { updateMany :
      {
         "filter" : <document>,
         "update" : <document or pipeline>,
         "upsert" : <boolean>,
         "collation": <document>,
         "arrayFilters": [ <filterdocument1>, ... ],
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite([
   { replaceOne :
      {
         "filter" : <document>,
         "replacement" : <document>,
         "upsert" : <boolean>,
         "collation": <document>,
         "hint": <document|string>
      }
   }
] )

db.collection.bulkWrite([
   { deleteOne : {
      "filter" : <document>,
      "collation" : <document>                   // Available starting in 3.4
   } }
] )

db.collection.bulkWrite([
   { deleteMany: {
      "filter" : <document>,
      "collation" : <document>                    // Available starting in 3.4
   } }
] )

_id Campo

Si el documento no especifica un campo _id, entonces mongod agrega el campo _id y asigna un único ObjectId() al documento antes de insertarlo o actualizarlo. La mayoría de los controladores crean un ObjectId e insertan el campo _id, pero el mongod creará y completará el _id si el controlador o la aplicación no lo hace.

Si el documento contiene un campo _id, el valor de _id debe ser único dentro de la colección para evitar un error de clave duplicada.

Las operaciones de actualización o reemplazo no pueden especificar un valor _id que sea diferente del documento original.

Ejecución de operaciones

El parámetro ordered controla si las operaciones se ejecutan en serie o en cualquier orden.

Con ordered : true (valor predeterminado), las operaciones se ejecutan en serie. Si se produce un error, las operaciones posteriores no se ejecutan.

Con ordered : false, las operaciones pueden ejecutarse en paralelo. Todas las operaciones sin errores se completan, incluso si algunas fallan.

La cantidad de operaciones en cada grupo no puede exceder el valor de maxWriteBatchSize de la base de datos. El valor por defecto de maxWriteBatchSize es 100,000. Este valor se muestra en el campo hello.maxWriteBatchSize.

Este límite previene problemas con mensajes de error demasiado grandes. Si un grupo supera este límite, el controlador del cliente divide el grupo en grupos más pequeños con cantidades menores o iguales al valor del límite. Por ejemplo, con el valor maxWriteBatchSize de 100,000, si la cola consta de 200,000 operaciones, el controlador crea 2 grupos, cada uno con 100,000 operaciones.

Si el informe de errores para una sola agrupación crece demasiado, MongoDB trunca todos los mensajes de error restantes en un string vacío. Si hay al menos dos mensajes de error con un tamaño total superior a 1MB, se truncan.

Los tamaños y la mecánica de agrupación son detalles internos de rendimiento y están sujetos a cambios en versiones futuras.

La ejecución de una ordered lista de operaciones en una colección particionada generalmente será más lenta que la ejecución de una lista unordered, ya que con una lista ordenada, cada operación debe esperar a que la anterior termine.

Colecciones con tamaño fijo

bulkWrite() tiene restricciones sobre las colecciones limitadas:

• updateOne y updateMany lanza un WriteError si la actualización aumenta el tamaño del documento.

• replaceOne lanza un WriteError si el documento de reemplazo es más grande que el original.

• deleteOne y deleteMany arroja un WriteError en colecciones limitadas.

Error Handling

bulkWrite() Lanza una BulkWriteError excepción en caso de errores. Consulte Manejo de errores dentro de las transacciones.

Excluyendo los errores de nivel de confirmación de escritura, las operaciones ordenadas se detienen después de un error, mientras que las operaciones no ordenadas continúan procesando las operaciones de escritura restantes en la cola, a menos que se ejecuten dentro de una transacción. Vea Manejo de errores dentro de las transacciones.

Los errores de nivel de confirmación de escritura se muestran en el campo writeConcernErrors, mientras que todos los demás errores se muestran en el campo writeErrors. Si se encuentra un error, se muestra el número de operaciones de escritura exitosas en lugar de los valores _id insertados. Las operaciones ordenadas muestran el único error encontrado, mientras que las operaciones desordenadas muestran cada error en un arreglo.

Transacciones

bulkWrite() se puede utilizar dentro de transacciones distribuidas.

Ejemplo de guardado masivo ordenado

Es importante comprender el orden de las operaciones bulkWrite() y la gestión de errores. Por defecto, bulkWrite() ejecuta una lista ordenada de operaciones:

• Las operaciones se ejecutan de forma secuencial.

• Si una operación tiene un error, esa operación y las siguientes no se ejecutarán.

• Las operaciones aparecen antes de que se complete la operación de error.

Los ejemplos bulkWrite() utilizan la colección pizzas:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

El siguiente ejemplo ejecuta estas operaciones en bulkWrite() la pizzas colección:

• Agrega dos documentos con insertOne.

• Actualiza un documento con updateOne.

• Elimina un documento con deleteOne.

• Reemplaza un documento con replaceOne.

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 4, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ] )
} catch( error ) {
   print( error )
}

Ejemplo de salida, que incluye un resumen de las operaciones completadas:

{
   acknowledged: true,
   insertedCount: 2,
   insertedIds: { '0': 3, '1': 4 },
   matchedCount: 2,
   modifiedCount: 2,
   deletedCount: 1,
   upsertedCount: 0,
   upsertedIds: {}
}

Si la colección ya contenía un documento con un _id de 4 antes de ejecutar el ejemplo anterior bulkWrite(), se devuelve la siguiente excepción de clave duplicada para la segunda operación insertOne:

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
         op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 4 }',
               op: { _id: 4, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 4 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 0,
      nModified: 0,
      nRemoved: 0,
      upserted: []
   }
}

Como el ejemplo bulkWrite() está ordenado, solo se completa la primera operación insertOne.

Para completar todas las operaciones sin errores, ejecute bulkWrite() con ordered establecido en false. Para ver un ejemplo, consulte la siguiente sección.

Ejemplo de guardado masivo no ordenado

Para especificar un bulkWrite() no ordenado, establezca ordered en false.

En una lista desordenada bulkWrite() de operaciones:

• Las operaciones pueden ejecutarse en paralelo (no está garantizado). Para obtener más detalles, consulte Operaciones ordenadas o no ordenadas.

• Las operaciones con errores no se completan.

• Se han completado todas las operaciones sin errores.

Continuando con el ejemplo de la colección pizzas, descarta y vuelve a crear la colección:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

En el siguiente ejemplo:

• bulkWrite() ejecuta operaciones no ordenadas en la colección pizzas.

• La segunda operación insertOne tiene el mismo _id que la primera insertOne, lo que causa un error de llave duplicada.

try {
   db.pizzas.bulkWrite( [
      { insertOne: { document: { _id: 3, type: "beef", size: "medium", price: 6 } } },
      { insertOne: { document: { _id: 3, type: "sausage", size: "large", price: 10 } } },
      { updateOne: {
         filter: { type: "cheese" },
         update: { $set: { price: 8 } }
      } },
      { deleteOne: { filter: { type: "pepperoni"} } },
      { replaceOne: {
         filter: { type: "vegan" },
         replacement: { type: "tofu", size: "small", price: 4 }
      } }
   ],
   { ordered: false } )
} catch( error ) {
   print( error )
}

Ejemplo de salida, que incluye el error de llave duplicada y un resumen de las operaciones completadas.

writeErrors: [
   WriteError {
      err: {
         index: 1,
         code: 11000,
         errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
         op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
      }
   }
],
result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [
         WriteError {
            err: {
               index: 1,
               code: 11000,
               errmsg: 'E11000 duplicate key error collection: test.pizzas index: _id_ dup key: { _id: 3 }',
               op: { _id: 3, type: 'sausage', size: 'large', price: 10 }
            }
         }
      ],
      writeConcernErrors: [],
      insertedIds: [ { index: 0, _id: 3 }, { index: 1, _id: 3 } ],
      nInserted: 1,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 1,
      upserted: []
   }
}

La segunda operación insertOne falla debido al error de clave duplicada. En un bulkWrite() desordenado, cualquier operación sin errores se completa.

Errores de nivel de confirmación de escritura (write concern) en clústeres particionados

Cuando bulkWrite() se ejecuta en en un clúster mongos fragmentado,writeConcernError siempre se informa un en la respuesta, incluso si se producen uno o más errores. En versiones anteriores, otros errores a veces provocaban bulkWrite() que no informara errores de escritura.

Por ejemplo, si un documento no supera la validación, activando un error DocumentValidationFailed, y también ocurre un error de nivel de confirmación de escritura, tanto el error DocumentValidationFailed como el writeConcernError se devuelven en el campo de nivel superior de la respuesta.

Ejemplo de guardado masivo con nivel de confirmación de escritura

Continuando con el ejemplo de la colección pizzas, descarta y vuelve a crear la colección:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

El siguiente bulkWrite() ejemplo ejecuta operaciones en la pizzas colección y establece "majority" una 100 preocupación de escritura con un tiempo de espera de milisegundos:

try {
   db.pizzas.bulkWrite( [
      { updateMany: {
         filter: { size: "medium" },
         update: { $inc: { price: 0.1 } }
      } },
      { updateMany: {
         filter: { size: "small" },
         update: { $inc: { price: -0.25 } }
      } },
      { deleteMany: { filter: { size: "large" } } },
      { insertOne: {
         document: { _id: 4, type: "sausage", size: "small", price: 12 }
      } } ],
      { writeConcern: { w: "majority", wtimeout: 100 } }
   )
} catch( error ) {
   print( error )
}

Si el tiempo para que la mayoría de los miembros del set de réplicas reconozcan las operaciones supera wtimeout, el ejemplo devuelve un error de nivel de confirmación de escritura y un resumen de las operaciones completadas:

result: BulkWriteResult {
   result: {
      ok: 1,
      writeErrors: [],
      writeConcernErrors: [
         WriteConcernError {
            err: {
               code: 64,
               codeName: 'WriteConcernTimeout',
               errmsg: 'waiting for replication timed out',
               errInfo: { wtimeout: true, writeConcern: [Object] }
            }
         }
      ],
      insertedIds: [ { index: 3, _id: 4 } ],
      nInserted: 0,
      nUpserted: 0,
      nMatched: 2,
      nModified: 2,
      nRemoved: 0,
      upserted: [],
      opTime: { ts: Timestamp({ t: 1660329086, i: 2 }), t: Long("1") }
   }
}