db.collection.insert() (método mongosh)

Parâmetros

Escreva preocupação

O método insert() usa o comando insert, que usa a preocupação de gravação padrão. Para especificar uma preocupação de gravação diferente, inclua-a no parâmetro de opções.

Criação de coleção e campo _id

Se a coleção não existir, então insert() cria a coleção.

Se o documento a ser inserido não especificar um campo _id, então mongod adicionará o campo _id e atribuirá um ObjectId() exclusivo para o documento. A maioria dos drivers cria um ObjectId e insere o campo _id, mas o mongod criará e preencherá o _id se o driver ou aplicativo não.

Se o documento contiver um campo _id, o valor _id deverá ser único dentro da collection para evitar erro de chave duplicada.

Transações

insert() pode ser usado dentro de transações distribuídas.

Entradas de oplog

Se uma operação insert() inserir um documento com sucesso, a operação adicionará uma entrada no oplog (log de operações). Se a operação falhar, ela não adicionará uma entrada no oplog.

Inserir um documento sem especificar um campo _id

No exemplo a seguir, o documento passado para insert() não contém o campo _id:

db.products.insert( { item: "card", qty: 15 } )

Durante a inserção, mongod criará o campo _id e atribuirá a ele um valor ObjectId() exclusivo, conforme verificado pelo documento inserido:

{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }

Os valores ObjectId são específicos da máquina e do momento em que a operação é executada. Dessa forma, seus valores podem ser diferentes dos do exemplo.

Inserir um documento especificando um campo _id

No exemplo a seguir, o documento passado para insert() inclui o campo _id. O valor de _id deve ser único dentro da coleção para evitar erro de chave duplicada.

db.products.insert( { _id: 10, item: "box", qty: 20 } )

A operação insere o seguinte documento na coleção products:

{ "_id" : 10, "item" : "box", "qty" : 20 }

Insira vários documentos

O exemplo a seguir executa uma inserção em massa de três documentos passando uma array de documentos para insert(). Por padrão, o MongoDB executa uma inserção ordenada. Com inserções ordenadas, se ocorrer um erro durante a inserção de um dos documentos, o MongoDB retornará o erro sem processar os documentos restantes na array.

Os documentos na array não precisam ter os mesmos campos. Por exemplo, o primeiro documento na array tem um campo _id e um campo type. Como o segundo e o terceiro documentos não contêm um campo _id, mongod criará o campo _id para o segundo e o terceiro documentos durante a inserção:

db.products.insert(
   [
     { _id: 11, item: "pencil", qty: 50, type: "no.2" },
     { item: "pen", qty: 20 },
     { item: "eraser", qty: 25 }
   ]
)

A operação inseriu os seguintes três documentos:

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a0"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("51e0373c6f35bd826f47e9a1"), "item" : "eraser", "qty" : 25 }

Executar uma Inserção Não Ordenada

O exemplo a seguir executa uma inserção não ordenada de três documentos. Com inserções não ordenadas, se ocorrer um erro durante a inserção de um dos documentos, o MongoDB continuará a inserir os documentos restantes na array.

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

Substituir preocupação de gravação padrão

A operação a seguir para um conjunto de réplicas especifica uma preocupação de gravação de w: 2 com uma wtimeout de 5000 milissegundos. Essa operação retorna depois que a gravação se propaga para o primário e um secundário ou expira após 5 segundos.

db.products.insert(
    { item: "envelopes", qty : 100, type: "Clasp" },
    { writeConcern: { w: 2, j: true, wtimeout: 5000 } }
)

Resultados bem-sucedidos

Em caso de sucesso, o objeto WriteResult retornado contém informações sobre o número de documentos inseridos:

WriteResult({ "nInserted" : 1 })

Erros de preocupação de gravação

Se insert() encontrar erros de preocupação de gravação, os resultados incluirão o 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"
       }
     }
})

Erros não relacionados a preocupação de gravação

Se insert() encontrar um erro que não seja de preocupação de gravação, os resultados incluirão o 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 }"
   }
})