/ /

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 como eles aparecem no banco de dados. Para saber mais, consulte ordem natural no glossário manual do servidor. Tipo: `Document` Padrão: `None`
`write_concern`	O write concern para a operação. Se você não definir esta opção, a operação herdará o write concern definido para a coleção. Para saber mais sobre write concern, consulte write concern no manual do servidor. Tipo: `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 apenas ao conectar-se às versões 4.4 e posteriores do MongoDB Server. 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`	Se `true`, permite que o driver execute uma gravar que viole a validação do nível do documento. Para saber mais sobre validação, consulte Validação de esquema no manual do servidor. Tipo: `bool` Padrão: `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 como eles 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`	O write concern para a operação. Se você não definir esta opção, a operação herdará o write concern definido para a coleção. Para saber mais sobre write concern, consulte write concern no manual do servidor. Tipo: `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 apenas ao conectar-se às versões 4.4 e posteriores do MongoDB Server. 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 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`	Se `true`, permite que o driver execute uma gravar que viole a validação do nível do documento. Para saber mais sobre validação, consulte Validação de esquema no manual do servidor. Tipo: `bool` Padrão: `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 como eles 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`	O write concern para a operação. Se você não definir esta opção, a operação herdará o write concern definido para a coleção. Para saber mais sobre write concern, consulte write concern no manual do servidor. Tipo: `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 apenas ao conectar-se às versões 4.4 e posteriores do MongoDB Server. 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 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