Menu Docs

Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

db.collection.insertOne()

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamentos
  • Exemplos

Definição

db.collection.insertOne()

Importante

Método mongosh

Esta página documenta um método mongosh . Esta não é a documentação para comandos de banco de dados ou drivers específicos de idioma, como Node.js.

Para o comando do banco de dados, consulte o comando insert.

Para drivers de API do MongoDB, consulte a documentação do driver MongoDB específica do idioma.

Para a documentação de shell legada do mongo, consulte a documentação para a versão correspondente do MongoDB Server:

mongo shell v4.4

Insere um único documento em uma collection.

Retorna:Um documento contendo:

  • Um booleano acknowledged como true se a operação foi executada com write concern ou false se o write concern foi desativado.

  • Um campo insertedId com o valor _id do documento inserido.

Compatibilidade

Você pode utilizar o db.collection.insertOne() para implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

Sintaxe

O método insertOne() tem o seguinte formulário:

db.collection.insertOne(
    <document>,
    {
      writeConcern: <document>
    }
)

O método insertOne() utiliza os seguintes parâmetros:

Parâmetro
Tipo
Descrição
document
documento
Um documento para inserir na coleção.
writeConcern
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().

Tratamento de erros

Em caso de erro, db.collection.insertOne() lança uma exceção writeError ou writeConcernError .

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.

Dica

Veja também:

Crie coleções e índices em uma transação

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 Oplog

Se uma operação db.collection.insertOne() inserir com êxito um documento, a operação adicionará uma entrada no oplog (registro 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 seguinte, 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 seguinte, o documento passado para o método insertOne() inclui o campo _id . O valor de _id deve ser exclusivo dentro da collection 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"
     }
   }
})

Dica

Veja também:

← db.collection.insert()
db.collection.insertMany() →

Nesta página