Menu Docs

Atualize documentos

Neste guia, você pode aprender como atualizar documentos em uma coleção MongoDB . As operações de atualização especificam os campos e valores a serem alterados em um ou mais documentos. Eles aplicam alterações especificadas em um documento de atualização a um ou mais documentos que correspondem ao seu filtro de query.

Para saber como atualizar arrays incorporados ou atualizar ou inserir em uma única operação, consulte as seguintes páginas:

As operações de atualização podem modificar campos e valores:

  • O método updateOne() altera o primeiro documento ao qual seu filtro de query corresponde e o

  • O método updateMany() altera todos os documentos que seu filtro de query corresponde.

Você pode chamar os métodos updateOne() e updateMany() em uma instância do MongoCollection da seguinte forma:

collection.updateOne(<query>, <updateDocument>);
collection.updateMany(<query>, <updateDocument>);

Os métodos updateOne() e updateMany() têm os seguintes parâmetros:

  • query especifica um filtro de consulta com os critérios para corresponder aos documentos a serem atualizados em sua coleção.

  • update especifica os campos e valores a serem modificados no documento ou documentos correspondentes. Os exemplos nesta seção usam os Construtores de Atualizações para criar o documento de atualização.

  • (Opcional) updateOptions especifica opções que você pode definir para personalizar como o driver executa a operação de atualização. Para saber mais sobre esse tipo, consulte a documentação da API para UpdateOptions.

Você pode criar o updateDocument utilizando um construtor Updates como segue:

Bson update = Updates.operator(<field>, <value>);

Para visualizar uma lista completa de construtores de atualizações e seu uso,consulte Atualizações na documentação da API.

Nos exemplos a seguir, uma loja de tintas vende cinco cores diferentes de tinta. A coleção paint_inventory representa seu inventário atual:

{ "_id": 1, "color": "red", "qty": 5 }
{ "_id": 2, "color": "purple", "qty": 8 }
{ "_id": 3, "color": "yellow", "qty": 0 }
{ "_id": 4, "color": "green", "qty": 6 }
{ "_id": 5, "color": "pink", "qty": 0 }

O exemplo a seguir demonstra como alterar o valor do campo color no primeiro documento correspondente em que o valor de qty é 0:

Bson filter = Filters.eq("qty", 0);
Bson update = Updates.set("color", "dandelion");
// Updates first matching document
UpdateResult result = collection.updateOne(filter, update);

Se vários documentos corresponderem ao filtro de query especificado no método updateOne(), ele atualizará o primeiro resultado. Você pode especificar uma classificação em uma instância UpdateOptions para aplicar uma ordem aos documentos correspondentes antes que o servidor execute a operação de atualização, conforme mostrado no código a seguir:

UpdateOptions options = UpdateOptions.sort(ascending("color"));
UpdateResult result = collection.updateOne(filter, document, options);

A loja de tintas recebe uma nova remessa e precisa atualizar seu estoque. A remessa contém 20 latas de cada cor de tinta.

Para atualizar o inventário, chame o método updateMany() especificando o seguinte:

  • Filtro de query que corresponde a todas as cores

  • Atualizar documento que contém instruções para incrementar o campo qty até 20

Bson filter = Filters.empty();
Bson update = Updates.inc("qty", 20);
// Updates all documents and prints the number of matched and modified documents
UpdateResult result = collection.updateMany(filter, update);
System.out.println("Matched document count: " + result.getMatchedCount());
System.out.println("Modified document count: " + result.getModifiedCount());

A saída do código anterior se assemelha ao seguinte:

Matched document count: 5
Modified document count: 5

O seguinte mostra os documentos atualizados na coleção paint_inventory :

{ "_id": 1, "color": "red", "qty": 25 }
{ "_id": 2, "color": "purple", "qty": 28 }
{ "_id": 3, "color": "yellow", "qty": 20 }
{ "_id": 4, "color": "green", "qty": 26 }
{ "_id": 5, "color": "pink", "qty": 20 }

Se zero documentos corresponderem ao filtro de query na operação de atualização, updateMany() não fará alterações nos documentos na coleção. Consulte nosso guia upsert para saber como inserir um novo documento em vez de atualizar um se nenhum documento corresponder.

Importante

Os métodos updateOne() e updateMany() não podem fazer alterações em um documento que viole restrições de índice único na coleção. Para obter mais informações sobre restrições em índices únicos, consulte Índices únicos no manual do servidor MongoDB.

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 Como criar um MongoClient. 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 e uma operação de atualização muitos:

// Updates the first document that matches a query filter by using the Java driver
package org.example;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.UpdateOptions;
import com.mongodb.client.model.Updates;
import com.mongodb.client.result.UpdateResult;
import static com.mongodb.client.model.Filters.gt;
public class Update {
public static void main(String[] args) {
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
// Instructs the driver to insert a new document if none match the query
UpdateOptions options = new UpdateOptions().upsert(true);
Document updateOneQuery = new Document().append("title", "Cool Runnings 2");
// Creates instructions to update the values of three document fields
Bson updateOneUpdates = Updates.combine(
Updates.set("runtime", 99),
Updates.addToSet("genres", "Sports"),
Updates.currentTimestamp("lastUpdated"));
// Updates the first document that has a "title" value of "Cool Runnings 2"
UpdateResult result = collection.updateOne(updateOneQuery, updateOneUpdates, options);
// Prints the number of updated documents and the upserted document ID, if an upsert was performed
System.out.println("Number of documents updated - update one: " + result.getModifiedCount());
System.out.println("Upserted document ID: " + result.getUpsertedId());
Bson updateManyQuery = gt("num_mflix_comments", 50);
// Creates instructions to update the values of two document fields
Bson updateManyUpdates = Updates.combine(
Updates.addToSet("genres", "Frequently Discussed"),
Updates.currentTimestamp("lastUpdated"));
// Updates documents that have a "num_mflix_comments" value over 50
UpdateResult result = collection.updateMany(updateManyQuery, updateManyUpdates);
// Prints the number of updated documents
System.out.println("\nNumber of documents updated - update many: " + result.getModifiedCount());
}
}
}
updateOne() modified document count: 1
Upserted ID: null
updateMany() modified document count: 242

Uma operação de substituição substitui um documento da sua collection. A substituição ocorre entre um documento ao qual seu filtro de query corresponde e um documento de substituição.

O replaceOne() método remove todos os campos e valores existentes no documento correspondente (exceto o _id campo ) e o substitui pelo documento de substituição.

Você pode chamar o método replaceOne() em uma instância MongoCollection da seguinte forma:

collection.replaceOne(<query>, <replacement>);

O método replaceOne() tem os seguintes parâmetros:

  • query especifica um filtro de query com os critérios para corresponder a um documento a ser substituído em sua coleção.

  • replacement especifica campos e valores de um novo objeto Document para substituir o documento correspondente.

  • (Opcional) replaceOptions especifica opções que você pode definir para personalizar como o driver executa a operação de substituição. Para saber mais sobre esse tipo, consulte a documentação da API para ReplaceOptions.

A loja de tintas entende que deve atualizar seu estoque novamente. O que eles pensaram ser 20 latas de tinta laranja é, na verdade, 25 latas de tinta laranja.

Para atualizar o inventário, chame o método replaceOne() especificando o seguinte:

  • Um filtro de query que corresponda a documentos onde o color é "pink"

  • Um documento de substituição em que o color é "orange" e o qty é "25"

Bson filter = Filters.eq("color", "pink");
Document document = new Document("color", "orange").append("qty", 25);
// Replaces the first document that matches the filter with a new document
UpdateResult result = collection.replaceOne(filter, document);
// Prints the number of matched and modified documents
System.out.println("Matched document count: " + result.getMatchedCount());
System.out.println("Modified document count: " + result.getModifiedCount());

A saída do código anterior se assemelha ao seguinte:

Matched document count: 1
Modified document count: 1

A seguir, mostra o documento atualizado:

{ "_id": 5, "color": "orange", "qty": 25 }

Se vários documentos corresponderem ao filtro de query especificado no método replaceOne(), ele substituirá o primeiro resultado. Você pode especificar uma classificação em uma instância ReplaceOptions para aplicar uma ordem aos documentos correspondentes antes que o servidor execute a operação de substituição, conforme mostrado no código a seguir:

ReplaceOptions options = ReplaceOptions.sort(ascending("qty"));
UpdateResult result = collection.replaceOne(filter, document, options);

Se zero documentos corresponderem ao filtro de query na operação de substituição, replaceOne() não fará alterações nos documentos na coleção. Consulte nosso guia upsert para saber como inserir um novo documento em vez de substituir um se nenhum documento corresponder.

Importante

O método replaceOne() não pode fazer alterações em um documento que viole restrições de índice exclusivas na collection. Para obter mais informações sobre restrições em índices únicos, consulte Índices únicos no manual do MongoDB Server .

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 Como criar um MongoClient. 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 .

// Replaces the first document that matches a filter by using the Java driver
package org.example;
import static com.mongodb.client.model.Filters.eq;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.MongoException;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.ReplaceOptions;
import com.mongodb.client.result.UpdateResult;
public class ReplaceOne {
public static void main(String[] args) {
// Replace the uri string with your MongoDB deployment's connection string
String uri = "<connection string uri>";
try (MongoClient mongoClient = MongoClients.create(uri)) {
MongoDatabase database = mongoClient.getDatabase("sample_mflix");
MongoCollection<Document> collection = database.getCollection("movies");
Bson query = eq("title", "Music of the Heart");
// Creates a new document containing "title" and "fullplot" fields
Document replaceDocument = new Document().
append("title", "50 Violins").
append("fullplot", " A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music");
// Instructs the driver to insert a new document if none match the query
ReplaceOptions opts = new ReplaceOptions().upsert(true);
// Replaces the first document that matches the filter with a new document
UpdateResult result = collection.replaceOne(query, replaceDocument, opts);
// Prints the number of modified documents and the upserted document ID, if an upsert was performed
System.out.println("Modified document count: " + result.getModifiedCount());
System.out.println("Upserted id: " + result.getUpsertedId());
// Prints a message if any exceptions occur during the operation
} catch (MongoException me) {
System.err.println("Unable to replace due to an error: " + me);
}
}
}
Modified document count: 0
Upserted id: BsonObjectId{ ... }

Para obter mais informações sobre os métodos e as classes usadas nesta página, consulte a seguinte documentação da API: