Itens de consulta no Azure Cosmos DB para NoSQL usando .NET

Artigo
08/15/2024

APLICA-SE A: NoSQL

Os itens no Azure Cosmos DB representam entidades armazenadas em um contêiner. Na API para NoSQL, um item consiste em dados formatados em JSON com um identificador exclusivo. Quando você emite consultas usando a API para NoSQL, os resultados são retornados como uma matriz JSON de documentos JSON.

Itens de consulta usando SQL

O Azure Cosmos DB para NoSQL dá suporte ao uso de SQL (Structured Query Language) para executar consultas em itens em contêineres. Uma consulta SQL simples como SELECT * FROM products retornará todos os itens e propriedades de um contêiner. As consultas podem ser ainda mais complexas e incluir projeções de campo específicas, filtros e outras cláusulas SQL comuns:

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

Para saber mais sobre a sintaxe SQL do Azure Cosmos DB para NoSQL, consulte Introdução às consultas SQL.

Consultar um item

Nota

Os exemplos neste artigo pressupõem que você já definiu um tipo C# para representar seus dados chamado Product:

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

Para consultar itens em um contêiner, chame um dos seguintes métodos:

GetItemQueryIterator<>
GetItemLinqQueryable<>

Itens de consulta usando uma consulta SQL de forma assíncrona

Este exemplo cria uma consulta SQL usando uma cadeia de caracteres simples, recupera um iterador de feed e usa loops aninhados para iterar os resultados. O loop while externo iterará através das páginas de resultados, enquanto o loop foreach interno itera sobre os resultados dentro de uma página.

// 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}");
    }
}

O método Container.GetItemQueryIterator<> retorna um FeedIterator<> que é usado para iterar através de resultados de várias páginas. A HasMoreResults propriedade indica se ainda restam mais páginas de resultados. O ReadNextAsync método obtém a próxima página de resultados como um enumerável que é usado em um loop para iterar sobre os resultados.

Como alternativa, use o QueryDefinition para criar uma consulta SQL com entrada parametrizada:

// 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}");
    }
}

Gorjeta

Valores de entrada parametrizados podem ajudar a evitar muitos ataques comuns de injeção de consulta SQL.

Itens de consulta usando LINQ de forma assíncrona

Neste exemplo, um IQueryable<> objeto é usado para construir uma consulta integrada de linguagem (LINQ). Os resultados são então iterados usando um iterador de feed.

// 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}");
    }
}

O método Container.GetItemLinqQueryable<> constrói um IQueryable para criar a consulta LINQ. Em seguida, o ToFeedIterator<> método é usado para converter a expressão de consulta LINQ em um FeedIterator<>arquivo .

Gorjeta

Embora você possa iterar sobre o , esta operação é síncrona IQueryable<>. Use o ToFeedIterator<> método para coletar resultados de forma assíncrona.

Próximos passos

Agora que você consultou vários itens, experimente um de nossos tutoriais completos com a API para NoSQL.

Criar um aplicativo que consulta e adiciona dados ao Azure Cosmos DB para NoSQL

Partilhar via