Especificar uma query

Visão geral

Neste guia, você pode aprender como especificar uma query para corresponder a um subconjunto de documentos.

Para corresponder a um subconjunto de documentos, especifique um filtro de query contendo seus critérios de correspondência. Os critérios de correspondência consistem nos campos e valores que você deseja que os documentos correspondam. Um filtro de query contém pelo menos um conjunto de critérios de correspondência para determinar quais documento retornar. Se você usar um filtro de query vazio em uma operação de busca, o driver corresponderá a todos os documento da collection.

Em um filtro de query, você pode corresponder campos com valores literais ou com operadores de query. Os operadores de query permitem que você realize operações matemáticas ou lógicas para localizar documentos dentro de uma collection.

Para fazer a correspondência de documentos usando valores literais, use o seguinte formato:

let filter = doc! { "<field>": "<value>" };

Para criar critérios de correspondência que incluam operadores de query, use o seguinte formato:

let filter = doc! { "<field>": doc! { "<operator>": "<value>" } };

Os exemplos nas seções seguintes mostram como especificar query utilizando o método find() para corresponder a documento em uma collection.

Este guia inclui as seguintes seções:

• Dados de amostra para exemplos apresenta os dados de amostra usados pelos exemplos de consulta

• Valores literais descrevem como consultar dados que correspondam exatamente a um valor fornecido no filtro de query

• Comparação descreve como fazer query de dados com base em comparações com valores em uma coleção

• Lógica descreve como consultar dados usando lógica aplicada aos resultados dos operadores de nível de campo

• O elemento descreve como fazer query com base na presença, ausência ou tipo de campo

• A avaliação descreve como executar lógica de nível superior, como pesquisas de regex e texto, ao consultar documentos em uma coleção

• Bitwise descreve como fazer query com base no conjunto de bits equivalentes de um valor base10

• Array descreve como fazer query de uma collection com base em dados dentro de um campo com valor de array

• Informações adicionais fornecem links para recursos e documentação da API para os tipos e métodos mencionados neste guia

Dados de amostra

Os exemplos deste guia usam os seguintes documentos de amostra. Cada documento representa uma frutas no estoque de uma loja e contém informações sobre sua quantidade. Alguns documentos contêm campos que descrevem a frutas ou seus fornecedores.

#[derive(Serialize, Deserialize, Debug)]
struct Fruit {
    _id: String,
    name: String,
    quantity: i32,
    #[serde(skip_serializing_if = "Option::is_none")]
    description: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    vendors: Option<Vec<String>>
}

Os exemplos nas seções a seguir query uma collection de documento descritos por estruturas Fruit :

let docs = vec! [
    Fruit { 
        _id: 1.to_string(), 
        name: "orange".to_string(), 
        quantity: 7,
        description: None,
        vendors: None
    },
    Fruit { 
        _id: 2.to_string(), 
        name: "apple".to_string(), 
        quantity: 4,
        description: Some("Granny Smith".to_string()),
        vendors: None
    },
    Fruit { 
        _id: 3.to_string(), 
        name: "banana".to_string(), 
        quantity: 36,
        description: None,
        vendors: None
    },
    Fruit { 
        _id: 4.to_string(), 
        name: "pear".to_string(), 
        quantity: 28,
        description: None,
        vendors: vec!["A".to_string(), "C".to_string() ].into()
    },
];

Para saber como inserir esses dados em uma coleção, consulte o guia Inserir documentos .

Valores literais

Os filtros de query de valor literal permitem que você query dados que correspondam exatamente a um valor fornecido no filtro de query. A operação a seguir usa uma query literal para procurar documentos que contenham um campo chamado name que tenha o valor de "pear":

let query = doc! { "name": "pear" };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }

my_coll.find(doc! {
   "price": doc! { "$eq": 5 }
}).await?;

my_coll.find(doc! {
   "price": 5
}).await?;

Comparação

Os operadores de comparação permitem fazer query de documentos comparando-os com valores no filtro de query. Os operadores de comparação comuns incluem $gt para comparações "maior que", $lt para comparações "menor que" e $ne para comparações "não igual a".

// $gt means "greater than"
let query = doc! { "quantity": doc! { "$gt": 5 } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "1", name: "orange", quantity: 7, description: None, vendors: None }
Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }
Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }

Lógica

Os operadores lógicos exigem pelo menos dois critérios de correspondência e podem corresponder a documentos que atendam a alguns, todos ou nenhum desses critérios. Por exemplo, você pode usar o operador lógico $or para fazer query de documentos que correspondem a um operador de comparação $gt (maior que) ou a uma query de valor literal.

let query =
    doc! { "$and": [
       doc! { "quantity": doc! { "$gt": 10 } },
       doc! { "quantity": doc! { "$mod": [ 3, 0 ] } }
   ]
};
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }

my_coll.find(doc! {
   "price": doc! { "$eq": 5 },
   "quantity": doc! { "$gt": 4 }
});

my_coll.find(doc! {
   "$and": [
      doc! { "price": { "$eq": 5 }},
      doc! { "quantity": { "$gt": 4 }}
   ]
});

Elemento

Os operadores de elementos permitem que você faça a correspondência de documentos com base nos tipos de campos especificados ou se eles incluem campos especificados.

let query = doc! { "description": doc! { "$exists": true } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "2", name: "apple", quantity: 4, description: Some("Granny Smith"),
vendors: None }

Avaliação

Os operadores de avaliação analisam campos individuais ou documentos de uma coleção para determinar se eles atendem a determinados critérios. Cada operador de avaliação executa uma função diferente. Por exemplo, o operador $mod executa uma operação matemática em um valor de campo e o operador $where permite avaliar valores em relação a expressões JavaScript.

// $mod means "modulo" and checks if the remainder is a specific value
let query = doc! { "quantity": doc! { "$mod": [ 3, 0 ] } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "3", name: "banana", quantity: 36, description: None, vendors: None }

Bitwise

Os operadores bit a bit convertem um campo numérico de um número de base 10 (decimal) no número de base 2 (binário) correspondente. Eles verificam se o valor em um documento tem os mesmos bits definidos como o valor em seus critérios de correspondência.

let query = doc! { "quantity": doc! { "$bitsAllSet": 7 } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "1", name: "orange", quantity: 7, description: None, vendors: None }

Array

Os operadores de array verificam os valores ou a quantidade de elementos em um campo com valor de array.

let query = doc! { "vendors": doc! { "$elemMatch": { "$eq": "C" } } };
let mut cursor = my_coll.find(query).await?;
while let Some(doc) = cursor.try_next().await? {
    println!("{:?}", doc);
}

Fruit { _id: "4", name: "pear", quantity: 28, description: None, vendors: Some(["A", "C"]) }

Informações adicionais

Para saber mais sobre como encontrar operações, consulte o guia Recuperar dados .

Para saber mais sobre operadores de query, consulte Seletores de query no manual do servidor MongoDB.