Importante
Método obsoleto de mongosh
Definición
db.collection.insert()Inserta uno o varios documentos en una colección.
Devuelve: Un objeto WriteResult para inserciones individuales.
Un objeto BulkWriteResult para inserciones en bloque.
Sintaxis
El método insert() tiene la siguiente sintaxis:
db.collection.insert( <document or array of documents>, { writeConcern: <document>, ordered: <boolean> } )
Parameter | Tipo | Descripción |
|---|---|---|
| documento o arreglo | Un documento o un arreglo de documentos para insertar en la colección. |
| Documento | Opcional. Un documento que expresa la Escribir preocupación. Omitir el uso de la preocupación de escritura predeterminada. Ver Escribir preocupación. 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. |
| booleano | Opcional. Si Si Se establece por defecto en |
El insert() devuelve un objeto que contiene el estado de la operación.
Comportamientos
Nivel de confirmación de escritura
El método insert() utiliza el comando insert, que emplea el nivel de confirmación de escritura por defecto. Para especificar un nivel de confirmación de escritura diferente, incluye el nivel de confirmación de escritura en el parámetro de opciones.
Crear colección
Si la colección no existe, entonces el método insert() creará la colección.
_id Campo
Si el documento no especifica un campo _id, MongoDB agregará el campo _id y asignará un ObjectId() único para el documento antes de insertarlo. La mayoría de los drivers crean un ObjectId e insertan el campo _id, pero el mongod creará y rellenará el _id si el driver 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.
Transacciones
db.collection.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.
Entradas de OpLog
Si una operación db.collection.insert() 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
Los siguientes ejemplos insertan documentos en la colección products. Si la colección no existe, el método insert() crea la colección.
Insertar un documento sin especificar un _id campo
En el siguiente ejemplo, el documento que pasó al método insert() no contiene el campo _id:
db.products.insert( { item: "card", qty: 15 } )
Durante la inserción, mongod creará el campo _id y le asignará un valor único ObjectId(), tal como lo verifica el documento insertado:
{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }
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 insert() incluye el campo _id. El valor de _id debe ser único dentro de la colección para evitar un error de clave duplicada.
db.products.insert( { _id: 10, item: "box", qty: 20 } )
La operación inserta el siguiente documento en la colección products:
{ "_id" : 10, "item" : "box", "qty" : 20 }
Inserta varios documentos
El siguiente ejemplo realiza una inserción masiva de tres documentos al pasar un arreglo de documentos al método insert(). Por defecto, MongoDB realiza una inserción ordenada. Con las inserciones ordenadas, si se produce un error durante la inserción de uno de los documentos, MongoDB devuelve un error sin procesar los documentos restantes del arreglo.
Los documentos en el arreglo no necesitan tener los mismos campos. Por ejemplo, el primer documento del arreglo tiene un campo _id y un campo type. Debido a que el segundo y el tercer documento no contienen un campo _id, mongod creará el campo _id para el segundo y el tercer documento durante la inserción:
db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" }, { item: "pen", qty: 20 }, { item: "eraser", qty: 25 } ] )
La operación insertó los siguientes tres documentos:
{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" } { "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 } { "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }
Realizar una inserción no ordenada
El siguiente ejemplo realiza una inserción no ordenada de tres documentos. Con las inserciones desordenadas, si se produce un error durante la inserción de uno de los documentos, MongoDB continúa insertando los documentos restantes en el arreglo.
db.products.insert( [ { _id: 20, item: "lamp", qty: 50, type: "desk" }, { _id: 21, item: "lamp", qty: 20, type: "floor" }, { _id: 22, item: "bulk", qty: 100 } ], { ordered: false } )
Anular el nivel de confirmación de escritura (write concern) por defecto
La siguiente operación a un set de réplicas especifica un nivel de confirmación de escritura (write concern) de w: 2 con un wtimeout de 5000 milisegundos. Esta operación regresa después de que el guardado se propaga tanto al primario como a un secundario, o expira después de 5 segundos.
db.products.insert( { item: "envelopes", qty : 100, type: "Clasp" }, { writeConcern: { w: 2, wtimeout: 5000 } } )
WriteResult
Cuando se pasa un único documento, insert() devuelve un objeto WriteResult.
Resultados exitosos
El insert() devuelve un objeto WriteResult() que contiene el estado de la operación. En caso de éxito, el objeto WriteResult() contiene información sobre el número de documentos insertados:
WriteResult({ "nInserted" : 1 })
Errores de nivel de confirmación de escritura
Si el método insert() encuentra errores de nivel de confirmación de escritura (write concern), los resultados incluyen el campo WriteResult.writeConcernError:
WriteResult({ "nInserted" : 1, "writeConcernError"({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })
Errores no relacionados con el nivel de confirmación de escritura (write concern)
Si el método insert() encuentra un error que no es de nivel de confirmación de escritura (write concern), los resultados incluyen el campo WriteResult.writeError:
WriteResult({ "nInserted" : 0, "writeError" : { "code" : 11000, "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.foo.$_id_ dup key: { : 1.0 }" } })
BulkWriteResult
Cuando se le pasa un arreglo de documentos, insert() devuelve un objeto BulkWriteResult(). Consulte BulkWriteResult() para más detalles.