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.

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

Consulte o manual do MongoDB Server para obter uma lista 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.

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 5const 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

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 de conexão. Este exemplo também usa a coleção movies no banco de dados sample_mflix incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados em um cluster gratuito no MongoDB Atlas seguindo o 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:

// Update a document import { MongoClient } from "mongodb"; // Replace the uri string with your MongoDB deployment's connection stringconst uri = "<connection string uri>"; const client = new MongoClient(uri); async function run() { try { const database = client.db("sample_mflix"); const movies = database.collection("movies"); // Create a filter for movies with the title "Random Harvest" const filter = { title: "Random Harvest" }; /* Set the upsert option to insert a document if no documents match the filter */ const options = { upsert: true }; // Specify the update to set a value for the plot field const updateDoc = { $set: { plot: `A harvest of random numbers, such as: ${Math.random()}` }, }; // Update the first document that matches the filter const result = await movies.updateOne(filter, updateDoc, options); // Print the number of matching and modified documents console.log( `${result.matchedCount} document(s) matched the filter, updated ${result.modifiedCount} document(s)`, ); } finally { // Close the connection after the operation completes await client.close(); }}// Run the program and print any thrown errorsrun().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

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 de conexão. Este exemplo também usa a coleção movies no banco de dados sample_mflix incluído nos conjuntos de dados de amostra do Atlas. Você pode carregá-los em seu banco de dados em um cluster gratuito no MongoDB Atlas seguindo o MongoDB Get Started.

O código a seguir é um arquivo completo e autônomo que executa uma operação de atualização de muitos:

/* Update multiple documents */ import { MongoClient } from "mongodb"; // Replace the uri string with your MongoDB deployment's connection stringconst uri = "<connection string uri>"; const client = new MongoClient(uri); async function run() { try { // Get the "movies" collection in the "sample_mflix" database const database = client.db("sample_mflix"); const movies = database.collection("movies"); // Create a filter to update all movies with a 'G' rating const filter = { rated: "G" }; // Create an update document specifying the change to make const updateDoc = { $set: { random_review: `After viewing I am ${ 100 * Math.random() }% more satisfied with life.`, }, }; // Update the documents that match the specified filter const result = await movies.updateMany(filter, updateDoc); console.log(`Updated ${result.modifiedCount} documents`); } finally { // Close the database connection on completion or error await client.close(); }}run().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: