Visão geral
Neste guia, você aprenderá como inserir documentos no MongoDB.
Você pode usar o MongoDB para recuperar, atualizar e excluir informações que já estão armazenadas no MongoDB. Para armazenar informações, use uma operação de inserção.
Uma operação de inserção insere um ou mais documentos em uma coleção MongoDB. O driver Node.js fornece os seguintes métodos para executar operações de inserção :
insertOne()
insertMany()
bulkWrite()
Dica
Laboratório interativo
Esta página inclui um breve laboratório interativo que demonstra como inserir dados usando o método insertOne()
. Você pode concluir este laboratório diretamente na janela do seu navegador sem instalar o MongoDB ou um editor de código.
Para iniciar o laboratório, clique no botão Open Interactive Tutorial na parte superior da página. Para expandir o laboratório para um formato de tela inteira, clique no botão de tela inteira (⛶) no canto superior direito do painel do laboratório.
As seções a seguir focam em insertOne()
e insertMany()
. Para obter um exemplo de como usar o método bulkWrite()
, consulte a seção bulkWrite() Exemplo: Arquivo completo do guia Operações em massa.
Uma observação sobre _id
Ao inserir um documento, o MongoDB impõe uma restrição nos seus documentos por padrão. Cada documento deve conter um campo _id
exclusivo.
Há duas maneiras de gerenciar este campo:
Você mesmo pode gerenciar esse campo, garantindo que cada valor usado seja exclusivo.
Você pode permitir que o driver gere automaticamente valores únicos de
ObjectId
com a fábrica de chaves primárias.
A menos que você tenha fornecido garantias sólidas de exclusividade, recomendamos que deixe o driver gerar automaticamente os valores de _id
.
Observação
Os valores _id
duplicados violam restrições de índice único, resultando em um WriteError
.
Para obter mais informações sobre _id
, consulte a entrada manual do servidor MongoDB em Índices únicos.
Inserir um único documento
Use o método insertOne()
quando quiser inserir um único documento.
Em uma inserção bem-sucedida, o método retorna uma instância do InsertOneResult
representando o _id
do novo documento.
Exemplo
O exemplo a seguir usa o método insertOne()
para inserir um novo documento na coleção myDB.pizzaMenu
:
const myDB = client.db("myDB"); const myColl = myDB.collection("pizzaMenu"); const doc = { name: "Neapolitan pizza", shape: "round" }; const result = await myColl.insertOne(doc); console.log( `A document was inserted with the _id: ${result.insertedId}`, );
Sua saída se assemelha ao seguinte texto:
A document was inserted with the _id: 60c79c0f4cc72b6bb31e3836
Para obter mais informações sobre as classes e métodos mencionados nesta seção, consulte os seguintes recursos:
Documentação da API sobre insertOne()
Documentação da API sobre InsertOneResult
Entrada manual do servidor em insertOne()
insertOne() Exemplo: arquivo completo
Observação
Exemplo de configuração
Esse exemplo se conecta a uma instância do MongoDB usando um URI de conexão. Para saber mais sobre como se conectar à sua instância do MongoDB, consulte o guia Conectar ao MongoDB. Este exemplo também utiliza a coleção do movies
no banco de dados do sample_mflix
incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados na camada grátis do MongoDB Atlas seguindo o Guia de Introdução ao Atlas.
O código a seguir é um arquivo completo e autônomo que executa uma operação de inserção :
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 // Create a new client and connect to MongoDB 7 const client = new MongoClient(uri); 8 9 async function run() { 10 try { 11 // Connect to the "sample_mflix" database and access its "movies" collection 12 const database = client.db("sample_mflix"); 13 const movies = database.collection("movies"); 14 15 // Create a document to insert 16 const doc = { 17 title: "Charade", 18 genres: ["Comedy", "Romance", "Thriller"], 19 year: 1963, 20 cast: ["Cary Grant", "Audrey Hepburn", "Walter Matthau"], 21 } 22 // Insert the defined document into the "movies" collection 23 const result = await movies.insertOne(doc); 24 25 // Print the ID of the inserted document 26 console.log(`A document was inserted with the _id: ${result.insertedId}`); 27 } finally { 28 // Close the MongoDB client connection 29 await client.close(); 30 } 31 } 32 // Run the function and handle any errors 33 run().catch(console.dir);
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 const client = new MongoClient(uri); 7 8 interface Movie { 9 title: string; 10 content: string[]; 11 year: number; 12 cast: string[]; 13 } 14 15 async function run() { 16 try { 17 const database = client.db("sample_mflix"); 18 // Specifying a Schema is optional, but it enables type hints on 19 // finds and inserts 20 const movies = database.collection<Movie>("movies"); 21 const result = await movies.insertOne({ 22 title: "Charade", 23 genres: ["Comedy", "Romance", "Thriller"], 24 year: 1963, 25 cast: ["Cary Grant", "Audrey Hepburn", "Walter Matthau"], 26 }); 27 console.log(`A document was inserted with the _id: ${result.insertedId}`); 28 } finally { 29 await client.close(); 30 } 31 } 32 run().catch(console.dir);
Ao executar o exemplo anterior, você verá a seguinte saída:
A document was inserted with the _id: ...
Insira vários documentos
Use o método insertMany()
quando quiser inserir vários documentos. Este método insere documentos na ordem especificada até ocorrer uma exceção, se houver.
Por exemplo, suponha que você queira inserir os seguintes documentos:
{ "_id": 1, "color": "red" } { "_id": 2, "color": "purple" } { "_id": 1, "color": "yellow" } { "_id": 3, "color": "blue" }
Se você tentar inserir esses documentos, um WriteError
ocorrerá quando o terceiro documento for processado, mas os documentos anteriores ao erro serão inseridos em sua coleção.
Observação
Use um bloco try-catch para obter uma confirmação de documentos processados com êxito antes que o erro ocorra:
const myDB = client.db("myDB"); const myColl = myDB.collection("colors"); try { const docs = [ { "_id": 1, "color": "red"}, { "_id": 2, "color": "purple"}, { "_id": 1, "color": "yellow"}, { "_id": 3, "color": "blue"} ]; const insertManyresult = await myColl.insertMany(docs); let ids = insertManyresult.insertedIds; console.log(`${insertManyresult.insertedCount} documents were inserted.`); for (let id of Object.values(ids)) { console.log(`Inserted a document with id ${id}`); } } catch(e) { console.log(`A MongoBulkWriteException occurred, but there are successfully processed documents.`); let ids = e.result.result.insertedIds; for (let id of Object.values(ids)) { console.log(`Processed a document with id ${id._id}`); } console.log(`Number of documents inserted: ${e.result.result.nInserted}`); }
A saída consiste em documentos que o MongoDB pode processar e é semelhante à seguinte:
A MongoBulkWriteException occurred, but there are successfully processed documents. Processed a document with id 1 Processed a document with id 2 Processed a document with id 1 Processed a document with id 3 Number of documents inserted: 2
Dentro da sua collection, verá os seguintes documentos:
{ "_id": 1, "color": "red" } { "_id": 2, "color": "purple" }
Ao fazer a inserção corretamente, o método gera uma instância InsertManyResult
representando o número de documentos inseridos e o _id
do novo documento.
Exemplo
O exemplo a seguir usa o método insertMany()
para inserir três novos documentos na collection myDB.pizzaMenu
:
const myDB = client.db("myDB"); const myColl = myDB.collection("pizzaMenu"); const docs = [ { name: "Sicilian pizza", shape: "square" }, { name: "New York pizza", shape: "round" }, { name: "Grandma pizza", shape: "square" } ]; const insertManyresult = await myColl.insertMany(docs); let ids = insertManyresult.insertedIds; console.log(`${insertManyresult.insertedCount} documents were inserted.`); for (let id of Object.values(ids)) { console.log(`Inserted a document with id ${id}`); }
Seu resultado parece semelhante ao seguinte:
3 documents were inserted. Inserted a document with id 60ca09f4a40cf1d1afcd93a2 Inserted a document with id 60ca09f4a40cf1d1afcd93a3 Inserted a document with id 60ca09f4a40cf1d1afcd93a4
Para obter mais informações sobre as classes e métodos mencionados nesta seção, consulte os seguintes recursos:
Documentação da API do insertMany()
Documentação da API sobrem InsertManyResult
Documentação da API sobre PkFactory
Entrada manual do servidor em insertMany()
insertMany() Exemplo: arquivo completo
Observação
Exemplo de configuração
Esse exemplo se conecta a uma instância do MongoDB usando um URI de conexão. Para saber mais sobre como se conectar à sua instância do MongoDB, consulte o guia Conectar ao MongoDB. Este exemplo também utiliza a coleção do movies
no banco de dados do sample_mflix
incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados na camada grátis do MongoDB Atlas seguindo o Guia de Introdução ao Atlas.
O código a seguir é um arquivo completo e autônomo que executa uma operação de inserção muitos:
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 const client = new MongoClient(uri); 7 8 async function run() { 9 try { 10 11 // Get the database and collection on which to run the operation 12 const database = client.db("sample_mflix"); 13 const movies = database.collection("movies"); 14 15 // Create an array of documents to insert 16 const moviesToInsert = [ 17 { title: "Arsenic and Old Lace", genres: ["Comedy", "Romance"], year: 1944, cast: ["Cary Grant", "Priscilla Lane", "Raymond Massey"] }, 18 { title: "Ball of Fire", genres: ["Comedy", "Romance"], year: 1941, cast: ["Gary Cooper", "Barbara Stanwyck", "Oskar Homolka"] }, 19 { title: "I Married a Witch", genres: ["Comedy", "Fantasy", "Romance"], year: 1942, cast: ["Veronica Lake", "Fredric March", "Susan Hayward"] }, 20 ]; 21 22 // Prevent additional documents from being inserted if one fails 23 const options = { ordered: true }; 24 25 // Execute insert operation 26 const result = await movies.insertMany(moviesToInsert, options); 27 28 // Print result 29 console.log(`${result.insertedCount} documents were inserted`); 30 } finally { 31 await client.close(); 32 } 33 } 34 run().catch(console.dir);
1 import { MongoClient } from "mongodb"; 2 3 // Replace the uri string with your MongoDB deployment's connection string. 4 const uri = "<connection string uri>"; 5 6 const client = new MongoClient(uri); 7 8 interface Movie { 9 title: string; 10 genres: string[]; 11 year: number; 12 cast: string[]; 13 } 14 15 async function run() { 16 try { 17 const database = client.db("sample_mflix"); 18 // Specifying a schema is optional, but it enables type hints on 19 // finds and inserts 20 const movies = database.collection<Movie>("movies"); 21 22 const result = await movies.insertMany( 23 { title: "Arsenic and Old Lace", genres: ["Comedy", "Romance"], year: 1944, cast: ["Cary Grant", "Priscilla Lane", "Raymond Massey"] }, 24 { title: "Ball of Fire", genres: ["Comedy", "Romance"], year: 1941, cast: ["Gary Cooper", "Barbara Stanwyck", "Oskar Homolka"] }, 25 { title: "I Married a Witch", genres: ["Comedy", "Fantasy", "Romance"], year: 1942, cast: ["Veronica Lake", "Fredric March", "Susan Hayward"] }, 26 { ordered: true } 27 ); 28 console.log(`${result.insertedCount} documents were inserted`); 29 } finally { 30 await client.close(); 31 } 32 } 33 run().catch(console.dir);
Ao executar o exemplo anterior, você verá a seguinte saída:
3 documents were inserted
Documentação da API
Para saber mais sobre qualquer um dos tipos ou métodos discutidos neste guia, consulte a seguinte documentação da API: