db.collection.insertOne()
MongoDB com drivers
Esta página documenta um método. Para ver o método equivalente em um driver MongoDB , consulte a página correspondente para sua linguagem de mongosh programação:
Definição
db.collection.insertOne()Insere um único documento em uma collection.
Retorna: Um documento contendo: Um booleano
acknowledgedcomotruese a operação foi executada com preocupação de gravação,ou sea preocupação de gravaçãofalsefoi desativada.Um campo
insertedIdcom o valor_iddo documento inserido.
Compatibilidade
Esse método está disponível em implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
Observação
Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.
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 insertOne() tem o seguinte formato:
db.collection.insertOne( <document>, { writeConcern: <document> } )
O método insertOne() utiliza os seguintes parâmetros:
Parâmetro | Tipo | Descrição |
|---|---|---|
| documento | Um documento para inserir na coleção. |
| documento | Opcional. Um documento expressando o write concern. Omita para usar o write concern padrão. .. include:: /includes/extracts/transactions-operations-write-concern.rst |
Comportamentos
Criação de collections
Se a coleção não existir, o método insertOne() criará a coleção.
_id Campo
Se o documento não especificar um campo _id, o mongod adicionará o campo _id e atribuirá um ObjectId() único 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 aplicativo não fizer isso.
Se o documento contiver um campo _id, o valor _id deverá ser único dentro da collection para evitar erro de chave duplicada.
Explicabilidade
insertOne() não é compatível com db.collection.explain().
Error Handling
Em caso de erro, db.collection.insertOne() lança uma exceção writeError ou writeConcernError.
Erros de validação de esquema
Se sua coleção usar validação de esquema e tiver validationAction definido como error, a inserção de um documento inválido gerará um MongoServerError e db.collection.insertOne() falhará.
Transações
db.collection.insertOne() 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.insertOne() 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
Inserir um documento sem especificar um campo _id
No exemplo a seguir, o documento passado para o método insertOne() não contém o campo _id:
try { db.products.insertOne( { item: "card", qty: 15 } ); } catch (e) { print (e); };
A operação retorna o seguinte documento:
{ "acknowledged" : true, "insertedId" : ObjectId("56fc40f9d735c28df206d078") }
Como os documentos não incluíam _id, o mongod cria e adiciona o campo _id e atribui a ele um valor ObjectId() único.
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 o método insertOne() contém o campo _id. O valor de _id deve ser exclusivo dentro da coleção para evitar erro de chave duplicada.
try { db.products.insertOne( { _id: 10, item: "box", qty: 20 } ); } catch (e) { print (e); }
A operação retorna o seguinte:
{ "acknowledged" : true, "insertedId" : 10 }
A inserção de um valor duplicado para qualquer chave que faça parte de um índice único, como _id, gera uma exceção. As seguintes tentativas de inserir um documento com um valor _id que já existe:
try { db.products.insertOne( { _id: 10, "item" : "packing peanuts", "qty" : 200 } ); } catch (e) { print (e); }
Como _id: 10 já existe, a seguinte exceção é gerada:
WriteError({ "index" : 0, "code" : 11000, "errmsg" : "E11000 duplicate key error collection: inventory.products index: _id_ dup key: { : 10.0 }", "op" : { "_id" : 10, "item" : "packing peanuts", "qty" : 200 } })
Aumentar o write concern
Dado um conjunto de réplicas de três nós, a operação a seguir especifica um w de majority, wtimeout de 100:
try { db.products.insertOne( { "item": "envelopes", "qty": 100, type: "Self-Sealing" }, { writeConcern: { w : "majority", wtimeout : 100 } } ); } catch (e) { print (e); }
Se a confirmação demorar mais que o limite wtimeout, a seguinte exceção será lançada:
WriteConcernError({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } } })