/ /

Atualize documentos

Visão geral

Neste guia, você pode aprender como usar o driver Ruby para atualizar documentos em uma coleção MongoDB utilizando os métodos update_one e update_many.

Dados de amostra

Os exemplos neste guia usam a collection restaurants no banco de dados sample_restaurants dos conjuntos de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação Ruby, crie um objeto Mongo::Client que se conecte a um Atlas cluster e atribua os seguintes valores às suas variáveis database e collection:

database = client.use('sample_restaurants')
collection = database[:restaurants]

Para aprender a criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o Guia de Introdução do MongoDB.

Atualizar operações

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

update_one: Atualiza o primeiro documento que corresponde aos critérios de pesquisa
update_many: Atualiza todos os documentos que correspondem aos critérios de pesquisa

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

Filtro de query, que corresponde aos documentos que você deseja 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 e os campos e valores a serem atualizados. O operador de atualização especifica o tipo de atualização a ser executada. Para visualizar uma lista de operadores de atualização e saber mais sobre seus usos, consulte a página do guia Operadores de atualização de campo no manual do MongoDB Server .

Atualizar um exemplo de documento

O exemplo a seguir usa o método update_one para localizar o primeiro documento em que o valor do campo name é "Happy Garden". Em seguida, ele usa o operador $set para atualizar o valor do campo name para "Mountain House".

filter = { name: 'Happy Garden' }
update = { '$set' => { name: 'Mountain House' } }
single_result = collection.update_one(filter, update)
puts "#{single_result.modified_count} document(s) updated."

1 document(s) updated

Exemplo de atualização de muitos documentos

O exemplo seguinte utiliza o método update_many para atualizar todos os documentos onde o valor do campo name é "Starbucks". O documento de atualização usa o operador $rename para alterar o nome do campo address para location.

filter = { name: 'Starbucks' }
update = { '$rename' => { address: 'location' } }
many_result = collection.update_many(filter, update)
puts "#{many_result.modified_count} document(s) updated."

11 document(s) updated

Opção Upsert

O parâmetro upsert permite a você utilizar as operações update_one() e update_many() para executar uma operação condicional:

Se o documento especificado existir, o comando o atualizará.
Se o documento especificado não existir, o comando criará um novo documento com o parâmetro especificado.

Para obter mais informações, consulte a seção Exemplo de atualização de modificação ou a tabela de opções nesta página.

Personalizar a operação de atualização

Os métodos update_one e update_many aceitam opções para configurar a operação de atualização. Você pode passar essas opções individualmente como parâmetros ou pode criar um objeto Hash que contenha as opções e passar o objeto como um parâmetro. Se você não especificar nenhuma opção, o driver executará a operação de atualização com as configurações padrão.

A tabela a seguir descreve as opções que você pode usar para configurar a operação de atualização:

Opção	Descrição
`upsert`	Se a operação de atualização executará uma operação de upsert se nenhum documento corresponder ao filtro de query. Para obter mais informações, consulte a declaração upsert no manual do MongoDB Server . Padrão: `false`
`bypass_document_validation`	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 . Padrão: `false`
`collation`	Agrupamento de idiomas a ser usado ao classificar os resultados. Para obter mais informações, consulte Agrupamento no manual do MongoDB Server .
`array_filters`	Lista de filtros que você especifica para selecionar a quais elementos da array a atualização se aplica.
`hint`	Índice a ser usado ao combinar documentos. Para obter mais informações,consulte a declaração de dica no manual do MongoDB Server .
`let`	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 .

Exemplo de modificação de atualização

O exemplo utiliza o operador $equal para corresponder a documentos onde o valor do campo name é "Sunrise Pizzeria". Em seguida, ele usa o operador $set para definir o valor do campo borough no primeiro documento correspondente como "Queens" e o valor do campo cuisine como "Italian".

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

filter = { 'name' => 'Sunrise Pizzeria' }
update = { '$set' => { borough: 'Queens', cuisine: 'Italian' } }
upsert_result = collection.update_one(filter, update, upsert: true)
puts "#{upsert_result.modified_count} document(s) updated."

1 document(s) updated

Valor de retorno

Os métodos update_one e update_many retornam um objeto Result. Você pode acessar os seguintes métodos a partir de uma instância Result :

Método	Descrição
`matched_count`	Número de documentos que corresponderam ao filtro de query, independentemente de quantas atualizações foram realizadas.
`modified_count`	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.
`acknowledged?`	Retorna `true` se o servidor reconheceu o resultado.
`upserted_count`	Retorna o número de documentos que foram atualizados no banco de dados, se o driver executou um upsert.
`upserted_ids`	Retorna o valor de `_id` do documento que foi atualizado no banco de dados, se o driver executou um upsert.

Dica

Verifique o valor do método acknowledged? antes de tentar chamar qualquer outro método Result. Se o método acknowledged? retornar false, o driver lançará uma exceção InvalidOperation se você tentar chamar qualquer outro método no objeto Result. 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 Ruby, 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