Consultar itens no Azure Cosmos DB for NoSQL usando o .NET

APLICA-SE A: NoSQL

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

Consultar itens usando SQL

O Azure Cosmos DB for NoSQL dá suporte ao uso da linguagem SQL 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 comuns de SQL:

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

Para saber mais sobre a sintaxe SQL da Azure Cosmos DB for NoSQL, confira Introdução a consultas SQL.

Consultar um item

Observação

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

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

Consultar itens usando uma consulta SQL de modo assíncrono

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

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products 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 cada resultado de várias páginas. A propriedade HasMoreResults indica se ainda há mais páginas de resultado. O método ReadNextAsync obtém a próxima página de resultados como uma enumeração, que é usada em um loop para iterar cada resultado.

Como alternativa, use 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}");
    }
}

Dica

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

Consultar itens usando LINQ de modo assíncrono

Neste exemplo, um objeto IQueryable<> é usado para construir uma LINQ (Consulta Integrada à Linguagem). Os resultados sã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 método ToFeedIterator<> é usado para converter a expressão de consulta LINQ em uma FeedIterator<>.

Dica

Embora você possa iterar na IQueryable<>, essa operação é síncrona. Use o método ToFeedIterator<> para coletar resultados de modo assíncrono.

Próximas etapas

Agora que você consultou vários itens, experimente um dos tutoriais de ponta a ponta com a API do NoSQL.

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