/ /

Métodos mongosh

Colecciones

Docs Home

Manual de base de datos

Referencia

Métodos mongosh

Colecciones

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

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte Procedimientos de actualización de MongoDB.7.0

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

El método insertOne() tiene la siguiente forma:

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

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

Creación de colección

Si la colección no existe, el método insertOne() crea la colección.

`_id` Campo

Si el documento no especifica un campo _id, entonces mongod agregará el campo _id y asignará un ObjectId() único al documento antes de insertarlo. La mayoría de los controladores crean un ObjectId e insertan el campo _id, pero el mongod 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 con db.collection.explain().

Error Handling

En caso de error, db.collection.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 db.collection.insertOne().

Transacciones

db.collection.insertOne() 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.

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.

Entradas de OpLog

Si una operación db.collection.insertOne() inserta un documento correctamente, la operación agrega una entrada en el oplog (registro de operaciones). Si la operación falla, no se agrega ninguna entrada al oplog.

Ejemplos

Insertar un documento sin especificar un `_id` campo

En el siguiente ejemplo, el documento que pasó al método 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 al método insertOne() incluye el campo _id. El valor de _id debe ser único dentro de la colección para evitar un error 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"
     }
   }
})

Tip

Para insertar varios documentos, consulte db.collection.insertMany()
WriteResult.writeConcernError

Volver

db.collection.insertMany

db.collection.isCapped