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 deste guia usam a coleção restaurants no banco de dados sample_restaurants dosconjuntos 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 saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

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 delete_one hash e passe um filtro de query especificando o documento que você deseja excluir. A delete_one operação 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 delete_many hash e passe um filtro de query especificando o documento que deseja excluir. A delete_many operação 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`	If `true`, the driver performs the write operations in the order provided. If an error occurs, the remaining operations are not attempted. If `false`, the driver performs the operations in an arbitrary order and attempts to perform all operations. Defaults to `true`.
`bypass_document_validation`	Specifies whether the update operation bypasses document validation. This lets you update documents that don't meet the schema validation requirements, if any exist. For more information about schema validation, see Schema Validation in the MongoDB Server manual. Defaults to `false`.
`session`	The session to use for the operation. Type: `Session`
`let`	Provides a map of parameter names and values to set top-level variables for the operation. Values must be constant or closed expressions that don't reference document fields.

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?`	Indicates if the server acknowledged the write operation.
`deleted_count`	Returns the number of documents deleted, if any.
`inserted_count`	Returns the number of documents inserted, if any.
`inserted_ids`	Returns the list of inserted document ids, if any.
`matched_count`	Returns the number of documents matched for an update, if applicable.
`modified_count`	Returns the number of documents modified, if any.
`upserted_count`	Returns the number of upserted documents, if any.
`upserted_ids`	Returns the list of upserted document ids, if any.

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