/ /

Comandos de base de datos

Consulta & guardar

Docs Home

Manual de base de datos

Referencia

Comandos de base de datos

Consulta & guardar

insertar (comando de base de datos)

Esta versión de la documentación se archivó y ya no se admite. Para actualizar tu implementación de 6.0, consulta el Procedimientos de actualización de MongoDB.7.0

Definición

insert

El comando insert inserta uno o más documentos y devuelve un documento que contiene el estado de todas las inserciones. Los métodos de inserción proporcionados por los drivers de MongoDB usan este comando internamente.

Tip

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

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 es `true`, si falla la inserción de un documento, se retorna sin insertar los documentos restantes de la matriz `inserts`. Si es `false`, si falla la inserción de un documento, se continúa insertando los documentos restantes. El valor predeterminado es `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. Un documento que expresa el nivel de confirmación de escritura (write concern) del comando `insert`. Omitir para usar 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 que `insert` omita la validación de esquema durante la operación. Esto permite insertar documentos que no cumplen con los requisitos de validació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 debe ser menor o igual que el tamaño máximo del documento BSON."

El número total de documentos en la documents matriz debe ser menor o igual al tamaño masivo máximo.

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

Puede crear colecciones e índices dentro de una transacción distribuida si la transacción es 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.

Tip

Crear colecciones e índices en una transacción

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 produce un error del servidor durante una inserción, es posible que se hayan insertado algunos documentos.

Después de una inserción exitosa, el sistema devuelve insert.n, el número de documentos insertados en la colección. Si la operación de inserción se interrumpe debido a un cambio de estado del set de réplicas, el sistema puede continuar insertando documentos. Como resultado, insert.n podría reportar menos documentos de los que se insertaron realmente.

Ejemplos

Inserta un solo documento

Inserte un documento en la colección users:

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

El documento retornado muestra que el comando insertó con éxito un documento. Consulta Salida para obtener más detalles.

{ "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 }
   }
)

El documento devuelto muestra que el comando insertó correctamente los tres documentos. Consulta Salida para obtener más detalles.

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

Uso de Insertar con `bypassDocumentValidation`

Si validación de esquema validationActions está configurado en error, las inserciones en una colección arrojan errores para los documentos que violan las reglas de validación del esquema. Para insertar documentos que violarían estas reglas, configure 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" ]
         }
      }
})

Intento de insertar un documento que infringe 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
}

Establezca bypassDocumentValidation : true y vuelva a ejecutar la inserción:

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

La operación tiene éxito.

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 entero que identifica el documento en la matriz 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

Un arreglo de documentos que contienen información relativa a cualquier error encontrado durante la operación de inserción.

Cambiado en la versión 6.0.14: (también disponible en 5.0.30): Cuando insert se ejecuta en mongos, siempre se informan los errores de nivel de confirmación de escritura (write concern), incluso cuando ocurre uno o más errores de escritura. En versiones anteriores, la ocurrencia de errores de escritura podía provocar que insert no informara errores de nivel de confirmación de escritura (write concern).

Cada documento de error contiene 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 es un ejemplo de documento devuelto tras una insert exitosa de un único documento:

{ ok: 1, n: 1 }

El siguiente es un ejemplo de documento devuelto para un insert de dos documentos que lograron insertar un documento pero encontraron un error con el otro documento:

{
   "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

resetError