Especifica un query

Overview

En esta guía, puedes aprender a especificar una query para hacer coincidir un subconjunto de documentos.

Para coincidir con un subconjunto de documentos, especifique un filtro de query que contenga sus criterios de coincidencia. Los criterios de coincidencia consisten en los campos y valores que deseas que coincidan los documentos. Un filtro de query contiene al menos un conjunto de criterios de coincidencia para determinar qué documentos devolver. Si utilizas un filtro de query vacío en una operación de búsqueda, el driver compara todos los documentos de la colección.

En un filtro de query, puedes filtrar campos con valores literales o con operadores del query. Los operadores del query permiten realizar operaciones matemáticas o lógicas para localizar documentos dentro de una colección.

Para hacer coincidir documentos mediante valores literales, utilice el siguiente formato:

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

Para crear criterios de coincidencia que incluyan operadores de consulta, utilice el siguiente formato:

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

Los ejemplos en las siguientes secciones muestran cómo especificar queries mediante el uso del find() método para igualar documentos en una colección.

Esta guía incluye las siguientes secciones:

• Datos de muestra para ejemplos presenta los datos de muestra que se utilizan en los ejemplos de consulta

• Valores literales describe cómo consultar datos que coincidan exactamente con un valor proporcionado en el filtro de consulta

• Comparación describe cómo consultar datos basados en comparaciones con valores en una colección

• Lógico describe cómo query datos utilizando la lógica aplicada a los resultados de los operadores a nivel de campo

• Elemento describe cómo query en función de la presencia, ausencia o tipo de campo

• Evaluación describe cómo ejecutar lógica de alto nivel, como búsquedas con RegEx y texto, al consultar documentos en una colección

• Bitwise describe cómo realizar consultas en función del conjunto de bits equivalente de un valor base10

• Arreglo describe cómo query una colección en función de los datos dentro de un campo con valor de arreglo

• Información adicional proporciona enlaces a recursos y documentación de la API para los tipos y métodos mencionados en esta guía

Datos de muestra

Los ejemplos de esta guía utilizan los siguientes documentos de muestra. Cada documento representa una fruta en el inventario de una tienda y contiene información sobre su cantidad. Algunos documentos contienen campos que describen la fruta o sus proveedores.

#[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>>
}

Los ejemplos en las siguientes secciones consultan una colección de documentos descritos por estructuras 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 aprender a insertar estos datos en una colección, consulte la Guía deinserción de documentos.

Valores literales

Los filtros de consulta de valor literal permiten consultar datos que coinciden exactamente con el valor proporcionado en el filtro. La siguiente operación utiliza una consulta literal para buscar documentos que contengan un campo llamado name con el valor "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?;

Comparación

Los operadores de comparación le permiten consultar documentos comparándolos con valores establecidos en el filtro de query. Los operadores de comparación comunes incluyen $gt para composiciones de «mayor que», $lt para composiciones de «menor que» y $ne para composiciones de «distinto de».

// $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

Los operadores lógicos requieren al menos dos criterios de coincidencia y pueden hacer coincidir documentos que cumplan algunos, todos o ninguno de estos criterios. Por ejemplo, puedes usar el operador lógico $or para consultar documentos que coincidan con un operador de comparación $gt (mayor que) o con una 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

Los operadores de elementos le permiten hacer coincidir documentos según los tipos de campos especificados o si incluyen 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 }

Evaluación

Los operadores de evaluación analizan campos individuales o documentos de una colección para determinar si cumplen ciertos criterios. Cada operador de evaluación realiza una función diferente. Por ejemplo, el operador $mod realiza una operación matemática sobre un valor de campo, y el operador $where permite evaluar valores en comparación con expresiones de 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

Los operadores bit a bit convierten un campo numérico de un número en base 10 (decimal) en el número correspondiente en base 2 (binario). Verifican si el valor en un documento tiene los mismos bits establecidos que el valor en tus criterios de coincidencia.

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 }

Arreglo

Los operadores de arreglos verifican los valores o la cantidad de elementos en un campo con valor de arreglo.

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"]) }

Información Adicional

Para aprender más sobre las operaciones find, consulte la guía Recuperar Datos.

Para obtener más información sobre los operadores del query, consulta Selectores de consultas en el manual del servidor.