insertar (comando de base de datos)

Definición

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 insert 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

• 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:

Comportamiento

Ejemplos

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

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

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

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

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

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

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

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

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

Una matriz de documentos que contiene información sobre cualquier error encontrado durante la operación de inserción.

Cambiado en la 6.0.14 versión: (tambiéndisponible 5.0.30 en): Cuando insert se ejecuta en, siempre se informan errores de escritura, incluso si se producen uno mongos insert o más. En versiones anteriores, la ocurrencia de errores de escritura podía provocar que no informara errores de escritura.

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 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 }"
      }
   ]
}