db.collection.insert()
Importante
Método de mongosh obsoleto
Esse método está obsoleto em mongosh. Para obter métodos alternativos, consulte Alterações de compatibilidade com o shell mongo legado.
Definição
db.collection.insert()Insere um documento ou documentos em uma collection.
Retorna: Um objeto WriteResult para inserções únicas.
Um objeto BulkWriteResult para inserções em massa.
Compatibilidade
Você pode utilizar o db.collection.Insert() para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
O método insert() tem a seguinte sintaxe:
db.collection.insert( <document or array of documents>, { writeConcern: <document>, ordered: <boolean> } )
Parâmetro | Tipo | Descrição |
|---|---|---|
document | documento ou array | Um documento ou array de documentos para inserir na coleção. |
writeConcern | documento | Opcional. Um documento expressando a preocupação de gravação. Omita o uso da preocupação de gravação padrão. Consulte Preocupação de gravação. Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern. |
ordered | booleano | Opcional. Se Se Padrão é |
O insert() retorna um objeto contendo o status da operação.
Comportamentos
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 preocupação de gravação no parâmetro de opções.
criar coleta
Se a coleção não existir, o método insert() criará a coleção.
_id Campo
Se o documento não especificar um campo _id, o MongoDB adicionará o campo _id e atribuirá um ObjectId() exclusivo para o documento antes de inserir. A maioria dos drivers cria um ObjectId e insere o campo _id, mas o mongod criará e preencherá o _id se o driver ou o aplicativo não o fizer.
Se o documento contiver um campo _id, o valor _id deverá ser único dentro da collection para evitar erro de chave duplicada.
Transações
db.collection.insert() pode ser usado dentro de transações distribuídas.
Importante
Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.
Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.
Criação de collections em transações
Você pode criar coleção e indexes dentro de uma transaction distribuída se a transaction não for uma transação de escrita de estilhaço cruzado.
Se você especificar uma inserção em uma collection não existente em uma transação, o MongoDB criará a collection implicitamente.
Write concerns e transações
Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.
Entradas de oplog
Se uma operação db.collection.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.
Exemplos
Os exemplos a seguir inserem documentos na coleção products. Se a coleção não existir, o método insert() criará a coleção.
Inserir um documento sem especificar um _id campo
No exemplo a seguir, o documento passado para o método 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 _id campo
No exemplo a seguir, o documento passado para o método insert() contém o campo _id. O valor de _id deve ser exclusivo 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 um array de documentos para o método 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 no 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, wtimeout: 5000 } } )
WriteResult
Quando passado um único documento, insert() retorna um objeto WriteResult.
Resultados bem-sucedidos
O insert() retorna um objeto WriteResult() que contém o status da operação. Após o sucesso, o objeto WriteResult() contém informações sobre o número de documentos inseridos:
WriteResult({ "nInserted" : 1 })
Erros de preocupação de gravação
Se o método 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 o método insert() encontrar um erro que não seja 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 }" } })
BulkWriteResult
Quando recebe um array de documentos, insert() retorna um objeto BulkWriteResult(). Consulte BulkWriteResult() para obter detalhes.