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

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 especifica si bulkWrite() ejecutará las operaciones en orden o no. Por defecto, las operaciones se ejecutan en orden.

El siguiente código representa un bulkWrite() con cinco operaciones.

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document> }
   ]
)

En el estado ordered : true por defecto, cada operación se ejecutará en orden, desde la primera operación insertOne hasta la última operación deleteMany.

Si ordered se establece en false, las operaciones pueden ser reordenadas por mongod para aumentar el rendimiento. Las aplicaciones no deberían depender del orden de ejecución de las operaciones.

El siguiente código representa un bulkWrite() desordenado con seis operaciones:

db.collection.bulkWrite(
   [
      { insertOne : <document> },
      { updateOne : <document> },
      { updateMany : <document> },
      { replaceOne : <document> },
      { deleteOne : <document> },
      { deleteMany : <document> }
   ],
   { ordered : false }
)

Con ordered : false, los resultados de la operación pueden variar. Por ejemplo, deleteOne o deleteMany pueden remover más o menos documentos dependiendo de si se ejecutan antes o después de las operaciones insertOne, updateOne, updateMany o replaceOne.

El número de operaciones en cada grupo no puede superar el valor de maxWriteBatchSize de la base de datos. A partir de MongoDB,3.6 este valor 100,000 es. Este valor se muestra en el hello.maxWriteBatchSize campo.

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.

A partir de MongoDB 3.6, cuando el informe de errores de un lote individual aumenta demasiado, MongoDB trunca todos los mensajes de error restantes a una cadena vacía. Actualmente, comienza cuando hay al menos 2 mensajes de error con un tamaño total superior a 1MB.

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

Las operaciones de escritura bulkWrite() tienen restricciones cuando se usan en una colección con tamaño fijo.

updateOne y updateMany lanzará un WriteError si el criterio update aumenta el tamaño del documento que se está modificando.

replaceOne lanza un WriteError si el documento replacement tiene un tamaño mayor que el documento original.

deleteOne y deleteMany lanzará un WriteError si se utiliza en una colección con tamaño fijo.

Colecciones de series de tiempo

Las operaciones de escriturabulkWrite() tienen restricciones al usarse en series temporales. Solo se puede usar en series temporales. Todas las demás operaciones devolverán.insertOne WriteError

Error Handling

db.collection.bulkWrite() lanza una excepción BulkWriteError 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

db.collection.bulkWrite() puede usarse dentro de transacciones distribuidas.

Ejemplo de guardado masivo ordenado

Es importante que comprendas el orden de las operaciones y el manejo de errores de bulkWrite(). 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 de bulkWrite() usan 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: []
   }
}

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

Para completar todas las operaciones que no tengan errores, ejecuta bulkWrite() con ordered configurado en false. Para ver un ejemplo, consulta la siguiente sección.

Ejemplo de guardado masivo no ordenado

Para especificar un bulkWrite() desordenado, establece ordered en false.

En una lista no ordenada 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 a un error de llave duplicada. En un bulkWrite() desordenado, se completa toda operación que no tenga errores.

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

Cuando db.collection.bulkWrite() se ejecuta en mongos en un clúster fragmentado, siempre se informa de un writeConcernError en la respuesta, incluso cuando se producen uno o más errores adicionales. En versiones anteriores, otros errores a veces causaban que db.collection.bulkWrite() no reportara errores de nivel de confirmación 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 ejemplo bulkWrite() ejecuta operaciones en la colección pizzas y establece un nivel de confirmación de escritura "majority" con un tiempo de espera de 100 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") }
   }
}