/ /

insertar (comando de base de datos)

Definición

insert

Inserta uno o más documentos en una colección y devuelve un documento de estado. Los métodos de inserción del driver de MongoDB utilizan este comando internamente.

Tip

En mongosh, este comando también se puede ejecutar a través de los métodos asistentes db.collection.insertOne() y db.collection.insertMany().

Los métodos asistente son convenientes para usuarios de mongosh, pero es posible que no proporcionen el mismo nivel de información que los comandos de base de datos. En los casos en que no se necesite la conveniencia o se requieran campos de retorno adicionales, utiliza el comando de base de datos.

Devuelve:	Un documento que contiene el estado de la operación. Consulta Salida para obtener más detalles.

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 la siguiente sintaxis:

db.runCommand(
   {
      insert: <collection>,
      documents: [ <document>, <document>, <document>, ... ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>
   }
)

Campos de comandos

El comando toma los siguientes campos:

Campo	Tipo	Descripción
`insert`	string	El nombre de la colección objetivo.
`documents`	arreglo	Un arreglo de uno o más documentos para insertar en la colección nombrada.
`ordered`	booleano	opcional. Si `true`, cuando falla una inserción, regrese sin insertar los documentos restantes. Si `false`, cuando falla una inserción, continúe insertando los documentos restantes. Se establece por defecto en `true`.
`maxTimeMS`	non-negative integer	Opcional. Especifica un límite de tiempo en milisegundos. Si no especifica un valor para `maxTimeMS`, las operaciones no agotarán el tiempo de espera. Un valor de `0` especifica explícitamente el comportamiento por defecto sin límites. MongoDB finaliza las operaciones que exceden su límite de tiempo asignado utilizando el mismo mecanismo que `db.killOp()`. MongoDB solo termina una operación en uno de sus puntos de interrupción designados.
`writeConcern`	Documento	opcional. Especifica el nivel de confirmación de escritura (write concern). Omita para utilizar el nivel de confirmación de escritura (write concern) por defecto. No establezcas explícitamente el nivel de confirmación de escritura para la operación si se ejecuta en una transacción. Para usar el nivel de confirmación de escritura con transacciones, consulta Transacciones y nivel de confirmación de escritura.
`bypassDocumentValidation`	booleano	Opcional. Permite `insert` que omita la validación del esquema durante la operación.
`comment`	any	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.).

Comportamiento

Límite de tamaño

El tamaño total de todos los elementos del arreglo documents no debe exceder el tamaño máximo del documento BSON.

El número total de documentos en el arreglo documents no debe exceder el tamaño máximo por lotes.

Validación de esquema

El comando insert añade compatibilidad con la opción bypassDocumentValidation, que le permite omitir la validación de esquema al insertar o actualizar documentos en una colección con reglas de validación.

Transacciones

insert puede usarse dentro de transacciones distribuidas.

Importante

En la mayoría de los casos, una transacción distribuida incurre en un costo de rendimiento mayor que las escrituras de documentos individuales, y la disponibilidad de transacciones distribuidas no debería ser un sustituto para un diseño de esquema efectivo. Para muchos casos, el modelo de datos desnormalizado (documento incrustado y matrices) seguirá siendo óptimo para tus datos y casos de uso. Es decir, en muchos casos, modelar tus datos de forma adecuada minimizará la necesidad de transacciones distribuidas.

Para consideraciones adicionales sobre el uso de transacciones (como el límite de tiempo de ejecución y el límite de tamaño del oplog), consulta también las consideraciones de producción.

Creación de colecciones en transacciones

Puedes crear colecciones e índices dentro de una transacción distribuida si la transacción no es una transacción de escritura entre particiones.

Si especifica una inserción en una colección inexistente en una transacción, MongoDB crea la colección de forma implícita.

Nivel de confirmación de escritura y transacciones

No establezcas explícitamente el nivel de confirmación de escritura para la operación si se ejecuta en una transacción. Para usar el nivel de confirmación de escritura con transacciones, consulta Transacciones y nivel de confirmación de escritura.

Inexactitud en la inserción

Incluso si se encuentra un error del servidor durante una inserción, es posible que se hayan insertado algunos documentos.

Tras una inserción exitosa, el sistema devuelve el número de documentos insertados en la colección. Si la operación de inserción se interrumpe por un cambio de estado del conjunto de réplicas, el sistema puede continuar insertando documentos. En consecuencia, es posible que se registre un número menor de documentos de los que realmente se insertaron.

Ejemplos

Inserta un solo documento

Inserte un documento en la colección users:

db.runCommand(
   {
      insert: "users",
      documents: [ { _id: 1, user: "abc123", status: "A" } ]
   }
)

La operación devuelve el siguiente documento:

{ "ok" : 1, "n" : 1 }

Bulk Insert

Inserte tres documentos en la colección users:

db.runCommand(
   {
      insert: "users",
      documents: [
         { _id: 2, user: "ijk123", status: "A" },
         { _id: 3, user: "xyz123", status: "P" },
         { _id: 4, user: "mop123", status: "P" }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

La operación devuelve el siguiente documento:

{ "ok" : 1, "n" : 3 }

Uso de Insertar con `bypassDocumentValidation`

Si la validación de esquema validationActions se establece en error, el comando de inserción devuelve un error para los documentos que no superan la validación. Para insertar documentos que infrinjan las reglas de validación, establezca bypassDocumentValidation: true.

Crea la colección user con una regla de validación en los campos status.

La regla de validación valida que el estado debe ser "Desconocido" o "Incompleto":

db.createCollection("users", {
   validator:
      {
         status: {
            $in: [ "Unknown", "Incomplete" ]
         }
      }
})

Inserte un documento que infrinja la regla de validación:

db.runCommand({
      insert: "users",
      documents: [ {user: "123", status: "Active" } ]
})

La inserción devuelve un mensaje de error de guardado:

{
   n: 0,
   writeErrors: [
      {
         index: 0,
         code: 121,
         errInfo: {
            failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'),
            details: {
               operatorName: '$in',
               specifiedAs: { status: { '$in': [Array] } },
               reason: 'no matching value found in array',
               consideredValue: 'Active'
            }
         },
         errmsg: 'Document failed validation'
      }
   ],
   ok: 1
}

Establecer bypassDocumentValidation: true y volver a ejecutar la inserción:

db.runCommand({
   insert: "users",
   documents: [ {user: "123", status: "Active" } ],
   bypassDocumentValidation: true
})

La operación se realiza correctamente.

Para comprobar si hay documentos que infringen las reglas de validación del esquema, utilice el comando validate.

Salida

El documento devuelto contiene un subconjunto de los siguientes campos:

insert.ok: El estado del comando.

insert.n: El número de documentos insertados.

insert.writeErrors

Un arreglo de documentos que contiene información sobre cualquier error encontrado durante la operación de inserción. La writeErrors arreglo contiene un documento de error por cada inserción que presenta un error.

Cada documento de error contiene los siguientes campos:

insert.writeErrors.index: Un número entero que identifica el documento en el arreglo de documents, que utiliza un índice basado en cero.

insert.writeErrors.code: Valor entero que identifica el error.

insert.writeErrors.errmsg: Una descripción del error.

insert.writeConcernError

Documento que describe los errores relacionados con el nivel de confirmación de escritura (write concern).

Modificado en la 7.0.6 versión.:

(Tambiéndisponible 6.0.14 en 5.0.30 y): Cuando insert se ejecuta en, siempre se informan errores de escritura, incluso cuando se produce uno o más mongos insert errores de escritura. En versiones anteriores, la aparición de errores de escritura podía provocar que no informara de errores de escritura.

Los documentos writeConcernError contienen los siguientes campos:

insert.writeConcernError.code: Valor entero que identifica la causa del error del nivel de confirmación de escritura (write concern).

insert.writeConcernError.errmsg: Una descripción de la causa del error de nivel de confirmación de escritura (write concern).

insert.writeConcernError.errInfo.writeConcern

El objeto del nivel de confirmación de escritura (write concern) usado para la operación correspondiente. Para obtener información sobre los campos del objeto de nivel de confirmación de escritura (write concern), se puede consultar Especificación de nivel de confirmación de escritura (write concern).

El objeto del nivel de confirmación de escritura (write concern) también puede contener el siguiente campo, que indica el origen del nivel de confirmación de escritura (write concern):

insert.writeConcernError.errInfo.writeConcern.provenance

Un valor de string que indica dónde se originó el nivel de confirmación de escritura (write concern) (conocido como nivel de confirmación de escritura (write concern) provenance). La siguiente tabla muestra los valores posibles para este campo y su significado:

Origen	Descripción
`clientSupplied`	El nivel de confirmación de escritura se especificó en la aplicación.
`customDefault`	El nivel de confirmación de escritura se originó a partir de un valor por defecto personalizado. Vea `setDefaultRWConcern`.
`getLastErrorDefaults`	El nivel de confirmación de escritura se originó en el campo `settings.getLastErrorDefaults` del set de réplicas.
`implicitDefault`	El nivel de confirmación de escritura (write concern) se originó en el servidor en ausencia de todas las demás especificaciones de nivel de confirmación de escritura (write concern).

El siguiente muestra un ejemplo de salida para una inserción de un solo documento exitosa:

{ ok: 1, n: 1 }

A continuación se muestra un ejemplo de salida cuando un documento se inserta correctamente y un segundo documento falla:

{
   "ok" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
      }
   ]
}

Volver

getMore

mapReduce