insertOne() (Inserir um Único Documento)
Última atualização: 2026-10-09
insertOne() (Inserir um Único Documento)
insertOne() insere um único documento em uma coleção. Se o documento não tiver _id, o MongoDB gera um ObjectId automaticamente. O resultado inclui insertedId e acknowledged. É a forma mais direta de escrita de um único documento, ao custo de uma ida e volta (diferente de insertMany()).
| Categoria | Escrita |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.insertOne(<document>, { writeConcern: <options> })⚙️ Parâmetros
| documento | O documento BSON a inserir; pode conter campos e matrizes aninhados. |
|---|
Retorno：WriteResult: { acknowledged, insertedId }
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// insertOne: insere um único usuário
db.users.insertOne({
name: "Alice",
age: 21,
address: { city: "Beijing" }
})Saída：
{
acknowledged: true,
insertedId: ObjectId("64c8a1b2f3d4e5a6b7c8d9e0")
}📌 Notas
- ObjectId gerado automaticamente quando _id está ausente
- Limite de tamanho do documento: 16MB (BSON)
- _id duplicado lança DuplicateKeyError (índice único)
- O write concern padrão é acknowledged: true
🏷️ Tags Relacionados
💡 Casos Relacionados
Bancos de dados e coleções: gerenciamento de namespaces no MongoDB
Inserção de documentos: uma explicação detalhada sobre `insertOne` e `insertMany`
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO insertOne pode inserir um array?
ANão — o nível superior deve ser um documento (objeto). Arrays são aceitos como valores de campos dentro do documento.
QO que acontece se eu omitir _id no insertOne?
AO MongoDB gera automaticamente um ObjectId para _id. Você pode fornecer seu próprio _id, mas ele deve ser único na coleção, caso contrário um erro de chave duplicada é lançado.
QPosso especificar writeConcern com insertOne?
ASim, passe opções como { writeConcern: { w: 'majority' } } como segundo argumento para controlar o nível de reconhecimento; caso contrário, a configuração da coleção ou da sessão é aplicada.
