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.
Exemplo
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 filtroeq
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 comotrue
. 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: