Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Atualize documentos

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() .

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)

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 .

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)

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)

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 atualizar executa uma operação upsert se nenhum documento corresponder ao filtro de queries. 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 algum. Para obter mais informações sobre a 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.

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)

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.

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

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