/ /

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:

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

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