MongoDB com drivers
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 write concern oufalsese o write concern foi desativado.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
db.collection.insertOne() tem o seguinte formato:
db.collection.insertOne( <document>, { writeConcern: <document> })Parâmetros
insertOne() recebe os seguintes parâmetros:
Parâmetro | Tipo | Descrição |
|---|---|---|
| documento | Um documento para inserir na coleção. |
| documento | Opcional. Um documento que expressa o write concern. Omitir para usar o write concern padrã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. |
Comportamentos
Criação de coleção e campo _id
Se a coleção não existir, então insertOne() 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.
Explicabilidade
insertOne() não é compatível db.collection.explain() com.
Error Handling
Em caso de erro, o sistema 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 insertOne() falhará.
Transações
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 índices dentro de uma transação distribuída se a transação não for uma transação de gravação cross-fragmento.
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 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 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 insertOne() inclui o campo _id. O valor de _id deve ser único 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 exceção será lançada:
WriteConcernError({ "code" : 64, "errmsg" : "waiting for replication timed out", "errInfo" : { "wtimeout" : true, "writeConcern" : { "w" : "majority", "wtimeout" : 100, "provenance" : "getLastErrorDefaults" } }})