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
db.collection.insert() tiene la siguiente sintaxis:
db.collection.insert( <document or array of documents>, { writeConcern: <document>, ordered: <boolean> } )
Parámetros
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 nivel de confirmación de escritura (write concern). Omitir para utilizar el nivel de confirmación de escritura (write concern) por defecto. See nivel de confirmación de escritura (write concern). 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 |
Comportamientos
Nivel de confirmación de escritura
El método insert() utiliza el comando insert, que utiliza la nivel de confirmación de escritura (write concern) predeterminada. Para especificar un nivel de confirmación de escritura (write concern) diferente, incluya el nivel de confirmación de escritura (write concern) en el parámetro de opciones.
Creación de colección y campo _id
Si la colección no existe, insert() 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.
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 particiones.
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 de insert() inserta correctamente un documento, la operación agrega una entrada en el oplog (registro de operaciones). Si la operación falla, la operación no agrega una entrada en el registro opcional (oplog).
Ejemplos
Los siguientes ejemplos insertan documentos en la colección products. Si la colección no existe, insert() la crea.
Insertar un documento sin especificar un _id campo
En el siguiente ejemplo, el documento pasado a 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 que especifique un campo _id
En el siguiente ejemplo, el documento pasado a insert() incluye el campo _id. El valor de _id debe ser único dentro de la colección para evitar errores 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 pasando una matriz de documentos insert() a. De forma predeterminada, MongoDB realiza una inserción ordenada. Con inserciones ordenadas, si se produce un error durante la inserción de uno de los documentos, MongoDB devuelve el error sin procesar los documentos restantes de la matriz.
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, j: true, wtimeout: 5000 } } )
WriteResult
Cuando se pasa un solo documento, insert() devuelve un WriteResult() objeto.
Resultados exitosos
Con éxito, el objeto WriteResult devuelto contiene información sobre el número de documentos insertados:
WriteResult({ "nInserted" : 1 })
Errores de nivel de confirmación de escritura
Si 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 insert() encuentra un error 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().