/ /

Administración

Docs Home

Desarrollo

Comandos de base de datos

Administración

Docs Home

Desarrollo

Comandos de base de datos

Administración

bulkWrite (comando de base de datos)

Definición

bulkWrite

Nuevo en la versión 8.0.

A partir de MongoDB 8.0, puedes usar el nuevo bulkWrite Comando para realizar múltiples operaciones de inserción, actualización y eliminación en múltiples colecciones en una sola solicitud. El existente db.collection.bulkWrite() El método solo le permite modificar una colección en una solicitud.

Para especificar cada colección en el bulkWrite comando, utilice un espacio de nombres (nombre de base de datos y de colección).

Compatibilidad

Este comando está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Nota

Este comando es compatible con todos los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, consulte Comandos no compatibles.

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

El comando tiene esta sintaxis:

db.adminCommand( {
   bulkWrite: 1,
   // Include the insert, update, and delete operations
   // in the ops array
   ops: [
      {
         insert: <integer>,  // Namespace ID index for insert operation.
                             // Must match a namespace ID index in
                             // ns specified later in the nsInfo array.
         document: <document>
      },
      {
         update: <integer>,  // Namespace ID index for update operation
         filter: <document>,
         updateMods: <document>,
         arrayFilters: [ <filterDocument0>, <filterDocument1>, ...  ],
         multi: <bolean>,
         hint: <document>,
         constants: <document>,
         collation: <document>
      },
      {
         delete: <integer>,  // Namespace ID index for delete operation
         filter: <document>,
         multi: <boolean>,
         hint: <document>,
         collation: <document>
      },
      ...
      // Additional insert, update, and delete operations in any order
      ...
   ],
   // Include the namespaces with collections to modify
   // in the nsInfo array. You can add multiple namespaces here.
   nsInfo: [
      {
         ns: <string>,  // Namespace (database and collection name) to modify.
                        // Each operation namespace ID index
                        // specified in the earlier ops array must
                        // match a namespace ID index here.
         collectionUUID: <string>,
         encryptionInformation: <document>
      },
      ...
      // Additional namespaces
      ...
   ],
   // Additional fields
   ordered: <boolean>,
   bypassDocumentValidation: <boolean>,
   comment: <string>,
   let: <document>,
   errorsOnly: <boolean>,
   cursor: { batchSize: <integer> },
   writeConcern: <string>
} )

En la sintaxis del comando, puede especificar varios:

Insertar, actualizar y eliminar operaciones en cualquier orden en la matriz ops.
Espacios de nombres para las operaciones en la nsInfo matriz. Para que la operación coincida con el espacio de nombres, utilice el mismo índice de ID de espacio de nombres. Los índices empiezan 0 en. Puede usar colecciones fragmentadas.

Campos de comandos

El comando toma los siguientes campos:

Campo	Tipo	Necesidad	Descripción
`insert`	entero	Requerido	Índice de ID de espacio de nombres para una operación de inserción, que debe coincidir con un índice de ID de espacio de nombres en el campo `ns` de la matriz `nsInfo`. Los índices comienzan en `0`.
`document`	Documento	Requerido	Documento para insertar en la colección.
`update`	entero	Requerido	Índice de ID de espacio de nombres para una operación de actualización, que debe coincidir con un índice de ID de espacio de nombres en el campo `ns` de la matriz `nsInfo`. Los índices comienzan en `0`.
`filter`	Documento	Opcional	Selector de consultas para limitar los documentos para la operación de actualización o eliminación.
`updateMods`	Documento	Opcional	Operación de actualización para la colección. Puede especificar una de estas opciones: Un documento con expresiones de operador de actualización. Una canalización de agregación en formato `[ <stage1>, <stage2>, ... ]` con etapas para las actualizaciones.
`arrayFilters`	matriz de documentos	Opcional	Matriz de documentos de filtro que especifican los documentos a modificar para una operación de actualización en un campo de matriz. Para obtener más detalles, consulte Operaciones de actualización de `arrayFilters` matriz con.
`multi`	booleano	Opcional	Si el `multi` campo `true` es, la operación de actualización o eliminación actualiza o elimina todos los documentos que coinciden con el `filter` documento. Si `false` es, la operación actualiza o elimina el primer documento que coincide con el `filter` documento. Para obtener más información sobre las transacciones con varios documentos, consulte Transacciones. El valor por defecto es `false`.
`hint`	Documento	Opcional	Índice que se usará para el `filter` documento. Si el índice no existe, la operación de actualización devuelve un error.
`constants`	Documento	Opcional	Constantes para una actualización personalizada de la canalización de agregación.
`collation`	Documento	Opcional	Intercalación para una operación de actualización o eliminación.
`delete`	entero	Requerido	Índice de ID de espacio de nombres para una operación de eliminación, que debe coincidir con un índice de ID de espacio de nombres en el campo `ns` de la matriz `nsInfo`. Los índices comienzan en `0`.
`ns`	string	Requerido	Espacio de nombres (base de datos y colección) para las operaciones. Establezca el índice de ID de espacio de nombres para cada operación en `ops` con el índice de matriz de espacio de nombres correspondiente en `ns`. Los índices comienzan en `0`.
`collectionUUID`	string	Opcional	Valor hexadecimal UUID que especifica la colección para las operaciones.
`encryptionInformation`	Documento	Opcional	Esquema de información de cifrado y tokens para la operación. Para obtener detalles, consulta Esquemas de cifrado.
`ordered`	booleano	Opcional	Si es `true`, se realizan operaciones ordenadas. De lo contrario, se realizan operaciones desordenadas. Las operaciones ordenadas se ejecutan en serie. Si se produce un error, se cancelan las operaciones restantes. Las operaciones desordenadas se ejecutan en paralelo. Si se produce un error, se ejecutan las sentencias restantes. El servidor puede reordenar las operaciones para mejorar el rendimiento. Por lo tanto, sus aplicaciones no deberían depender del orden de ejecución de las operaciones. El valor por defecto es `true`.
`bypassDocumentValidation`	booleano	Opcional	Si `true` es, la operación omite las reglas de validación del esquema. Si `false` es, los documentos deben ser válidos. El valor por defecto es `false`.
`comment`	string	Opcional	Opcional. Un comentario proporcionado por el usuario para adjuntar a este comando. Una vez configurado, este comentario aparece junto a los registros de este comando en las siguientes ubicaciones: Mensajes de registro de mongod, en el campo `attr.command.cursor.comment`. Salida del perfilador de base de datos, en el campo `command.comment`. `currentOp` de salida, en el campo `command.comment`. Un comentario puede ser de cualquier tipo BSON válido (string, objeto, arreglo, etc.).
`let`	Documento	Opcional	Documento con una lista de constantes a las que se hace referencia en la operación. Para `let` ver ejemplos de, consulte Usar variables en `let` `c` la opción o el campo y Usar variables en.`let`
`errorsOnly`	booleano	Opcional	Si es `true`, la operación solo devuelve errores y omite otras salidas. El valor por defecto es `false`.
`cursor batchSize`	entero	Opcional	Tamaño del lote del cursor para los `bulkWrite` resultados devueltos por el comando. Para más detalles,`cursor.batchSize()` consulte.
`writeConcern`	string	Opcional	Escriba la preocupación sobre la operación. Omita el uso del valor predeterminado del servidor.

Salida

El comando devuelve un documento con estos campos:

Campo	Tipo	Descripción
`cursor`	Documento	Cursor con los resultados del comando.
`cursor.id`	entero	Identificador del cursor.
`cursor.firstBatch`	matriz de documentos	Resultados de las operaciones.
`cursor.firstBatch.ok`	entero	`1` Indica que la operación fue exitosa. De lo contrario, `0`.
`cursor.firstBatch.idx`	entero	Número de índice de la operación, que corresponde a la operación en la matriz `ops`. La primera operación tiene un valor `idx` de `0`.
`cursor.firstBatch.code`	entero	Número de código de un error.
`cursor.firstBatch.errmsg`	string	Descripción de un error.
`cursor.firstBatch.keyPattern`	Documento	Especificación de la clave del índice del documento para un error.
`cursor.firstBatch.keyValue`	Documento	Valor de la clave de índice del documento para un error.
`cursor.firstBatch.n`	entero	Número total de documentos afectados por una operación.
`cursor.firstBatch.nModified`	entero	Número de documentos modificados por una operación de actualización.
`nErrors`	entero	Número de errores para el comando `bulkWrite`.
`nInserted`	entero	Número de documentos insertados.
`nMatched`	entero	Número de documentos coincidentes.
`nModified`	entero	Número de documentos modificados.
`nUpserted`	entero	Número de documentos insertados.
`nDeleted`	entero	Número de documentos eliminados.
`ok`	entero	`1` Indica que el comando `bulkWrite` fue exitoso. De lo contrario, `0`.

Nota

Los campos de salida pueden variar según las operaciones que ejecute en el comando bulkWrite.

Comportamiento

Esta sección describe el comportamiento del comando bulkWrite.

Campos de documentos múltiples y escrituras reintentables

Si el multi campo true es, la operación de actualización o eliminación actualiza o elimina todos los documentos que coinciden con el filter documento. Si false es, la operación actualiza o elimina el primer documento que coincide con el filter documento. Para obtener más información sobre las transacciones con varios documentos, consulte Transacciones.

Para habilitar escrituras reintentables, consulta escrituras reintentables.

Puede utilizar operaciones de inserción bulkWrite con escrituras reintentables y el campo multi establecido en true.

Puede utilizar operaciones de actualización y eliminación bulkWrite con el campo multi configurado en true. Pero no puede utilizar operaciones de actualizar o borrar con ambos multi configurados en true y escrituras reintentables.

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

Cambiado en la versión 8.1.2.

Cuando 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 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.

Rendimiento de la operación

Si reescribe los comandos de inserción, actualización y eliminación existentes como un comando bulkWrite y establece errorsOnly en true, el comando bulkWrite tendrá un rendimiento similar al de los comandos existentes. Si establece errorsOnly en false, el rendimiento será inferior.

Además, si tienes una secuencia de comandos como ésta:

insert
update
delete

Si reemplaza esos comandos con el siguiente fragmento de ejemplo, entonces el comando con el siguiente fragmento será más rápido independientemente de otras opciones:

{
   bulkWrite: 1,
   ops: [
      insert,
      update,
      delete
   ]
}

La mayor parte de la mejora del rendimiento se debe a la latencia de la red, que es variable según la implementación, pero el ejemplo siempre es más rápido.

Ejemplos

Los ejemplos de esta página utilizan datos del conjunto de datos de ejemplo sample_mflix. Para obtener más información sobre cómo cargar este conjunto de datos en su implementación de MongoDB autogestionada, consulte Cargar el conjunto de datos de ejemplo. Si realizó alguna modificación en las bases de datos de ejemplo, es posible que deba eliminarlas y volver a crearlas para ejecutar los ejemplos de esta página.

Ejemplo de escritura masiva en un solo espacio de nombres

El siguiente ejemplo bulkWrite modifica un solo espacio de nombres:

Modify the `users` collection

Ejecute el siguiente comando bulkWrite para realizar operaciones de inserción, actualización y eliminación en la colección users:

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // Specify the namespace ID index immediately after
      // the insert, update, and delete text.
      // For example, "insert: 0" specifies the 0 namespace ID index,
      // which is the "sample_mflix.users" namespace in nsInfo at the end
      // of the example.
      // Insert a user.
      { insert: 0, document: {
         _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e1"),
         name: "Tyrion Lannister",
         email: "tyrion.lannister@example.com",
         password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu"
      } },
      // Update the email for a user named Ned Stark.
      { update: 0, filter: { name: "Ned Stark" },
        updateMods: { $set: { email: "ned.stark.updated@example.com" } } },
      // Delete a user with a specific _id.
      { delete: 0, filter: { _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e1") } }
   ],
   // The nsInfo array contains the namespace to apply the
   // previous operations to.
   nsInfo: [
      { ns: "sample_mflix.users" }  // Namespace ID index is 0.
   ]
} )

La colección users se encuentra en la base de datos sample_mflix, por lo que el espacio de nombres ns es "sample_mflix.users". El índice del ID del espacio de nombres es 0, que se establece en el primer campo de las operaciones de inserción, actualización y eliminación en la matriz ops.

Examinar la salida

El siguiente ejemplo de salida bulkWrite, con varios campos ok: 1 y nErrors: 0, indica que todas las operaciones fueron exitosas:

{
  cursor: {
    id: Long('0'),
    firstBatch: [
      { ok: 1, idx: 0, n: 1 },
      { ok: 1, idx: 1, n: 1, nModified: 1 },
      { ok: 1, idx: 2, n: 1 }
    ],
    ns: 'admin.$cmd.bulkWrite'
  },
  nErrors: 0,
  nInserted: 1,
  nMatched: 1,
  nModified: 1,
  nUpserted: 0,
  nDeleted: 1,
  ok: 1
}

Para obtener detalles sobre los campos de salida, consulte la sección Salida anterior.

Ejemplo de escritura masiva en múltiples espacios de nombres

Puede especificar varios espacios de nombres en un comando bulkWrite.

El siguiente ejemplo bulkWrite contiene operaciones de inserción, actualización y eliminación para dos espacios de nombres:

Modificar las colecciones

Ejecute el siguiente comando bulkWrite para realizar operaciones de inserción, actualización y eliminación en las colecciones users y sample_mflix.theaters:

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // Specify the namespace ID indexes immediately after
      // the insert, update, and delete. For example, "insert: 0"
      // specifies the 0 namespace ID index, which is the "sample_mflix.users"
      // namespace. And, "insert: 1" specifies "sample_mflix.theaters".
      // Insert users.
      // Namespace ID is 0 for "sample_mflix.users", which
      // is specified as "insert: 0".
      { insert: 0, document: {
         _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e7"),
         name: "Sansa Stark",
         email: "sansa.stark@example.com",
         password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu"
      } },
      { insert: 0, document: {
         _id: ObjectId("67a1b2c3d4e5f6a7b8c9d0e8"),
         name: "Bran Stark",
         email: "bran.stark@example.com",
         password: "$2b$12$UREFwsRUoyF0CRqGNK0LzO0HM/jLhgUCNNIJ9RJAqMUQ74crlJ1Vu"
      } },
      // Update the email for a user.
      { update: 0, filter: { name: "Ned Stark" },
        updateMods: { $set: { email: "lord.stark@example.com" } } },
      // Delete users with a specific email pattern.
      { delete: 0, filter: { email: { $regex: "bran.stark" } } },
      // Update theaters.
      // Namespace ID is 1 for "sample_mflix.theaters".
      { update: 1, filter: { theaterId: 1000 },
        updateMods: { $set: { "location.address.city": "Minneapolis" } } },
      // Delete a theater with a specific _id.
      { delete: 1, filter: { _id: ObjectId("59a47286cfa9a3a73e51e72c") } },
      // Delete theaters in a specific state.
      { delete: 1, filter: { "location.address.state": "VT" }, multi: true }
   ],
   // Namespaces
   nsInfo: [
      { ns: "sample_mflix.users" }, // Namespace ID index is 0.
      { ns: "sample_mflix.theaters" }  // Namespace ID index is 1.
   ]
} )

Examinar la salida

El siguiente ejemplo de salida bulkWrite indica que las operaciones fueron exitosas:

{
  cursor: {
    id: Long('0'),
    firstBatch: [
      { ok: 1, idx: 0, n: 1 },
      { ok: 1, idx: 1, n: 1 },
      { ok: 1, idx: 2, n: 1, nModified: 1 },
      { ok: 1, idx: 3, n: 1 },
      { ok: 1, idx: 4, n: 1, nModified: 1 },
      { ok: 1, idx: 5, n: 1 },
      { ok: 1, idx: 6, n: 2 }
    ],
    ns: 'admin.$cmd.bulkWrite'
  },
  nErrors: 0,
  nInserted: 2,
  nMatched: 2,
  nModified: 2,
  nUpserted: 0,
  nDeleted: 4,
  ok: 1
}

Obtén más información

Volver

autoCompact

cloneCollectionAsCapped

Definición

Compatibilidad

Nota

Sintaxis

Campos de comandos

Salida

Nota

Comportamiento

Campos de documentos múltiples y escrituras reintentables

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

Rendimiento de la operación

Ejemplos

Ejemplo de escritura masiva en un solo espacio de nombres

Modify the users collection

Examinar la salida

Ejemplo de escritura masiva en múltiples espacios de nombres

Modificar las colecciones

Examinar la salida

Obtén más información

Modify the `users` collection