/ /

Atualize documentos

Visão geral

Neste guia, você pode aprender como usar o driver Kotlin Sync para atualizar documentos em uma coleção MongoDB usando os métodos updateOne() e updateMany() .

Dados de amostra

Os exemplos neste guia usam a sample_restaurants.restaurants coleção dos conjuntos de dados de amostra do Atlas . Para aprender a criar uma implantação gratuita do MongoDB e carregar os conjuntos de dados de amostra, consulte o guia Começar do MongoDB.

Os documentos nesta coleção são modelados pela seguinte classe de dados Kotlin :

data class Restaurant(
    val name: String,
    val borough: String,
    val cuisine: String,
    val address: Document
)

Atualizar operações

Você pode atualizar documentos no MongoDB com os seguintes métodos:

updateOne(), que atualiza o primeiro documento que corresponde aos critérios de pesquisa
updateMany(), que atualiza todos os documentos que correspondem aos critérios de pesquisa

Cada método de atualização exige os seguintes parâmetros:

Filtro de consulta, que corresponde a quais documentos atualizar. Para saber mais sobre filtros de query, consulte o guia Especificar uma query .
documento de atualização, que especifica o operador de atualização ou o tipo de atualização a ser executada e os campos e valores a serem atualizados. Para obter uma lista de operadores de atualização e seus usos, consulte a página do guia Operadores de atualização de campo no manual do MongoDB Server .

Atualizar um documento

O exemplo seguinte utiliza o método updateOne() para atualizar o valor name de um documento de "Happy Garden" para "Mountain House":

val filter = eq(Restaurant::name.name, "Happy Garden")
val update = set(Restaurant::name.name, "Mountain House")
val result = collection.updateOne(filter, update)

Atualizar muitos documentos

O exemplo a seguir usa o método updateMany() para atualizar todos os documentos nos quais o valor name é "Starbucks". A atualização renomeia o campo address para location.

val filter = eq(Restaurant::name.name, "Starbucks")
val update = rename(Restaurant::address.name, "location")
val result = collection.updateMany(filter, update)

Personalizar a operação de atualização

Os métodos updateOne() e updateMany() aceitam opcionalmente um parâmetro que define opções para configurar a operação de atualização. Se você não especificar nenhuma opção, o driver executará operações de atualização com as configurações padrão.

A tabela a seguir descreve os métodos de configuração que você pode usar para configurar uma instância UpdateOptions :

Propriedade	Descrição
`upsert()`	Especifica se a operação de atualizaçã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 . O padrão é `false`
`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 `updateOne()`, a operação atualizará o primeiro resultado. Você pode definir essa opção como para aplicar um pedido a documentos correspondentes para ter mais controle sobre qual documento é atualizado.
`bypassDocumentValidation()`	Especifica se a operação de atualizaçã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 . O padrão `false` é.
`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 .
`arrayFilters()`	Fornece uma lista de filtros que você especifica para selecionar a quais elementos da array a atualização se aplica.
`hint()`	Define o índice a ser usado na correspondência de documentos. Para obter mais informações, consulte a declaração de dica no manual do MongoDB Server .
`let()`	Fornece um mapa de nomes e valores de parâmetros para definir variáveis de nível superior para a operação. 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 .
`comment()`	Define um comentário a ser anexado à operação. Para obter mais informações, consulte o guia de campos de comando de atualização no manual do MongoDB Server para obter mais informações.

Exemplo de documentos upsert

O código a seguir usa o método updateOne() para corresponder a documentos nos quais o valor do campo name é "Sunrise Pizzeria". Em seguida, ele define o valor borough no primeiro documento correspondente como "Queens" e o valor cuisine como "Italian".

Como a opção upsert está definida como true, o driver insere um novo documento que tenha os campos e valores especificados no documento de atualização se o filtro de query não corresponder a nenhum documento existente.

val opts = UpdateOptions().upsert(true)
val filter = eq(Restaurant::name.name, "Sunrise Pizzeria")
val update = combine(
    set(Restaurant::borough.name, "Queens"),
    set(Restaurant::cuisine.name, "Italian")
)
collection.updateOne(filter, update, opts)

Valor de retorno

Os métodos updateOne() e updateMany() retornam um objeto UpdateResult . Você pode utilizar os seguintes métodos para acessar informações de uma instância do UpdateResult :

Propriedade	Descrição
`getMatchedCount()`	Retorna o número de documentos que corresponderam ao filtro de query, independentemente de quantas atualizações foram realizadas.
`getModifiedCount()`	Retorna o número de documentos modificados pela operação de atualização. Se um documento atualizado for idêntico ao original, ele não será incluído nesta contagem.
`wasAcknowledged()`	Retorna `true` se o servidor reconheceu o resultado.
`getUpsertedId()`	Retorna o valor de `_id` do documento que foi atualizado no banco de dados, se o driver executou um upsert.

Observação

Se o método wasAcknowledged() retornar false, a tentativa de acessar outras informações da instância UpdateResult resultará em uma exceção InvalidOperation . O driver não pode determinar esses valores se o servidor não reconhecer a operação de gravação.

Informações adicionais

Para exibir exemplos de código executáveis que demonstram como atualizar documentos usando o driver Kotlin Sync, consulte Inserir documentos.

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

Acessar dados de um cursor

Substituir documentos