다음을 통해 공유


.NET을 사용하여 Azure Cosmos DB for NoSQL의 항목 쿼리

적용 대상: NoSQL

Azure Cosmos DB의 항목은 컨테이너 내에 저장된 엔터티를 나타냅니다. API for NoSQL에서 항목은 고유 식별자가 있는 JSON 형식 데이터로 구성됩니다. API for NoSQL을 사용하여 쿼리를 실행하면 결과가 JSON 문서의 JSON 배열로 반환됩니다.

SQL을 사용하여 항목 쿼리

Azure Cosmos DB for NoSQL은 SQL(구조적 쿼리 언어)을 사용하여 컨테이너의 항목에 대한 쿼리를 수행할 수 있도록 지원합니다. SELECT * FROM products와 같은 간단한 SQL 쿼리는 컨테이너의 모든 항목과 속성을 반환합니다. 쿼리는 훨씬 더 복잡할 수 있으며 특정 필드 프로젝션, 필터 및 기타 일반적인 SQL 절을 포함할 수 있습니다.

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

Azure Cosmos DB for NoSQL의 SQL 구문에 대한 자세한 내용은 SQL 쿼리 시작을 참조하세요.

항목 쿼리

참고 항목

이 문서의 예제에서는 Product라는 데이터를 나타내는 C# 형식을 이미 정의했다고 가정합니다.

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

컨테이너의 항목을 쿼리하려면 다음 메서드 중 하나를 호출합니다.

비동기적으로 SQL 쿼리를 사용하여 항목 쿼리

이 예제에서는 간단한 문자열을 사용하여 SQL 쿼리를 빌드하고 피드 반복기를 검색한 다음, 중첩된 루프를 사용하여 결과를 반복합니다. 외부 while 루프는 결과 페이지를 반복하는 반면 내부 foreach 루프는 페이지 내의 결과를 반복합니다.

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

Container.GetItemQueryIterator<> 메서드는 다중 페이지 결과를 반복하는 데 사용되는 FeedIterator<>를 반환합니다. HasMoreResults 속성은 더 많은 결과 페이지가 남아 있는지 여부를 나타냅니다. ReadNextAsync 메서드는 결과의 다음 페이지를 열거형으로 가져온 다음, 루프에서 사용하여 결과를 반복합니다.

또는 QueryDefinition을 사용하여 매개 변수화된 입력으로 SQL 쿼리를 빌드합니다.

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

매개 변수화된 입력 값은 많은 일반적인 SQL 쿼리 삽입 공격을 방지하는 데 도움이 될 수 있습니다.

LINQ를 비동기적으로 사용하여 항목 쿼리

이 예제에서는 IQueryable<> 개체를 사용하여 LINQ(Language Integrated Query)를 구성합니다. 그런 다음, 피드 반복기를 사용하여 결과를 반복합니다.

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

Container.GetItemLinqQueryable<> 메서드는 IQueryable을 생성하여 LINQ 쿼리를 빌드합니다. 그런 다음, ToFeedIterator<> 메서드를 사용하여 LINQ 쿼리 식을 FeedIterator<>로 변환합니다.

IQueryable<>을 통해 반복할 수 있지만 이 작업은 동기적입니다. ToFeedIterator<> 메서드를 사용하여 결과를 비동기적으로 수집합니다.

다음 단계

여러 항목을 쿼리했으므로 이제 API for NoSQL을 사용하여 엔드투엔드 자습서 중 하나를 사용해 보세요.