Menu Docs
Página inicial do Docs
/ / /
Controlador Node.js
/

Insira documentos

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.

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.

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.

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:

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 :

1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6// Create a new client and connect to MongoDB
7const client = new MongoClient(uri);
8
9async 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
33run().catch(console.dir);
1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6const client = new MongoClient(uri);
7
8interface Movie {
9 title: string;
10 content: string[];
11 year: number;
12 cast: string[];
13}
14
15async 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}
32run().catch(console.dir);

Ao executar o exemplo anterior, você verá a seguinte saída:

A document was inserted with the _id: ...

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.

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:

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:

1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6const client = new MongoClient(uri);
7
8async 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}
34run().catch(console.dir);
1import { MongoClient } from "mongodb";
2
3// Replace the uri string with your MongoDB deployment's connection string.
4const uri = "<connection string uri>";
5
6const client = new MongoClient(uri);
7
8interface Movie {
9 title: string;
10 genres: string[];
11 year: number;
12 cast: string[];
13}
14
15async 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}
33run().catch(console.dir);

Ao executar o exemplo anterior, você verá a seguinte saída:

3 documents were inserted

Para saber mais sobre qualquer um dos tipos ou métodos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Operações CRUD

Nesta página