/ /

Driver Rust

Operações CRUD

Página inicial do Docs

Bibliotecas do cliente

Rust

Driver Rust

Operações CRUD

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:

Sample Data for Examples presents the sample data that is used by the compound operation examples
Find and Delete a Document describes how to find and delete a document in a single operation
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() encadeando métodos de construtor de opções a find_one_and_delete(). Esses métodos de construtor definem campos de estrutura FindOneAndDeleteOptions .

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

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`	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`
`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`

Observação

Opções de configuração

Você pode definir FindOneAndDeleteOptions campos encadeando métodos de construtor de opções diretamente à chamada de método find_one_and_delete() . Se você estiver utilizando uma versão anterior do driver, você deverá construir uma instância do FindOneAndDeleteOptions encadeando métodos de construtor de opção ao método builder() . Em seguida, passe a instância de opções como parâmetro para find_one_and_delete().

O código a seguir mostra como definir o campo comment encadeando o método comment() ao método find_one_and_delete() :

let res = my_coll.find_one_and_delete(filter)
    .comment(bson!("hello"))
    .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).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() encadeando métodos de construtor de opções a find_one_and_update(). Esses métodos de construtor definem campos de estrutura FindOneAndUpdateOptions .

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

Opção	Descrição
`array_filters`	O conjunto de filtros que especificam os elementos da array aos quais a atualização se aplica. Para aprender mais, consulte o guia Atualizar arrays em um documento. 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`	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 código a seguir mostra como definir o campo comment encadeando o método comment() ao método find_one_and_update() :

let res = my_coll.find_one_and_update(filter, update)
    .comment(bson!("hello"))
    .await?;

Exemplo de localização e atualização

Este exemplo mostra como executar as seguintes ações:

Chame o método find_one_and_update()
Passe um filtro de query para find_one_and_update() que corresponda a um documento onde o valor de school é "Aurora High School"
Passe um documento de atualização para find_one_and_update() que define o campo school como "Durango High School" e incrementa o campo age em 1
Encadeie o método return_document() a find_one_and_update() para retornar o documento correspondente 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 res = my_coll.find_one_and_update(filter, update)
    .return_document(ReturnDocument::After)
    .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() encadeando métodos de construtor de opções a find_one_and_replace(). Esses métodos de construtor definem campos de estrutura FindOneAndReplaceOptions .

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 código a seguir mostra como definir o campo comment encadeando o método comment() ao método find_one_and_replace() :

let res = my_coll.find_one_and_replace(filter, replacement)
    .comment(bson!("hello"))
    .await?;

Exemplo de localização e substituição

Este exemplo executa as seguintes ações:

Chama o método find_one_and_replace()
Passa um filtro de query para find_one_and_replace() que corresponde a um documento onde o valor de name inclui a string "Johnson"
Passa um documento de substituição para find_one_and_replace() que descreve um novo aluno
Encadeia o método return_document() a find_one_and_replace() para retornar o documento após a substituição
Encadeia o método projection() aos campos find_one_and_replace()``to project only the ``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 res = my_coll.find_one_and_replace(filter, replacement)
    .return_document(ReturnDocument::After)
    .projection(doc! { "name": 1, "school": 1, "_id": 0 })
    .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

Transações

Configurar operações CRUD