/ /

Substituir documentos

Visão geral

Neste guia, você pode aprender como usar o driver Java Reactive Streams para substituir um documento em uma coleção MongoDB executando uma operação de substituição.

Uma operação de substituição substitui um documento em uma coleção MongoDB por novos campos e valores que você especifica. Você pode executar uma operação de substituição usando o método replaceOne() .

Dados de amostra

Os exemplos neste guia usam a sample_restaurants.restaurants coleção dos conjuntos de dados de amostra do Atlas .

Para saber como criar um cluster gratuito do MongoDB Atlas e carregar os conjuntos de dados de amostra, consulte o tutorial de Introdução .

Importante

Biblioteca do Reator do Projeto

Este guia usa a biblioteca Project Reactor para consumir instâncias do Publisher retornadas pelos métodos de driver Java Reactive Streams. Para saber mais sobre a biblioteca do Projeto Reactor e como usá-la, consulte Introdução na documentação do Reactor. Para saber mais sobre como usamos os métodos da biblioteca do Project Reactor neste guia, consulte o guia Gravar dados no MongoDB.

Operação de substituição

Você pode executar uma operação de substituição utilizando o método replaceOne() em uma instância do MongoCollection . Esse método remove todos os campos, exceto o campo _id do primeiro documento que corresponde aos critérios de pesquisa, depois adiciona os campos e valores especificados ao documento vazio.

Parâmetros necessários

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

documento defiltro de query , que determina quais documentos substituir. Para obter mais informações sobre filtros de query, consulte o guia Especificar uma query.
Substituir documento, que especifica os campos e valores a serem inseridos no novo documento.

Exemplo de substituição

Para substituir um único documento em uma coleção MongoDB , chame o método replaceOne() e passe o documento de filtro de query e o documento de substituição como parâmetros. Em seguida, passe o resultado replaceOne() para o método Mono.from() estático de Mono. Mono é uma classe da biblioteca do Project Reactor. No Java Reactive Streams, os métodos do driver retornam instâncias Publisher frios, o que significa que a operação correspondente não acontece a menos que você assine o Publisher retornado. Este guia usa a biblioteca do Project Reactor para consumi-los. Para saber mais sobre o Mono, consulte Mono na documentação do Projeto Reactor.

O exemplo a seguir usa o método replaceOne() para substituir os campos e valores de um documento por um valor de campo name de "Pizza Town". O método replaceOne() substitui o documento original por um documento que tenha um valor de campo name de "Mongo's Pizza" e um valor de campo cuisine de "Pizza".

 Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
         eq("name", "Pizza Town"),
         new Document().append("name", "Mongo's Pizza")
                 .append("cuisine", "Pizza"));
 Mono.from(replacePublisher).block();

Modificar comportamento de substituição

Opcionalmente, você pode modificar o comportamento do método replaceOne() chamando um método de opções. A classe ReplaceOptions fornece métodos que modificam o comportamento do método replaceOne() . Para usar a classe ReplaceOptions , construa uma nova instância da classe e, em seguida, chame um ou mais de seus métodos para modificar a operação de substituição. Você pode encadear essas chamadas de método. Para modificar o comportamento da operação de substituição, passe a instância de classe e as chamadas de método encadeadas como o último argumento para o método replaceOne() .

Você pode utilizar os seguintes métodos na classe ReplaceOptions para modificar o método replaceOne() .

Método	Descrição
`bypassDocumentValidation(Boolean bypass)`	Especifica se a operação de substituição ignora a validação do documento . Isso permite atualizar documentos que não atendam aos requisitos de validação de esquema , se houver. Para obter mais informações sobre validação de esquema, consulte Validação de esquema no manual do MongoDB Server .
`collation(Collation collation)`	Especifica o tipo de agrupamento de idiomas a ser usado ao classificar os resultados. Para obter mais informações, consulte Agrupamento no manual do MongoDB Server .
`comment(BsonValue comment)`	Anexa um comentário `BsonValue` à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .
`comment(String comment)`	Anexa um comentário `String` à operação. Para obter mais informações, consulte o guia de campos de comando de inserção no manual do MongoDB Server .
`hint(Bson hint)`	Define o índice para a operação como um valor `Bson`. Para obter mais informações, consulte a declaração de dica no manual do MongoDB Server .
`hintString(String hint)`	Define o índice para a operação como um valor `String`. Para obter mais informações, consulte a declaração de dica no manual do MongoDB Server .
`let(Bson variables)`	Especifica um mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento . Para obter mais informações, consulte a declaração let no manual do MongoDB Server .
`sort(Bson sort)`	Define os critérios de classificação a serem aplicados à operação. Se vários documentos corresponderem ao filtro de query que você passa para o método `replaceOne()`, a operação substituirá o primeiro resultado. Você pode definir essa opção como para aplicar um pedido a documentos correspondentes para ter mais controle sobre qual documento é substituído.
`upsert(Boolean upsert)`	Especifica se a operação de substituição executará uma operação de upsert se nenhum documento corresponder ao filtro de consulta. Para obter mais informações, consulte a declaração upsert no manual do MongoDB Server .

Exemplo de modificação de substituição

O seguinte código utiliza o método replaceOne() para substituir um documento na coleção restaurants . Ele também define a opção upsert(true) para que o driver insira um novo documento se o filtro de query não corresponder a nenhum documento existente.

Publisher<UpdateResult> replacePublisher = restaurants.replaceOne(
        eq("name", "Food Town"),
        new Document().append("name", "Food World")
                .append("cuisine", "Mixed"),
        new ReplaceOptions().upsert(true));
Mono.from(replacePublisher).block();

Valor de retorno

O método replaceOne() retorna um objeto UpdateResult . Utilize os seguintes métodos do tipo UpdateResult para acessar as informações correspondentes:

Propriedade	Descrição
`getMatchedCount()`	O número de documentos que corresponderam ao filtro de query, independentemente de quantos foram substituídos.
`getModifiedCount()`	O número de documentos modificados pela operação de substituição. Se um documento substituído for idêntico ao original, ele não será incluído nesta contagem.
`getUpsertedId()`	A ID do documento inserido no banco de dados, se o driver tiver realizado um upsert. Se nenhum documento foi inserido, este valor é `null`.
`wasAcknowledged()`	Um reconhecimento da substituição.

Informações adicionais

Para obter exemplos de código executáveis de substituição de documentos pelo driver Java Reactive Streams, consulte o guia de operações CRUD .

Documentação da API

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

Voltar

Atualize documentos

Exclua documentos