db.collection.insertOne() (método mongosh)

MongoDB com drivers

Esta página documenta um método mongosh. Para ver o método equivalente em um driver do MongoDB, consulte a página correspondente da sua linguagem de programação:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definição

db.collection.insertOne()

Insere um único documento em uma collection.

Retorna:

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.

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

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Observação

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

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
`document`	documento	Um documento para inserir na coleção.
`writeConcern`	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

Os exemplos nesta página usam dados do conjunto de dados sample_mflix. Para obter detalhes sobre como carregar este conjunto de dados em sua implantação do MongoDB autogerenciado, consulte Carregar o conjunto de dados de amostra. Se você fez alguma modificação 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 coleção movies:

db.movies.insertOne( { title: "Inception", year: 2010, genres: [ "Action", "Sci-Fi" ] } )

{
  acknowledged: true,
  insertedId: "..."
}

Como o documento não inclui _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`

Quando você especifica _id ao inserir um documento, o valor _id deve ser exclusivo na coleção. O exemplo a seguir insere um documento na coleção movies e especifica _id:

db.movies.insertOne( { _id: 10, title: "Inception", year: 2010 } )

{ 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. A opção a seguir tenta inserir um documento com um valor _id que já existe:

try {
   db.movies.insertOne( { _id: 10, title: "Inception", year: 2010 } );
} 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: sample_mflix.movies index: _id_ dup key: { : 10.0 }",
   "op" : {
      "_id" : 10,
      "title" : "Inception",
      "year" : 2010
   }
})

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.movies.insertOne(
       { title: "Arrival", year: 2016 },
       { 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"
     }
   }
})

Voltar

db.collection.insertMany

db.collection.isCapped