/ /

insertar (comando de base de datos)

Definición

insert

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

Tip

mongoshEn, este comando también se puede ejecutar a través del db.collection.insertOne() db.collection.insertMany() Métodos auxiliares y.

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.Consulte la sección "Salida" para obtener más informació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 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	Una matriz 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 la preocupación de escritura del comando. Omitir el uso de la preocupación de escritura `insert` predeterminada. 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 de la documents matriz debe ser menor o igual al 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 fragmentos.

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.

Insertar imprecisiones

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

Tras una inserción correcta, el sistema devuelve, el número de documentos insertados en la colección. Si la operación de inserción se interrumpe debido insert.ninsert.n a un cambio de estado en el conjunto de réplicas, el sistema puede continuar insertando documentos. Como resultado, puede informar menos documentos de los que realmente se insertaron.

Ejemplos

Inserta un solo documento

Insertar un documento en la colección users:

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

El documento devuelto indica que el comando insertó un documento correctamente.Consulte la sección "Salida" para obtener más información.

{ "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. Consulte la sección "Resultado" para obtener más información.

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

Usando Insertar con `bypassDocumentValidation`

Si las acciones de validación del esquema se establecen error en, las inserciones en una colección devuelven errores para los documentos que infringen las reglas de validación del esquema. Para insertar documentos que infrinjan estas reglas,bypassDocumentValidation: true establezca.

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 viola la regla de validación:

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

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

{
   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

Una matriz de documentos que contiene información sobre cualquier error detectado durante la operación de inserción. La matriz contiene un documento de error por cada inserción writeErrors errónea.

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

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

Cambiado en la versión 7.0.6: (también disponible en 6.0.14 y 5.0.30): Cuando insert se ejecuta en mongos, siempre se informa de los errores de nivel de confirmación de escritura (write concern), incluso cuando se produce uno o más errores de escritura. En versiones anteriores, la aparición de errores de guardado podía hacer que insert no informara de los errores del nivel de confirmación de escritura (write concern).

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 es un documento de ejemplo devuelto para un exitoso de un solo insert documento:

{ ok: 1, n: 1 }

El siguiente es un documento de ejemplo devuelto para un de dos documentos que insertaron exitosamente un documento pero encontraron un error con el otro insert 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

mapReduce

Definición

Tip

Compatibilidad

Nota

Sintaxis

Campos de comandos

Comportamiento

Límite de tamaño

Validación de esquema

Transacciones

Importante

Creación de colecciones en transacciones

Nivel de confirmación de escritura y transacciones

Insertar imprecisiones

Ejemplos

Inserta un solo documento

Bulk Insert

Usando Insertar con bypassDocumentValidation

Salida

Usando Insertar con `bypassDocumentValidation`