/ /

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 utilizar el nuevo bulkWrite comando para realizar muchas operaciones de inserción, actualización y eliminación en varias 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 comando bulkWrite, utilice un namespace (base de datos y nombre de la 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 borrar operaciones en cualquier orden en el arreglo ops.
Espacios de nombres para las operaciones en el arreglo nsInfo. Para correlacionar la operación con el namespace, utiliza el mismo índice de ID de namespace. Los índices comienzan en 0. Se pueden utilizar colecciones fragmentadas.

Campos de comandos

El comando toma los siguientes campos:

Campo	Tipo	Necesidad	Descripción
`insert`	entero	Requerido	Índice de ID de namespace para una operación de inserción, que debe coincidir con un índice de ID de namespace en el campo `ns` del arreglo `nsInfo`. Los índices comienzan en `0`.
`document`	Documento	Requerido	Documento para insertar en la colección.
`update`	entero	Requerido	Índice de ID de namespace para una operación de actualización, que debe coincidir con un índice de ID de namespace en el campo `ns` en el arreglo `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 a realizar en la colección. Puedes especificar uno de estos: 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	Arreglo de documentos de filtro que especifican los documentos que se modificarán en una operación de actualizar sobre un campo de arreglo. Para más detalles, consulta Operaciones de actualización de arreglos con `arrayFilters`.
`multi`	booleano	Opcional	Si el campo `multi` es `true`, la operación de actualización o eliminación actualiza o elimina todos los documentos que coincidan con el documento `filter`. Si `false`, la operación actualiza o elimina el primer documento que coincide con el documento `filter`. Para obtener detalles sobre transacciones multidocumento, 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 pipeline de agregación actualización personalizada.
`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	namespace (base de datos y colección) para las operaciones. Establezca el índice de ID de espacio de nombres para cada operación en `ops` al índice correspondiente en la matriz de espacios de nombres en `ns`. Los índices empiezan 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 todas las operaciones restantes. Las operaciones no ordenadas se ejecutan en paralelo. Si se produce un error, se ejecutarán todas las instrucciones restantes. El servidor puede reorganizar las operaciones para mejorar el rendimiento. Por lo tanto, sus aplicaciones no deben 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 hacer referencia en la operación. Para obtener ejemplos de `let`, consulte utilizar variables en la opción `let` o en el campo `c` y utilizar 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 de cursor para los resultados devueltos por el comando `bulkWrite`. Para más detalles, consulte `cursor.batchSize()`.
`writeConcern`	string	Opcional	nivel de confirmación de escritura (write concern) para la operación. Omitir para usar el por defecto 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. Si no, `0`.
`cursor.firstBatch.idx`	entero	Número de índice de operación, que corresponde a la operación en el arreglo `ops`. La primera operación tiene un valor de `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 de índice del documento para un error.
`cursor.firstBatch.keyValue`	Documento	Valor clave de índice de 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 dependiendo de las operaciones que ejecutes en el comando bulkWrite.

Comportamiento

Esta sección describe el comportamiento del comando bulkWrite.

Campo de múltiples documentos y escrituras reintentoables

Si el campo multi es true, la operación de actualización o eliminación actualiza o elimina todos los documentos que coincidan con el documento filter. Si false, la operación actualiza o elimina el primer documento que coincide con el documento filter. Para obtener detalles sobre transacciones multidocumento, consulte Transacciones.

Para habilitar escrituras reintentables, consulta escrituras reintentables.

Puede utilizar bulkWrite operaciones de inserción con escrituras reintentables y el campo multi configurado 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 se reescriben los comandos existentes de insertar, actualizar y borrar como un comando bulkWrite y se establece errorsOnly en true, el comando bulkWrite tendrá un rendimiento similar al de los comandos existentes. Si configuras errorsOnly en false, el rendimiento es peor.

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

insert
update
delete

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

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

La mayor parte de la mejora en el rendimiento se debe a la latencia de la red, la cual varía 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 único namespace

El siguiente ejemplo de bulkWrite modifica un único espacio de nombres:

Modificar la colección `users`

Ejecuta 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 el resultado

El siguiente bulkWrite ejemplo de salida, 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 múltiples namespace en un comando bulkWrite.

El siguiente ejemplo de 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 el resultado

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

Campo de múltiples documentos y escrituras reintentoables

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 único namespace

Modificar la colección users

Examinar el resultado

Ejemplo de escritura masiva en múltiples espacios de nombres

Modificar las colecciones

Examinar el resultado

Obtén más información

Modificar la colección `users`