/ /

Operações de gravação em massa

Visão geral

Neste guia, você pode aprender como usar o driver Ruby para executar uma operação de gravação em massa que faz várias alterações em seus dados em uma única chamada de banco de dados .

Considere uma situação que exige que você insira documentos, atualize documentos e exclua documentos para a mesma tarefa. Se você usar os métodos de gravação individuais, cada operação de gravação acessará o banco de dados separadamente. Em vez disso, você pode usar uma operação de gravação em massa para otimizar o número de chamadas que seu aplicação faz para o servidor.

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.

Definir as operações de gravação

Para cada operação de gravação que você deseja executar, crie um hash que implemente uma das seguintes operações:

insert_one
update_one
update_many
replace_one
delete_one
delete_many

Em seguida, passe uma lista dessas instâncias para o método bulk_write .

As seções a seguir mostram como criar e usar instâncias das operações anteriores. A seção Executar a operação em massa demonstra como passar uma lista de hashes para o método bulk_write para executar a operação em massa.

Inserir operações

Para executar uma operação de inserção, crie um hash insert_one e especifique o documento que você deseja inserir.

O exemplo a seguir cria um hash insert_one:

insert_one = { insert_one: { name: 'Steve Rogers Cafe', borough: 'Brooklyn' } }

Para inserir vários documentos, crie um hash insert_one separado para cada documento.

Importante

Ao executar uma operação em massa, a operação insert_one não pode inserir um documento com um _id que já existe na coleção. Nessa situação, o driver lança um MongoBulkWriteException.

Atualizar operações

Para atualizar um documento, crie um hash update_one e passe os seguintes argumentos:

Filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção.
Atualize a operação que você deseja executar. Para obter mais informações sobre operações de atualização, consulte o guia Operadores de atualização de campo no manual do MongoDB Server .

A operação update_one especifica uma atualização para o primeiro documento que corresponde ao seu filtro de query.

O exemplo a seguir cria um hash update_one:

update_one = { update_one: 
  { 
    filter: { name: 'Mountain View' },
    update: { '$set': { borough: 'Queens' } }
  }
}

Para atualizar vários documentos, crie um hash update_many e passe os mesmos argumentos para uma operação update_one. A operação update_many especifica atualizações para todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria um hash update_many:

update_many = { update_many: 
  { 
    filter: { name: 'Starbucks' },
    update: { '$set': { cuisine: 'Cafe' } }
  }
}

Operações de substituição

Uma operação de substituição remove todos os campos e valores de um documento especificado e os substitui por novos campos e valores especificados por você. Para executar uma operação de substituição, crie um hash replace_one e passe os seguintes argumentos:

Filtro de query que especifica os critérios usados para corresponder aos documentos em sua coleção
documento de substituição que especifica os novos campos e valores a inserir

O exemplo a seguir cria um hash replace_one:

replace_one = { replace_one:
  { 
    filter: { name: 'Old World Diner' },
    replacement: { '$set': { name: 'New Age Luncheonette' } }
  }
}

Para substituir vários documentos, você deve criar um hash replace_one para cada documento.

Excluir operações

Para excluir um documento, crie um hash delete_one e passe um filtro de query especificando o documento que você deseja excluir. A operação delete_one exclui somente o primeiro documento que corresponde ao seu filtro de query.

O exemplo a seguir cria um hash delete_one:

delete_one = { delete_one: { name: 'Old World Diner' } }

Para excluir vários documentos, crie um hash delete_many e passe um filtro de query especificando o documento que deseja excluir. A operação delete_many exclui todos os documentos que correspondem ao seu filtro de query.

O exemplo a seguir cria um hash delete_many:

delete_many = { delete_many: { name: 'Starbucks' } }

Executar a operação em massa

Depois de definir um hash para cada operação que deseja executar, passe uma lista desses objetos para o método bulk_write . Por padrão, o método executa as operações na ordem especificada pela lista de hashes.

O exemplo a seguir executa diversas operações de gravação usando o método bulk_write :

insert_one = { insert_one: { name: 'Nuovo Ristorante', borough: 'Brooklyn', cuisine: 'Italian' } }
update_one = { update_one: 
  { 
    filter: { name: 'Moonlit Tavern' },
    update: { '$set': { borough: 'Queens' } }
  }
}
delete_many = { delete_many: { name: 'Crepe' } }
writes = [insert_one, update_one, delete_many]
collection.bulk_write(writes)

Se qualquer uma das operações de gravação falhar, o driver Ruby emitirá um BulkWriteError e não executará mais nenhuma operação. BulkWriteError fornece um item details que inclui a operação que falhou e detalhes sobre a exceção.

Observação

Quando o driver executa uma operação em massa, ele usa a preocupação de gravação da collection de destino. O driver relata todos os erros de preocupação de gravação depois de tentar todas as operações, independentemente da ordem de execução.

Personalizar operação de gravação em massa

Opcionalmente, o método bulk_write aceita um hash options que especifica as opções que você pode usar para configurar a operação de gravação em massa. Se você não especificar nenhuma opção, o driver executará a operação em massa com as configurações padrão.

A tabela a seguir descreve as opções que você pode utilizar para configurar o método bulk_write :

Opção	Descrição
`ordered`	Se `true`, o driver executa as operações de gravação na ordem fornecida. Se ocorrer um erro, as operações restantes não serão tentadas. Se `false`, o driver executa as operações em uma ordem arbitrária e tenta executar todas as operações. O padrão é `true`.
`bypass_document_validation`	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` é.
`session`	A sessão a ser usada para a operação. Tipo: `Session`
`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 .

O código a seguir cria opções e define a opção ordered como false para especificar uma escrita em massa não ordenada. Em seguida, o código usa o método bulk_write para executar as mesmas operações em massa do exemplo anterior:

options = { ordered: false }
collection.bulk_write(writes, options)

Se qualquer uma das operações de escrita em uma escrita em massa não ordenada falhar, o driver Ruby relatará os erros somente depois de tentar todas as operações.

Observação

Operações em massa não ordenadas não garantem uma ordem de execução. A ordem pode ser diferente da forma como você os lista para otimizar o tempo de execução.

Valor de retorno

O método bulk_write retorna um BulkWrite::Result. Você pode acessar informações da instância do Result utilizando os seguintes métodos de instância:

Método	Descrição
`acknowledged?`	Indica se o servidor reconheceu a operação de gravação.
`deleted_count`	Retorna o número de documentos excluídos, se houver.
`inserted_count`	Retorna o número de documentos inseridos, se houver.
`inserted_ids`	Retorna a lista de IDs de documento inseridos, se houver.
`matched_count`	Retorna o número de documentos correspondentes para uma atualização, se aplicável.
`modified_count`	Retorna o número de documentos modificados, se houver.
`upserted_count`	Retorna o número de documentos atualizados, se houver.
`upserted_ids`	Retorna a lista de IDs de documento atualizadas, se houver.

Informações adicionais

Para saber como realizar operações de escrita individuais, consulte os seguintes guias:

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

Exclua documentos

Transações