Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

Modificar documentos

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 de 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.

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

See the MongoDB Server manual for a complete list of update operators and their usage.

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 pipelines de agregação compostos por um subconjunto de estágios de agregação em operações de atualização. Para obter mais informações sobre os estágios de agregação que têm suporte do MongoDB em pipelines de agregação usados em operações de atualização, consulte nosso tutorial sobre como criar atualizações com pipelines de agregação.

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.

Observação

Exemplo de configuração

This example connects to an instance of MongoDB by using a connection URI. To learn more about connecting to your MongoDB instance, see the Connect to MongoDB guide. This example also uses the movies collection in the sample_mflix database included in the Atlas sample datasets. You can load them into your database on a free cluster in MongoDB Atlas following the MongoDB Get Started.

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
3import { MongoClient } from "mongodb";
4
5// Replace the uri string with your MongoDB deployment's connection string
6const uri = "<connection string uri>";
7
8const client = new MongoClient(uri);
9
10async 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
42run().catch(console.dir);

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

1 document(s) matched the filter, updated 1 document(s)

Observação

Exemplo de configuração

This example connects to an instance of MongoDB by using a connection URI. To learn more about connecting to your MongoDB instance, see the Connect to MongoDB guide. This example also uses the movies collection in the sample_mflix database included in the Atlas sample datasets. You can load them into your database on a free cluster in MongoDB Atlas following the MongoDB Get Started.

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
3import { MongoClient } from "mongodb";
4
5// Replace the uri string with your MongoDB deployment's connection string
6const uri = "<connection string uri>";
7
8const client = new MongoClient(uri);
9
10async 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}
35run().catch(console.dir);

Executando o exemplo anterior, você visualiza uma saída como a seguinte:

Updated 477 documents

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