Substituir documentos

Visão geral

Neste guia, você pode aprender como usar o driver Node.js para executar uma operação de substituição em um documento em uma coleção MongoDB . Uma operação de substituição tem desempenho diferente de uma operação de atualização. Uma operação de atualização modifica somente os campos especificados em um documento de destino. Uma operação de substituição remove todos os campos do documento de destino e os substitui por novos.

Substituir um documento

Para executar uma operação de substituição, crie um documento de substituição que consista nos campos e valores que você deseja usar em sua operação de substituição . Os documentos de substituição usam o seguinte formato:

{
   <field>: {
      <value>
   },
   <field>: {
      ...
   }
}

Documentos de substituição são os documentos que você deseja substituir os documentos existentes que correspondem aos filtros de consulta.

Você pode especificar mais opções, como upsert, utilizando o parâmetro opcional options. Se você definir o campo de opção upsert como true, o método inserirá um novo documento se nenhum documento corresponder à query.

O método replaceOne() lança uma exceção se ocorrer um erro durante a execução. Por exemplo, se você especificar um valor que viole uma regra de índice única, o replaceOne() lançará um duplicate key error.

Observação

Se o aplicação exigir o documento após a atualização, use o método collection.findOneAndReplace(), que possui uma interface semelhante replaceOne() a. Você pode configurar findOneAndReplace() para gerar o documento correspondente original ou o documento de substituição.

Exemplo

Considere um documento na collection myDB.items com campos descrevendo um item para venda, seu preço e a quantidade disponível:

{
   _id: 501,
   item: "3-wick beeswax candle",
   price: 18.99,
   quantity: 10,
}

Suponha que você queira substituir esse documento por um que contenha a descrição de um item totalmente diferente. Sua operação de substituição pode ser semelhante à seguinte:

const myDB = client.db("myDB");
const myColl = myDB.collection("items");
const filter = { _id: 501 };
// replace the matched document with the replacement document
const replacementDocument = {
   item: "Vintage silver flatware set",
   price: 79.15,
   quantity: 1,
};
const result = await myColl.replaceOne(filter, replacementDocument);

O documento substituído contém o conteúdo do documento de substituição e o campo imutável _id da seguinte forma:

{
   _id: 501,
   item: "Vintage silver flatware set",
   price: 79.15,
   quantity: 1,
}

Se uma operação de substituição não corresponder a nenhum documento em uma coleção, ela não fará nenhuma alteração. As operações de substituição podem ser configuradas para executar um upsert que tenta realizar a substituição, mas se nenhum documento for correspondido, ele insere um novo documento com os campos e valores especificados.

Você não pode modificar o campo _id de um documento nem alterar um campo para um valor que viole uma restrição de índice única. Consulte o manual do MongoDB Server para obter mais informações sobre índices únicos.

replaceOne() 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 substituiçã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 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 a query for documents where the title contains "The Cat from"
16     const query = { title: { $regex: "The Cat from" } };
17     
18     // Create the document that will replace the existing document
19     const replacement = {
20       title: `The Cat from Sector ${Math.floor(Math.random() * 1000) + 1}`,
21     };
22 
23     // Execute the replace operation
24     const result = await movies.replaceOne(query, replacement);
25     
26     // Print the result 
27     console.log(`Modified ${result.modifiedCount} document(s)`);
28   } finally {
29     await client.close();
30   }
31 }
32 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 }
11 
12 async function run() {
13   try {
14     const database = client.db("sample_mflix");
15     const movies = database.collection<Movie>("movies");
16 
17     const result = await movies.replaceOne(
18       { title: { $regex: "The Cat from" } },
19       {
20         title: `The Cat from Sector ${Math.floor(Math.random() * 1000) + 1}`,
21       }
22     );
23     console.log(`Modified ${result.modifiedCount} document(s)`);
24   } finally {
25     await client.close();
26   }
27 }
28 run().catch(console.dir);

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

Modified 1 document(s)

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:

Voltar

Modificar documentos

Atualizar arrays

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 a query for documents where the title contains "The Cat from"
16	const query = { title: { $regex: "The Cat from" } };
17
18	// Create the document that will replace the existing document
19	const replacement = {
20	title: `The Cat from Sector ${Math.floor(Math.random() * 1000) + 1}`,
21	};
22
23	// Execute the replace operation
24	const result = await movies.replaceOne(query, replacement);
25
26	// Print the result
27	console.log(`Modified ${result.modifiedCount} document(s)`);
28	} finally {
29	await client.close();
30	}
31	}
32	run().catch(console.dir);