Menu Docs
Página inicial do Docs
/ / /
Driver de sincronização Java
/ /

Substituir um documento

Você pode substituir um único documento usando o método replaceOne() em um objeto MongoCollection . Esse método remove todos os campos e valores existentes de um documento (exceto o campo _id ) e o substitui pelo documento de substituição.

O método replaceOne() aceita um filtro de query que corresponde ao documento que você deseja substituir e um documento de substituição que contém os dados que você deseja salvar no lugar do documento correspondente. O método replaceOne() substitui somente o primeiro documento que corresponde ao filtro.

Opcionalmente, você pode passar uma instância de ReplaceOptions para o método replaceOne() para especificar o comportamento do método. Por exemplo, se você definir o upsert campo do ReplaceOptions objeto como true, a operação inserirá um novo documento dos campos no documento de substituição se nenhum documento corresponder ao filtro de query. Consulte o link para a documentação da API de ReplaceOptions na parte inferior desta página para obter mais informações.

Após a execução bem-sucedida, o método replaceOne() gera uma instância de UpdateResult. Você pode recuperar informações, como o número de documentos modificados, chamando o método getModifiedCount() . Você também pode recuperar o valor do campo _id do documento chamando o método getUpsertedId() se tiver definido upsert(true) na instância ReplaceOptions e a operação tiver resultado na inserção de um novo documento.

Se a sua operação de substituição falhar, o driver emitirá uma exceção. Por exemplo, se você tentar especificar um valor para o campo imutável _id em seu documento de substituição que difere do documento original, o método lançará um MongoWriteException com a mensagem:

After applying the update, the (immutable) field '_id' was found to have been altered to _id: ObjectId('...)

Se o seu documento de substituição contiver uma alteração que viole as regras do índice único, o método lançará um MongoWriteException com uma mensagem de erro semelhante à seguinte:

E11000 duplicate key error collection: ...

Para obter mais informações sobre os tipos de exceções geradas em condições específicas, consulte a documentação da API para replaceOne(), cujo link está no final desta página.

Neste exemplo, substituímos a primeira correspondência de nossa query na collection movies do reconhecimento de data center sample_mflix por um documento de substituição. Todos os campos, exceto o campo _id , são excluídos do documento original e substituídos pelo documento de substituição.

Antes da operação replaceOne() ser executada, o documento original contém vários campos que descrevem o filme. Após a operação ser executada, o documento resultante conterá somente os campos especificados pelo documento de substituição (title e fullplot) e o campo _id .

O seguinte trecho utiliza os seguintes objetos e métodos:

  • Um filtro de query que é passado para o método replaceOne(). O filtro eq corresponde apenas a filmes com o título que corresponde exatamente ao texto 'Music of the Heart'.

  • Um documento de substituição que contém o documento que substitui o documento correspondente, se ele existir.

  • Um objeto ReplaceOptions com a opção upsert definida como true. Esta opção especifica que o método deve inserir os dados contidos no documento de substituição se o filtro de query não corresponder a nenhum documento.

Observaçã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 oguia de conexão .

// Replaces the first document that matches a filter by using the Java driver
package usage.examples;
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);
}
}
}

Depois de executar o exemplo, você verá um resultado parecido com este:

Modified document count: 1
Upserted id: null

Ou se o exemplo resultou em um upsert:

Modified document count: 0
Upserted id: BsonObjectId{value=...}

Se você fizer uma query no documento substituído, a saída será semelhante à seguinte:

Document {
{ _id=...,
title=50 Violins,
fullplot=A dramatization of the true story of Roberta Guaspari who co-founded the Opus 118 Harlem School of Music
}
}

Dica

Legacy API

Se você estiver usando a API herdada, consulte nossa página de perguntas frequentes para saber quais alterações devem ser feitas nesse exemplo de código.

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

  • replaceOne

  • ReplaceOptions

  • UpdateResult

  • eq()

Voltar

Atualizar vários documentos