/ /

Operações compostas

Visão geral

Neste guia, você verá como usar o driver Rust para executar operações compostas.

As operações compostas combinam a funcionalidade das operações de leitura e escrita em uma ação atômica . Se você executar uma operação de leitura e uma operação de gravação em sequência, alguém poderá alterar seu documento de destino entre as operações, levando a resultados inesperados. Quando você executa uma operação composta, o MongoDB impede alterações de dados intermediárias colocando um bloqueio de gravação no documento que você está modificando até que a operação seja concluída.

Você pode executar as seguintes operações compostas com o driver:

Encontrar e excluir um documento
Localizar e atualizar um documento
Localizar e substituir um documento

Este guia inclui as seguintes seções:

Dados de amostra para exemplos apresenta os dados de amostra que são usados pelos exemplos de operações compostas
Encontrar e excluir um documento descreve como localizar e excluir um documento em uma única operação
Localizar e atualizar um documento descreve como localizar e atualizar um documento em uma única operação
Localizar e substituir um documento descreve como localizar e substituir um documento em uma única operação
Informações adicionais fornecem links para recursos e documentação da API para os tipos e métodos mencionados neste guia

Dica

Para saber como realizar operações de leitura e gravação atômicas em mais de um documento por vez, consulte o guia transação .

Dados de amostra para exemplos

Os exemplos deste guia usam os seguintes documentos de amostra. Cada documento representa um aluno e contém informações sobre sua idade e a escola que atende:

{ "name": "Alex Johnson", "age": 8, "school": "Lakeside Elementary" },
{ "name": "Samara Khan", "age": 11, "school": "Rolling Hills Middle School" },
{ "name": "Ben Joseph", "age": 16, "school": "Aurora High School" },
{ "name": "Deanna Porowski", "age": 10, "school": "Lakeside Elementary" }

Localize e exclua um documento

O método find_one_and_delete() localiza e exclui o primeiro documento que corresponde ao filtro de query especificado. Se um documento corresponder aos critérios de filtro, o método retornará um tipo Some . Se nenhum documento corresponder, ele retornará um tipo None .

Observação

Se quiser realizar outras operações entre localizar e excluir um documento, você pode chamar o método find_one() seguido pelo método delete_one() .

Modificar comportamento de localização e exclusão

Opcionalmente, você pode modificar o comportamento do método find_one_and_delete() passando uma instância FineOneAndDeleteOptions como parâmetro. Para utilizar valores padrão para cada configuração, especifique o valor None para o parâmetro de opções.

A tabela a seguir descreve as opções disponíveis em FineOneAndDeleteOptions:

Opção	Descrição
`max_time`	A quantidade máxima de tempo em milissegundos que a query pode executar. Tipo: `Duration`
`projection`	A projeção a ser usada ao retornar resultados. Tipo: `Document` Padrão: `None`
`sort`	A ordem de classificação a ser usada ao retornar resultados. Por padrão, o driver retorna documentos em sua ordem natural ou conforme aparecem no banco de dados. Para saber mais, consulte ordem natural no glossário manual do servidor. Tipo: `Document` Padrão: `None`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	O agrupamento a ser usado ao classificar os resultados. Para saber mais sobre agrupamentos, consulte o guia Agrupamentos. Tipo: `Collation` Padrão: `None`
`hint`	O índice a ser usado para a operação. Para saber mais sobre índices, consulte Índices no manual do servidor. Esta opção está disponível somente ao conectar às versões.4 do MongoDB Server4 e posteriores. Tipo: `Hint` Padrão: `None`
`let_vars`	Um mapa de parâmetros e valores. Você pode acessar esses parâmetros como variáveis em expressões de agregação. Esta opção está disponível apenas ao conectar-se às versões 5.0 e posteriores do MongoDB Server. Tipo: `Document`
`comment`	Um valor `Bson` arbitrário vinculado à operação para rastreá-lo através do profiler de banco de dados, `currentOp` e logs. Esta opção está disponível apenas ao conectar-se às versões 4.4 do MongoDB Server e posteriores. Tipo: `Bson` Padrão: `None`

O driver Rust implementa o padrão de design Builder para a criação de uma instância FindOneAndDeleteOptions . Você pode usar o método builder() do tipo para construir uma instância de opções encadeando as funções do construtor de opções uma de cada vez.

O código a seguir mostra como construir uma instância FindOneAndDeleteOptions e passá-la para o método find_one_and_delete():

let opts = FindOneAndDeleteOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_delete(filter, opts).await?;

Exemplo de localização e exclusão

O exemplo a seguir usa o método find_one_and_delete() para combinar e excluir o primeiro documento onde o valor do campo age é menor ou igual a 10:

let filter = doc! { "age": doc! { "$lte": 10 } };
let res = my_coll.find_one_and_delete(filter, None).await?;
println!("Deleted document:\n{:?}", res);

Deleted document:
Some(Document({"_id": ObjectId("..."),
"name": String("Deanna Porowski"), "age": Int32(10), "school":
String("Lakeside Elementary")}))

Encontrar e atualizar um documento

O método find_one_and_update() localiza e atualiza o primeiro documento que corresponde ao filtro de query especificado. A operação atualiza o documento com base nas especificações fornecidas em um documento de atualização. Se um documento corresponder aos critérios de filtro, o método retornará um tipo Some . Se nenhum documento corresponder, ele retornará um tipo None .

Observação

Se quiser realizar outras operações entre localizar e atualizar um documento, você pode chamar o método find_one() seguido pelo método update_one() .

Modificar comportamento de localização e atualização

Opcionalmente, você pode modificar o comportamento do método find_one_and_update() passando uma instância FindOneAndUpdateOptions como parâmetro. Para utilizar valores padrão para cada configuração, especifique o valor None para o parâmetro de opções.

A tabela a seguir descreve as opções disponíveis em FineOneAndDeleteOptions:

Opção	Descrição
`array_filters`	O conjunto de filtros que especificam os elementos da array aos quais a atualização se aplica. Tipo: `Vec<Document>`
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual. Type: `bool` Default: `false`
`max_time`	A quantidade máxima de tempo em milissegundos que a query pode executar. Tipo: `Duration`
`projection`	A projeção a ser usada ao retornar resultados. Tipo: `Document` Padrão: `None`
`return_document`	Se `Before`, a operação retornará o documento antes da atualização. Se `After`, a operação retornará o documento atualizado. Tipo: `ReturnDocument` Padrão: `ReturnDocument::Before`
`sort`	A ordem de classificação a ser usada ao retornar resultados. Por padrão, o driver retorna documentos em sua ordem natural ou conforme aparecem no banco de dados. Para saber mais, consulte ordem natural no glossário manual do servidor. Tipo: `Document` Padrão: `None`
`upsert`	Se for verdadeiro, a operação insere um documento se nenhum documento corresponder ao filtro de queries. Tipo: `bool` Padrão: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	O agrupamento a ser usado ao classificar os resultados. Para saber mais sobre agrupamentos, consulte o guia Agrupamentos. Tipo: `Collation` Padrão: `None`
`hint`	The index to use for the operation. To learn more about indexes, see Indexes in the Server manual. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Hint` Default: `None`
`let_vars`	Um mapa de parâmetros e valores. Você pode acessar esses parâmetros como variáveis em expressões de agregação. Esta opção está disponível apenas ao conectar-se às versões 5.0 e posteriores do MongoDB Server. Tipo: `Document`
`comment`	Um valor `Bson` arbitrário vinculado à operação para rastreá-lo através do profiler de banco de dados, `currentOp` e logs. Esta opção está disponível apenas ao conectar-se às versões 4.4 do MongoDB Server e posteriores. Tipo: `Bson` Padrão: `None`

O driver Rust implementa o padrão de design Builder para a criação de uma instância FindOneAndUpdateOptions . Você pode usar o método builder() do tipo para construir uma instância de opções encadeando métodos de construtor de opções um de cada vez.

O código a seguir mostra como construir uma instância FindOneAndUpdateOptions e passá-la para o método find_one_and_update():

let opts = FindOneAndUpdateOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;

Exemplo de localização e atualização

Este exemplo mostra como chamar o método find_one_and_update() com os seguintes parâmetros:

Um filtro de query que corresponde a um documento onde o valor de school é "Aurora High School"
Um documento de atualização que define o campo school como "Durango High School" e incrementa o campo age em 1
Uma instância FindOneAndUpdateOptions que retorna o documento após a atualização

let filter = doc! { "school": "Aurora High School" };
let update =
    doc! { "$set": doc! { "school": "Durango High School" },
           "$inc": doc! { "age": 1 } };
let opts = FindOneAndUpdateOptions::builder()
    .return_document(Some(ReturnDocument::After))
    .build();
let res = my_coll.find_one_and_update(filter, update, opts).await?;
println!("Updated document:\n{:?}", res);

Updated document:
Some(Document({"_id": ObjectId("..."),
"name": String("Ben Joseph"), "age": Int32(17), "school":
String("Durango High School")}))

Encontrar e substituir um documento

O método find_one_and_replace() localiza e substitui o primeiro documento que corresponde ao filtro de query especificado. A operação substitui todos os campos do documento, exceto o campo _id por campos e valores que você fornece. Se um documento corresponder aos critérios de filtro, o método retornará um tipo Some . Se nenhum documento corresponder, ele retornará um tipo None .

Observação

Se você quiser realizar outras operações entre localizar e substituir um documento, poderá chamar o método find_one() seguido pelo método replace_one() .

Modificar o comportamento de localizar e substituir

Opcionalmente, você pode modificar o comportamento do método find_one_and_replace() passando uma instância FindOneAndReplaceOptions como parâmetro. Para utilizar valores padrão para cada configuração, especifique o valor None para o parâmetro de opções.

A tabela a seguir descreve as opções disponíveis em FindOneAndReplaceOptions:

Opção	Descrição
`bypass_document_validation`	If `true`, allows the driver to perform a write that violates document-level validation. To learn more about validation, see Schema Validation in the Server manual. Type: `bool` Default: `false`
`max_time`	A quantidade máxima de tempo em milissegundos que a query pode executar. Tipo: `Duration`
`projection`	A projeção a ser usada ao retornar resultados. Tipo: `Document` Padrão: `None`
`return_document`	Se `Before`, a operação retornará o documento antes da atualização. Se `After`, a operação retornará o documento atualizado. Tipo: `ReturnDocument` Padrão: `ReturnDocument::Before`
`sort`	The sorting order to use when returning results. By default, the driver returns documents in their natural order, or as they appear in the database. To learn more, see natural order in the Server manual glossary. Type: `Document` Default: `None`
`upsert`	Se for verdadeiro, a operação insere um documento se nenhum documento corresponder ao filtro de queries. Tipo: `bool` Padrão: `false`
`write_concern`	The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual. Type: `WriteConcern`
`collation`	O agrupamento a ser usado ao classificar os resultados. Para saber mais sobre agrupamentos, consulte o guia Agrupamentos. Tipo: `Collation` Padrão: `None`
`hint`	The index to use for the operation. To learn more about indexes, see Indexes in the Server manual. This option is available only when connecting to MongoDB Server versions 4.4 and later. Type: `Hint` Default: `None`
`let_vars`	Um mapa de parâmetros e valores. Você pode acessar esses parâmetros como variáveis em expressões de agregação. Esta opção está disponível apenas ao conectar-se às versões 5.0 e posteriores do MongoDB Server. Tipo: `Document`
`comment`	Um valor `Bson` arbitrário vinculado à operação para rastreá-lo através do profiler de banco de dados, `currentOp` e logs. Esta opção está disponível apenas ao conectar-se às versões 4.4 do MongoDB Server e posteriores. Tipo: `Bson` Padrão: `None`

O driver Rust implementa o padrão de design Builder para a criação de uma instância FindOneAndReplaceOptions . Você pode usar o método builder() do tipo para construir uma instância de opções encadeando as funções do construtor de opções uma de cada vez.

O código a seguir mostra como construir uma instância FindOneAndReplaceOptions e passá-la para o método find_one_and_replace():

let opts = FindOneAndReplaceOptions::builder().comment(bson!("hello")).build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;

Exemplo de localização e substituição

Este exemplo mostra como chamar o método find_one_and_replace() com os seguintes parâmetros:

Um filtro de queries que corresponde a um documento em que o valor de name inclui a string "Johnson"
Um documento de substituição que descreve um novo aluno
Uma instância FindOneAndReplaceOptions que retorna o documento após a substituição e projeta somente os campos name e school na saída

let filter = doc! { "name": doc! { "$regex": "Johnson" } };
let replacement =
    doc! { "name": "Toby Fletcher", 
           "age": 14,
           "school": "Durango High School" };
let opts = FindOneAndReplaceOptions::builder()
    .return_document(Some(ReturnDocument::After))
    .projection(doc! { "name": 1, "school": 1, "_id": 0 })
    .build();
let res = my_coll.find_one_and_replace(filter, replacement, opts).await?;
println!("Document after replacement:\n{:?}", res);

Document after replacement:
Some(Document({"name": String("Toby Fletcher"), "school":
String("Durango High School")}))

Informações adicionais

Para saber mais sobre as operações neste guia, consulte a seguinte documentação:

Documentação da API

Para saber mais sobre os métodos e tipos mencionados neste guia, consulte a documentação da API abaixo:

Voltar

Operações em massa

Serialização