Interroger des éléments dans Azure Cosmos DB for NoSQL à l’aide de .NET

Article
08/15/2024

S’APPLIQUE À : NoSQL

Les éléments dans Azure Cosmos DB représentent des entités stockées dans un conteneur. Dans l’API pour NoSQL, un élément se compose de données au format JSON avec un identificateur unique. Lorsque vous émettez des requêtes à l’aide de l’API pour NoSQL, les résultats sont retournés sous la forme d’un tableau JSON de documents JSON.

Interroger des éléments à l’aide de SQL

Azure Cosmos DB for NoSQL prend en charge l’utilisation du langage SQL (Structured Query Language) pour effectuer des requêtes sur des éléments dans des conteneurs. Une requête SQL simple comme SELECT * FROM products retourne tous les éléments et toutes les propriétés d’un conteneur. Les requêtes peuvent être encore plus complexes et inclure des projections de champs, des filtres et d’autres clauses SQL courantes :

SELECT 
    p.name, 
    p.description AS copy
FROM 
    products p 
WHERE 
    p.price > 500

Pour en savoir plus sur la syntaxe SQL pour Azure Cosmos DB for NoSQL, consultez Bien démarrer avec les requêtes SQL.

Interroger un élément

Notes

Les exemples de cet article partent du principe que vous avez déjà défini un type C# pour représenter vos données nommé Product :

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Pour interroger des éléments dans un conteneur, appelez l’une des méthodes suivantes :

GetItemQueryIterator<>
GetItemLinqQueryable<>

Interroger des éléments à l’aide d’une requête SQL de manière asynchrone

Cet exemple génère une requête SQL à l’aide d’une chaîne simple, récupère un itérateur de flux, puis utilise des boucles imbriquées pour itérer sur les résultats. La boucle while externe effectue une itération dans les pages de résultats, tandis que la boucle foreach interne itère les résultats d’une page.

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products p WHERE p.quantity > 10"
);

// Iterate query result pages
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

La méthode Container.GetItemQueryIterator<> retourne un FeedIterator<> utilisé pour itérer les résultats multipages. La propriété HasMoreResults indique s’il reste des pages de résultats. La méthode ReadNextAsync obtient la page de résultats suivante sous forme d’énumérable qui est ensuite utilisé dans une boucle pour itérer les résultats.

Vous pouvez également utiliser QueryDefinition pour générer une requête SQL avec une entrée paramétrisée :

// Build query definition
var parameterizedQuery = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.quantity > @quantity"
)
    .WithParameter("@quantity", 10);

// Query multiple items from container
using FeedIterator<Product> filteredFeed = container.GetItemQueryIterator<Product>(
    queryDefinition: parameterizedQuery
);

// Iterate query result pages
while (filteredFeed.HasMoreResults)
{
    FeedResponse<Product> response = await filteredFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Conseil

Les valeurs d’entrée paramétrisées peuvent aider à empêcher de nombreuses attaques courantes d’injection de requêtes SQL.

Interroger des éléments à l’aide de LINQ de manière asynchrone

Dans cet exemple, un objet IQueryable<> est utilisé pour construire une requête LINQ (Language Integrated Query). Les résultats sont ensuite itérés à l’aide d’un itérateur de flux.

// Get LINQ IQueryable object
IOrderedQueryable<Product> queryable = container.GetItemLinqQueryable<Product>();

// Construct LINQ query
var matches = queryable
    .Where(p => p.quantity > 10);

// Convert to feed iterator
using FeedIterator<Product> linqFeed = matches.ToFeedIterator();

// Iterate query result pages
while (linqFeed.HasMoreResults)
{
    FeedResponse<Product> response = await linqFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Matched item:\t{item.name}");
    }
}

La méthode Container.GetItemLinqQueryable<> construit un IQueryable pour générer la requête LINQ. Ensuite, la méthode ToFeedIterator<> est utilisée pour convertir l’expression de requête LINQ en un FeedIterator<>.

Conseil

Bien que vous puissiez itérer le IQueryable<>, cette opération est synchrone. Utilisez la méthode ToFeedIterator<> pour collecter les résultats de manière asynchrone.

Étapes suivantes

Maintenant que vous avez interrogé plusieurs éléments, essayez l’un de nos tutoriels de bout en bout avec l’API pour NoSQL.

Créer une application qui interroge et ajoute des données à Azure Cosmos DB for NoSQL

Partager via