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.
Sintaxe
db.collection.insert() tem a seguinte sintaxe:
db.collection.insert( <document or array of documents>, { writeConcern: <document>, ordered: <boolean> } )
Parâmetros
Parâmetro | Tipo | Descrição |
|---|---|---|
| documento ou array | Um documento ou array de documentos para inserir na coleção. |
| documento | Opcional. Um documento que expressa a preocupação de gravação . Omita o uso do preocupação de gravação padrão. Consulte Write Concern. 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. |
| booleano | Opcional. Se Se Padrã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 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.
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 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 nesta página usam dados do conjunto de dados de amostra sample_mflix. Para obter detalhes sobre como carregar esse conjunto de dados em sua implantação autogerenciada do MongoDB , consulte Carregar o conjunto de dados de amostra. Se você fez modificações nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.
Inserir um documento sem especificar um campo _id
O exemplo a seguir insere um documento sem um campo _id na collection movies:
db.movies.insert( { title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] } )
{ acknowledged: true, insertedIds: { '0': "..." } }
Como o documento inserido não _id inclui, criamongod e _id adiciona o campo e atribui a ele um valor ObjectId() exclusivo.
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
O exemplo a seguir especifica o campo _id no documento inserido na coleção movies. O valor de _id deve ser exclusivo dentro da collection para evitar um erro de chave duplicada.
db.movies.insert( { _id: 10, title: "Inception", year: 2010 } )
{ acknowledged: true, insertedIds: { '0': 10 } }
Insira vários documentos
O exemplo a seguir executa uma inserção em massa passando uma array de documentos insert() para. 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.
O primeiro documento especifica um _id campo. Como o segundo e o terceiro documentos não contêm um _id campo, cria e adicionamongod o _id campo para esses documentos durante a inserção:
db.movies.insert( [ { _id: 11, title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] }, { title: "The Matrix", year: 1999 }, { title: "Interstellar", year: 2014 } ] )
{ acknowledged: true, insertedIds: { '0': 11, '1': "...", '2': "..." } }
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.movies.insert( [ { _id: 20, title: "2001: A Space Odyssey", year: 1968 }, { _id: 21, title: "A Clockwork Orange", year: 1971 }, { _id: 22, title: "The Shining", year: 1980 } ], { ordered: false } )
Substituir write concern padrão
A operação a seguir para um conjunto de réplicas especifica uma write concern 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.movies.insert( { title: "The Revenant", year: 2015 }, { writeConcern: { w: 2, j: true, wtimeout: 5000 } } )
WriteResult
Quando um único documento é passado, insert() retorna um objeto WriteResult().
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 write concern
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 write concern
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 }" } })
BulkWriteResult
Quando recebe uma array de documentos, insert() retorna um objeto BulkWriteResult().