Visão geral
Você pode modificar documentos em uma collection MongoDB usando as operações de atualização e substituição. As operações de atualização modificam os campos e valores de um documento, mantendo outros campos e valores inalterados. Substituir operações substitui todos os campos e valores em um documento existente por campos e valores especificados, mantendo o valor do campo _id
inalterado.
O driver do Node.js fornece os seguintes métodos para alterar documentos:
updateOne()
updateMany()
replaceOne()
Para saber como substituir documentos, consulte o guia Substituir documentos.
Dica
Laboratório interativo
Esta página inclui um breve laboratório interativo que demonstra como modificar dados usando o método updateMany()
. É possível 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.
Atualize documentos
Para executar uma atualização em um ou mais documentos, crie um documento de atualização que especifique o operador de atualização (o tipo de atualização a ser executada) e os campos e valores que descrevem a alteração. Atualize os documentos usando o seguinte formato:
{ <update operator>: { <field> : { ... }, <field> : { } }, <update operator>: { ... } }
O nível superior de um documento de atualização contém um ou mais dos seguintes operadores de atualização:
$set
: substitui o valor de um campo por um campo especificado$inc
: aumenta ou diminui os valores do campo$rename
: renomeia campos$unset
: remove campos$mul
: multiplica um valor de campo por um número especificado
Consulte o manual do MongoDB Server para obter umalista completa de operadores de atualização e seu uso.
Os operadores de atualização se aplicam apenas aos campos associados a eles em seu documento de atualização.
Observação
Pipelines de agregação em operações de atualização
Se você estiver usando o MongoDB versão 4.2 ou posterior, poderá usar aggregation pipelines compostos por um subconjunto de estágios de aggregation em operações de atualização. Para obter mais informações sobre os estágios de aggregation que têm suporte do MongoDB em aggregation pipelines usados em operações de atualização, consulte nosso tutorial sobre como criar atualizações com aggregation pipelines.
Exemplo
Considere um documento na collection myDB.items
com campos descrevendo um item para venda, seu preço e a quantidade disponível:
{ _id: 465, item: "Hand-thrown ceramic plate", price: 32.50, quantity: 7, }
Se você aplicar o operador de atualização $set
com um novo valor para quantity
, você poderá usar o seguinte documento de atualização:
const myDB = client.db("myDB"); const myColl = myDB.collection("items"); const filter = { _id: 465 }; // update the value of the 'quantity' field to 5 const updateDocument = { $set: { quantity: 5, }, }; const result = await myColl.updateOne(filter, updateDocument);
O documento atualizado se assemelha ao seguinte, com um valor atualizado no campo quantity
e todos os outros valores inalterados:
{ _id: 465, item: "Hand-thrown ceramic plate", price: 32.50, quantity: 5, }
Se uma operação de atualização não corresponder a nenhum documento em uma collection, ela não fará nenhuma alteração. As operações de atualização podem ser configuradas para executar um upsert que tenta realizar uma atualização, mas, se nenhum documento for correspondido, 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.
Exemplo do updateOne(): 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.
Este exemplo usa o operador de atualização $set
, que especifica valores de atualização para campos do documento . Para obter mais informações sobre operadores de atualização, consulte a documentação de referência do operador de atualização do MongoDB.
O código a seguir é um arquivo completo e autônomo que executa uma operação de atualização única:
1 // Update a document 2 3 import { MongoClient } from "mongodb"; 4 5 // Replace the uri string with your MongoDB deployment's connection string 6 const uri = "<connection string uri>"; 7 8 const client = new MongoClient(uri); 9 10 async function run() { 11 try { 12 const database = client.db("sample_mflix"); 13 const movies = database.collection("movies"); 14 15 // Create a filter for movies with the title "Random Harvest" 16 const filter = { title: "Random Harvest" }; 17 18 /* Set the upsert option to insert a document if no documents match 19 the filter */ 20 const options = { upsert: true }; 21 22 // Specify the update to set a value for the plot field 23 const updateDoc = { 24 $set: { 25 plot: `A harvest of random numbers, such as: ${Math.random()}` 26 }, 27 }; 28 29 // Update the first document that matches the filter 30 const result = await movies.updateOne(filter, updateDoc, options); 31 32 // Print the number of matching and modified documents 33 console.log( 34 `${result.matchedCount} document(s) matched the filter, updated ${result.modifiedCount} document(s)`, 35 ); 36 } finally { 37 // Close the connection after the operation completes 38 await client.close(); 39 } 40 } 41 // Run the program and print any thrown errors 42 run().catch(console.dir);
1 // Update a document 2 3 import { MongoClient } from "mongodb"; 4 5 // Replace the uri string with your MongoDB deployment's connection string 6 const uri = "<connection string uri>"; 7 8 const client = new MongoClient(uri); 9 10 // Define the Movie interface 11 interface Movie { 12 plot: string; 13 title: string; 14 } 15 16 async function run() { 17 try { 18 const database = client.db("sample_mflix"); 19 const movies = database.collection<Movie>("movies"); 20 21 /* Update a document that has the title "Random Harvest" to have a 22 plot field with the specified value */ 23 const result = await movies.updateOne( 24 { title: "Random Harvest" }, 25 { 26 $set: { 27 plot: `A harvest of random numbers, such as: ${Math.random()}`, 28 }, 29 }, 30 /* Set the upsert option to insert a document if no documents 31 match the filter */ 32 { upsert: true } 33 ); 34 35 // Print the number of matching and modified documents 36 console.log( 37 `${result.matchedCount} document(s) matched the filter, updated ${result.modifiedCount} document(s)` 38 ); 39 } finally { 40 // Close the connection after the operation completes 41 await client.close(); 42 } 43 } 44 // Run the program and print any thrown errors 45 run().catch(console.dir);
Ao executar o exemplo anterior, você verá a seguinte saída:
1 document(s) matched the filter, updated 1 document(s)
updateMany() 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 atualização de muitos:
1 /* Update multiple documents */ 2 3 import { MongoClient } from "mongodb"; 4 5 // Replace the uri string with your MongoDB deployment's connection string 6 const uri = "<connection string uri>"; 7 8 const client = new MongoClient(uri); 9 10 async function run() { 11 try { 12 // Get the "movies" collection in the "sample_mflix" database 13 const database = client.db("sample_mflix"); 14 const movies = database.collection("movies"); 15 16 // Create a filter to update all movies with a 'G' rating 17 const filter = { rated: "G" }; 18 19 // Create an update document specifying the change to make 20 const updateDoc = { 21 $set: { 22 random_review: `After viewing I am ${ 23 100 * Math.random() 24 }% more satisfied with life.`, 25 }, 26 }; 27 // Update the documents that match the specified filter 28 const result = await movies.updateMany(filter, updateDoc); 29 console.log(`Updated ${result.modifiedCount} documents`); 30 } finally { 31 // Close the database connection on completion or error 32 await client.close(); 33 } 34 } 35 run().catch(console.dir);
1 /* Update multiple documents */ 2 3 import { MongoClient } from "mongodb"; 4 5 // Replace the uri string with your MongoDB deployment's connection string. 6 const uri = "<connection string uri>"; 7 8 const client = new MongoClient(uri); 9 10 enum Rating { 11 G = "G", 12 PG = "PG", 13 PG_13 = "PG-13", 14 R = "R", 15 NR = "NOT RATED", 16 } 17 18 // Create a Movie interface 19 interface Movie { 20 rated: Rating; 21 random_review?: string; 22 } 23 24 async function run() { 25 try { 26 // Get the "movies" collection in the "sample_mflix" database 27 const database = client.db("sample_mflix"); 28 const movies = database.collection<Movie>("movies"); 29 30 // Update all documents that match the specified filter 31 const result = await movies.updateMany( 32 { rated: Rating.G }, 33 { 34 $set: { 35 random_review: `After viewing I am ${ 36 100 * Math.random() 37 }% more satisfied with life.`, 38 }, 39 } 40 ); 41 console.log(`Updated ${result.modifiedCount} documents`); 42 } finally { 43 // Close the database connection on completion or error 44 await client.close(); 45 } 46 } 47 run().catch(console.dir);
Executando o exemplo anterior, você visualiza uma saída como a seguinte:
Updated 477 documents
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: