Especifica un query

Overview

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

Para buscar coincidencias con un subconjunto de documentos, especifique un filtro de consulta que contenga sus criterios de coincidencia. Estos criterios consisten en los campos y valores que desea que coincidan con los documentos. Un filtro de consulta contiene al menos un conjunto de criterios de coincidencia para determinar qué documentos devolver. Si utiliza un filtro de consulta vacío en una operación de búsqueda, el controlador buscará coincidencias con todos los documentos de la colección.

En un filtro de consulta, puede hacer coincidir campos con Valores literales o con operadores de consulta. Los operadores de consulta 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 consultas mediante el uso de find() Método para hacer coincidir 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

• La comparación describe cómo consultar datos basándose 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

• El elemento describe cómo realizar consultas según 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

• Lamatriz describe cómo consultar una colección en función de los datos dentro de un campo con valor de matriz.

• Información adicional proporciona enlaces a recursos y documentación de 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 del inventario de una tienda y contiene información sobre su cantidad. Algunos documentos contienen campos que describen la fruta o a 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 permiten consultar documentos comparándolos con los valores del filtro de consulta. Los operadores de comparación más comunes son $gt para comparaciones "mayores que", $lt para comparaciones "menores que" y $ne para comparaciones "diferentes 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

Los operadores lógicos requieren al menos dos criterios de coincidencia y pueden buscar documentos que cumplan algunos, todos o ninguno de estos criterios. Por ejemplo, puede usar el operador lógico $or para consultar documentos que coincidan con un operador de comparación $gt (mayor que) o una consulta 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 los 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 con el valor de un campo, y el operador $where permite evaluar valores con expresiones 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 decimal (base10) al número binario (base2) correspondiente. Comprueban si el valor de un documento tiene los mismos bits que el valor de los 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 matriz comprueban los valores o la cantidad de elementos en un campo con valor de matriz.

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 de consulta, consulte Selectores de consultas en el manual del servidor.