db.collection.insertOne() (método de mongosh)

MongoDB con controladores

Esta página documenta una mongosh . Para ver el método equivalente en un driver de MongoDB, se debe consultar la página correspondiente al lenguaje de programación:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definición

db.collection.insertOne()

Inserta un único documento en una colección.

Devuelve:	Un documento que contiene: Un valor booleano `acknowledged` como `true` si la operación se ejecutó con escribir preocupación o `false` si la escritura preocupación estaba deshabilitada. Un campo `insertedId` con el valor `_id` del documento recién insertado.

Compatibilidad

Este método 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

db.collection.insertOne() tiene la siguiente forma:

db.collection.insertOne(
    <document>,
    {
      writeConcern: <document>
    }
)

Parámetros

insertOne() toma los siguientes parámetros:

Parameter	Tipo	Descripción
`document`	Documento	Un documento para insertar en la colección.
`writeConcern`	Documento	Opcional. Un documento que expresa el nivel de confirmación de escritura. Omite el uso del nivel de confirmación de escritura 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.

Comportamientos

Colección y `_id` creación de campos

Si la colección no existe, entonces insertOne() crea la colección.

Si el documento a insertar no especifica un campo _id, entonces mongod agrega el campo _id y asigna un ObjectId() único para el documento. La mayoría de los controladores crean un ObjectId e insertan el campo _id, pero el mongod lo creará y completará el _id si el controlador o la aplicación no lo hacen.

Si el documento contiene un campo _id, el valor de _id debe ser único dentro de la colección para evitar un error de clave duplicada.

Explicabilidad

insertOne() no es compatible db.collection.explain() con.

Error Handling

En caso de error, insertOne() genera una excepción writeError o writeConcernError.

Errores de validación de esquema

Si su colección utiliza validación de esquema y tiene validationAction configurado en error, insertar un documento no válido arroja un MongoServerError y se produce un error con insertOne().

Transacciones

insertOne() se puede utilizar 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.

Entradas de OpLog

Si una insertOne() operación inserta correctamente un documento, se añade una entrada al registro de operaciones. Si falla, no se añade ninguna entrada.

Ejemplos

Insertar un documento sin especificar un `_id` campo

En el siguiente ejemplo, el documento pasado a insertOne() no contiene el campo _id:

try {
   db.products.insertOne( { item: "card", qty: 15 } );
} catch (e) {
   print (e);
};

La operación devuelve el siguiente documento:

{
   "acknowledged" : true,
   "insertedId" : ObjectId("56fc40f9d735c28df206d078")
}

Debido a que los documentos no incluían _id, mongod crea y añade el campo _id y le asigna un valor único de ObjectId().

Los valores de ObjectId son específicos de la máquina y del momento en que se ejecuta la operación. Por lo tanto, tus valores pueden diferir de los del ejemplo.

Insertar un documento especificando un `_id` campo

En el siguiente ejemplo, el documento pasado a insertOne() incluye el campo _id. El valor de _id debe ser único dentro de la colección para evitar errores de clave duplicada.

try {
   db.products.insertOne( { _id: 10, item: "box", qty: 20 } );
} catch (e) {
   print (e);
}

La operación devuelve lo siguiente:

{ "acknowledged" : true, "insertedId" : 10 }

Insertar un valor duplicado para cualquier clave que sea parte de un índice único, como _id, genera una excepción. Lo siguiente intenta insertar un documento con un valor _id que ya existe:

try {
   db.products.insertOne( { _id: 10, "item" : "packing peanuts", "qty" : 200 } );
} catch (e) {
   print (e);
}

Dado que _id: 10 ya existe, se lanza la siguiente excepción:

WriteError({
   "index" : 0,
   "code" : 11000,
   "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 10.0 }",
   "op" : {
      "_id" : 10,
      "item" : "packing peanuts",
      "qty" : 200
   }
})

Aumento del nivel de confirmación de escritura

Dado un set de réplicas de tres nodos, la siguiente operación especifica un w de majority, wtimeout de 100:

try {
   db.products.insertOne(
       { "item": "envelopes", "qty": 100, type: "Self-Sealing" },
       { writeConcern: { w : "majority", wtimeout : 100 } }
   );
} catch (e) {
   print (e);
}

Si el reconocimiento tarda más que el límite de wtimeout, se obtiene la siguiente excepción:

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

Volver

db.collection.insertMany

db.collection.isCapped