Azure Cosmos DB SDK에 대한 쿼리 성능 팁

적용 대상: NoSQL

Azure Cosmos DB는 보장된 대기 시간과 처리량 수준으로 매끄럽게 크기가 조정되는 빠르고 유연한 분산 데이터베이스입니다. Azure Cosmos DB를 사용하여 데이터베이스를 스케일링하기 위해 주요 아키텍처를 변경하거나 복잡한 코드를 작성할 필요는 없습니다. 규모를 확장 및 축소하는 방법이 API 호출을 하나 만드는 것만큼 쉽습니다. 자세한 내용은 컨테이너 처리량 프로비저닝 또는 데이터베이스 처리량 프로비저닝을 참조하세요.

쿼리 계획 호출 줄이기

쿼리를 실행하려면 쿼리 계획을 세워야 합니다. 이는 일반적으로 쿼리 작업의 대기 시간을 추가하는 Azure Cosmos DB 게이트웨이에 대한 네트워크 요청을 나타냅니다. 이 요청을 제거하고 쿼리 작업의 대기 시간을 줄이는 두 가지 방법이 있습니다.

낙관적 직접 실행을 사용하여 단일 파티션 쿼리 최적화

Azure Cosmos DB NoSQL에는 특정 NoSQL 쿼리의 효율성을 향상시킬 수 있는 ODE(낙관적 직접 실행)라는 최적화가 있습니다. 특히 배포가 필요하지 않은 쿼리에는 단일 물리적 파티션에서 실행되거나 페이지 매김이 필요하지 않은 응답이 있는 쿼리가 포함됩니다. 배포가 필요하지 않은 쿼리는 클라이언트 쪽 쿼리 계획 생성 및 쿼리 다시 쓰기와 같은 일부 프로세스를 자신 있게 건너뛰어 쿼리 대기 시간과 RU 비용을 줄일 수 있습니다. 요청 또는 쿼리 자체에 파티션 키를 지정하고(또는 실제 파티션이 하나만 있는 경우) 쿼리 결과에 페이지 매김이 필요하지 않은 경우 ODE는 쿼리를 개선할 수 있습니다.

참고 항목

배포가 필요하지 않은 쿼리에 대해 향상된 성능을 제공하는 ODE(낙관적 직접 실행)는 응용 프로그램을 백 엔드 복제본에 연결하는 경로인 직접 모드와 혼동해서는 안 됩니다.

이제 .NET SDK 버전 3.38.0 이상에서 ODE를 사용할 수 있습니다. 쿼리를 실행하고 요청 또는 쿼리 자체에 파티션 키를 지정하거나 데이터베이스에 물리적 파티션이 하나만 있는 경우 쿼리 실행은 ODE의 이점을 활용할 수 있습니다. ODE를 활성화하려면 QueryRequestOptions에서 EnableOptimisticDirectExecution을 true로 설정합니다.

GROUP BY, ORDER BY, DISTINCT 및 집계 함수(예: 합계, 평균, 최소 및 최대) 기능을 갖춘 단일 파티션 쿼리는 ODE를 사용하면 상당한 이점을 얻을 수 있습니다. 그러나 쿼리가 여러 파티션을 대상으로 하거나 여전히 페이지 매김이 필요한 시나리오에서는 쿼리 응답의 대기 시간과 RU 비용이 ODE를 사용하지 않을 때보다 높을 수 있습니다. 따라서 ODE를 사용하는 경우 다음을 수행하는 것이 좋습니다.

• 호출 또는 쿼리 자체에서 파티션 키를 지정합니다.
• 데이터 크기가 증가하여 파티션이 분할되지 않았는지 확인합니다.
• ODE의 모든 이점을 얻기 위해 쿼리 결과에 페이지 매김이 필요하지 않은지 확인합니다.

다음은 ODE를 활용할 수 있는 간단한 단일 파티션 쿼리의 몇 가지 예입니다.

- SELECT * FROM r
- SELECT * FROM r WHERE r.pk == "value"
- SELECT * FROM r WHERE r.id > 5
- SELECT r.id FROM r JOIN id IN r.id
- SELECT TOP 5 r.id FROM r ORDER BY r.id
- SELECT * FROM r WHERE r.id > 5 OFFSET 5 LIMIT 3 

시간이 지남에 따라 데이터 항목 수가 증가하고 Azure Cosmos DB 데이터베이스가 파티션을 분할하는 경우 단일 파티션 쿼리에 여전히 배포가 필요할 수 있습니다. 이 문제가 발생할 수 있는 쿼리의 예는 다음과 같습니다.

- SELECT Count(r.id) AS count_a FROM r
- SELECT DISTINCT r.id FROM r
- SELECT Max(r.a) as min_a FROM r
- SELECT Avg(r.a) as min_a FROM r
- SELECT Sum(r.a) as sum_a FROM r WHERE r.a > 0 

일부 복잡한 쿼리는 단일 파티션을 대상으로 하는 경우에도 항상 배포가 필요할 수 있습니다. 이러한 쿼리의 예는 다음과 같습니다.

- SELECT Sum(id) as sum_id FROM r JOIN id IN r.id
- SELECT DISTINCT r.id FROM r GROUP BY r.id
- SELECT DISTINCT r.id, Sum(r.id) as sum_a FROM r GROUP BY r.id
- SELECT Count(1) FROM (SELECT DISTINCT r.id FROM root r)
- SELECT Avg(1) AS avg FROM root r 

ODE가 항상 쿼리 계획을 검색하지 못할 수 있으므로 지원되지 않는 쿼리를 허용하지 않거나 해제할 수 없다는 점에 유의해야 합니다. 예를 들어 파티션 분할 후 이러한 쿼리는 더 이상 ODE에 적합하지 않으므로 클라이언트 쪽 쿼리 계획 평가에서 이러한 쿼리를 차단하므로 실행되지 않습니다. 호환성/서비스 연속성을 보장하려면 ODE가 없는 시나리오에서 완전히 지원되는 쿼리(즉, 일반적인 다중 파티션 사례에서 올바른 결과를 실행하고 생성)만 ODE와 함께 사용하는 것이 중요합니다.

참고 항목

ODE를 사용하면 잠재적으로 새 유형의 연속 토큰이 생성될 수 있습니다. 이러한 토큰은 의도적으로 이전 SDK에서 인식되지 않으며 이로 인해 형식이 잘못된 연속 토큰 예외가 발생할 수 있습니다. 최신 SDK에서 생성된 토큰이 이전 SDK에서 사용되는 시나리오가 있는 경우 업그레이드하기 위한 2단계 방법을 사용하는 것이 좋습니다.

• 단일 배포의 일부로 새 SDK로 업그레이드하고 ODE를 사용하지 않도록 설정합니다. 모든 노드가 업그레이드될 때까지 기다립니다.
  • ODE를 사용하지 않도록 설정하려면 QueryRequestOptions에서 EnableOptimisticDirectExecution을 false로 설정합니다.
• 모든 노드에 대해 두 번째 배포의 일부로 ODE를 사용하도록 설정합니다.

로컬 쿼리 계획 세대 사용

SQL SDK에는 로컬에서 쿼리를 구문 분석하고 최적화하는 네이티브 ServiceInterop.dll이 포함되어 있습니다. ServiceInterop.dll은 Windows x64 플랫폼에서만 지원됩니다. 다음 유형의 애플리케이션은 기본적으로 32비트 호스트 처리를 사용합니다. 호스트 처리를 64비트 처리로 변경하려면 애플리케이션 유형에 따라 다음 단계를 따르세요.

• 실행 가능한 애플리케이션의 경우 프로젝트 속성 창의 빌드 탭에서 플랫폼 대상을 x64로 설정하여 호스트 처리를 변경할 수 있습니다.

• VSTest 기반 테스트 프로젝트의 경우 Visual Studio 테스트 메뉴에서 테스트>테스트 설정>기본 프로세서 아키텍처를 X64로 설정을 선택하여 호스트 처리를 변경할 수 있습니다.

• 로컬로 배포된 ASP.NET 웹 애플리케이션의 경우 도구>옵션>프로젝트 및 솔루션>웹 프로세스에서 웹 사이트 및 프로젝트에 64비트 버전의 IIS Express 사용을 선택하면 호스트 처리를 변경할 수 있습니다.

• Azure에 배포된 ASP.NET 웹 애플리케이션의 경우 Azure Portal의 애플리케이션 설정에서 64비트 플랫폼을 선택하여 호스트 처리를 변경할 수 있습니다.

참고 항목

기본적으로 새 Visual Studio 프로젝트는 임의 CPU로 설정됩니다. x86으로 전환되지 않도록 프로젝트를 x64로 설정하는 것이 좋습니다. 모든 CPU로 설정된 프로젝트는 x86 전용 종속성이 추가되면 x86으로 쉽게 전환할 수 있습니다.
ServiceInterop.dll은 SDK DLL이 실행되는 폴더에 있어야 합니다. 이는 DLL을 수동으로 복사하거나 사용자 지정 빌드/배포 시스템이 있는 경우에만 문제가 됩니다.

단일 파티션 쿼리 사용

V3 .NET SDK

QueryRequestOptions에서 PartitionKey 속성을 설정하여 파티션 키를 대상으로 하고 집계(Distinct, DCount, Group By 등)를 포함하지 않는 쿼리의 경우. 이 예에서는 /state의 파티션 키 필드가 Washington 값으로 필터링됩니다.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle' AND c.state = 'Washington'"
{
    // ...
}

선택적으로 요청 옵션 개체의 일부로 파티션 키를 제공할 수 있습니다.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    // ...
}

Important

Linux 및 MacOS와 같은 비 Windows OS를 실행하는 클라이언트에서 파티션 키는 항상 요청 옵션 개체에 지정되어야 합니다.

V2 .NET SDK

FeedOptions에서 PartitionKey 속성을 설정하여 파티션 키를 대상으로 하고 집계(Distinct, DCount, Group By 등)를 포함하지 않는 쿼리의 경우:

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        PartitionKey = new PartitionKey("Washington")
    }).AsDocumentQuery();

참고 항목

교차 파티션 쿼리를 사용하려면 SDK가 모든 기존 파티션을 방문하여 결과를 확인해야 합니다. 컨테이너에 실제 파티션이 많을수록 잠재적으로 느려질 수 있습니다.

불필요하게 반복기를 다시 만들지 마세요.

모든 쿼리 결과가 현재 구성 요소에서 사용되는 경우 모든 페이지에 대한 연속으로 반복기를 다시 만들 필요가 없습니다. 페이지 매김이 다른 호출 구성 요소에 의해 제어되지 않는 한 항상 쿼리를 완전히 배출하는 것을 기본 설정합니다.

V3 .NET SDK

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { PartitionKey = new PartitionKey("Washington")}))
{
    while (feedIterator.HasMoreResults) 
    {
        foreach(MyItem document in await feedIterator.ReadNextAsync())
        {
            // Iterate through documents
        }
    }
}

V2 .NET SDK

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        PartitionKey = new PartitionKey("Washington")
    }).AsDocumentQuery();
while (query.HasMoreResults) 
{
    foreach(Document document in await queryable.ExecuteNextAsync())
    {
        // Iterate through documents
    }
}

병렬도 조정

V3 .NET SDK

쿼리의 경우, 특히 파티션 키 값에 대한 필터 없이 교차 파티션 쿼리를 수행하는 경우 QueryRequestOptions에서 MaxConcurrency 속성을 조정하여 애플리케이션에 가장 적합한 구성을 식별합니다. MaxConcurrency는 최대 병렬 작업 수, 즉 병렬로 방문할 최대 파티션 수를 제어합니다. 값을 -1로 설정하면 SDK가 최적의 동시성을 결정할 수 있습니다.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxConcurrency = -1 }))
{
    // ...
}

V2 .NET SDK

쿼리의 경우 FeedOptions에서 MaxDegreeOfParallelism 속성을 조정하여 특히 파티션 키 값에 대한 필터 없이 교차 파티션 쿼리를 수행하는 경우 애플리케이션에 가장 적합한 구성을 식별합니다. MaxDegreeOfParallelism는 최대 병렬 작업 수, 즉 병렬로 방문할 최대 파티션 수를 제어합니다. 값을 -1로 설정하면 SDK가 최적의 동시성을 결정할 수 있습니다.

IDocumentQuery<dynamic> query = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT * FROM c WHERE c.city = 'Seattle'", 
    new FeedOptions 
    { 
        MaxDegreeOfParallelism = -1, 
        EnableCrossPartitionQuery = true 
    }).AsDocumentQuery();

다음을 가정해보세요.

• D = 기본 최대 병렬 작업 수(= 클라이언트 컴퓨터의 총 프로세서 수)
• P = 사용자 지정 최대 병렬 작업 수
• N = 쿼리 응답을 위해 방문해야 하는 파티션 수

다음은 병렬 쿼리가 P의 여러 다른 값에 대해 어떻게 작동하는지를 나타냅니다.

• (P == 0) => 직렬 모드
• (P == 1) => 한 작업의 최대
• (P > 1) => 최소(P, N) 병렬 작업
• (P < 1) => 최소(N, D) 병렬 작업

페이지 크기 조정

SQL 쿼리를 실행할 때 결과 집합이 너무 크면 결과가 분할된 방식으로 반환됩니다.

참고 항목

MaxItemCount 속성은 페이지 매김에만 사용하는 것이 아닙니다. 주요 용도는 단일 페이지에서 반환되는 최대 항목 수를 줄여 쿼리 성능을 향상시키는 것입니다.

V3 .NET SDK

또한 Azure Cosmos DB SDK를 사용하여 페이지 크기를 설정할 수도 있습니다. QueryRequestOptions의 MaxItemCount 속성을 사용하면 열거 작업에서 반환할 최대 항목 수를 설정할 수 있습니다. MaxItemCount가 -1로 설정되면 SDK는 문서 크기에 따라 최적의 값을 자동으로 찾습니다. 예시:

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxItemCount = 1000}))
{
    // ...
}

V2 .NET SDK

또한 Azure Cosmos DB SDK를 사용하여 페이지 크기를 설정할 수도 있습니다. FeedOptions의 MaxItemCount 속성을 사용하면 열거 작업에서 반환할 최대 항목 수를 설정할 수 있습니다. MaxItemCount가 -1로 설정되면 SDK는 문서 크기에 따라 최적의 값을 자동으로 찾습니다. 예시:

IQueryable<dynamic> authorResults = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", 
    new FeedOptions { MaxItemCount = 1000 });

쿼리가 실행되면 결과 데이터가 TCP 패킷 내에서 전송됩니다. MaxItemCount 값을 너무 낮게 지정하면 TCP 패킷 내에서 데이터를 전송하는 데 필요한 이동 횟수가 많아져 성능에 영향을 줍니다. 따라서 MaxItemCount 속성에 대해 어떤 값을 설정할지 확실하지 않은 경우 -1로 설정하고 SDK가 기본값을 선택하도록 하는 것이 가장 좋습니다.

버퍼 크기 조정

V3 .NET SDK

병렬 쿼리는 클라이언트에서 현재 결과 일괄 처리를 처리하는 동안 결과를 프리페치하도록 설계되었습니다. 프리페치를 사용하면 쿼리의 전체 대기 시간을 단축할 수 있습니다. QueryRequestOptions의 MaxBufferedItemCount 속성은 미리 가져온 결과 수를 제한합니다. MaxBufferedItemCount를 반환된 결과의 예상 수(또는 더 높은 숫자)로 설정하면 쿼리가 프리페치의 최대 이점을 얻을 수 있습니다. 이 값을 -1로 설정하면 시스템이 버퍼링할 항목 수를 자동으로 결정합니다.

using (FeedIterator<MyItem> feedIterator = container.GetItemQueryIterator<MyItem>(
    "SELECT * FROM c WHERE c.city = 'Seattle'",
    requestOptions: new QueryRequestOptions() { 
        PartitionKey = new PartitionKey("Washington"),
        MaxBufferedItemCount = -1}))
{
    // ...
}

V2 .NET SDK

병렬 쿼리는 클라이언트에서 현재 결과 일괄 처리를 처리하는 동안 결과를 프리페치하도록 설계되었습니다. 프리페치를 사용하면 쿼리의 전체 대기 시간을 단축할 수 있습니다. FeedOptions의 MaxBufferedItemCount 속성은 미리 가져온 결과 수를 제한합니다. MaxBufferedItemCount를 반환된 결과의 예상 수(또는 더 높은 숫자)로 설정하면 쿼리가 프리페치의 최대 이점을 얻을 수 있습니다. 이 값을 -1로 설정하면 시스템이 버퍼링할 항목 수를 자동으로 결정합니다.

IQueryable<dynamic> authorResults = client.CreateDocumentQuery(
    UriFactory.CreateDocumentCollectionUri(DatabaseName, CollectionName), 
    "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", 
    new FeedOptions { MaxBufferedItemCount = -1 });

프리페치는 병렬 처리 수준과 관계없이 같은 방식으로 작동하고, 모든 파티션의 데이터를 위한 단일 버퍼가 있습니다.

다음 단계

.NET SDK를 사용한 성능에 대해 자세히 알아보려면:

• Azure Cosmos DB .NET SDK에 대한 모범 사례
• Azure Cosmos DB .NET V3 SDK에 대한 성능 팁
• Azure Cosmos DB .NET V2 SDK에 대한 성능 팁

쿼리 계획 호출 줄이기

쿼리를 실행하려면 쿼리 계획을 세워야 합니다. 이는 일반적으로 쿼리 작업의 대기 시간을 추가하는 Azure Cosmos DB 게이트웨이에 대한 네트워크 요청을 나타냅니다.

쿼리 계획 캐싱 사용

단일 파티션으로 범위가 지정된 쿼리에 대한 쿼리 계획은 클라이언트에서 캐시됩니다. 이렇게 하면 첫 번째 호출 후 쿼리 계획을 쿼리하기 위해 게이트웨이를 호출할 필요가 없습니다. 캐시된 쿼리 계획의 핵심은 SQL 쿼리 문자열입니다. 쿼리가 매개 변수화되었는지 확인해야 합니다. 그렇지 않은 경우 쿼리 문자열이 호출 간에 동일하지 않을 가능성이 높기 때문에 쿼리 계획 캐시 조회는 종종 캐시 누락이 됩니다. 쿼리 계획 캐싱은 Java SDK 버전 4.20.0 이상 및 Spring Datan Azure Cosmos DB SDK 버전 3.13.0 이상에서 기본적으로 사용하도록 설정됩니다.

매개 변수화된 단일 파티션 쿼리 사용

CosmosQueryRequestOptions에서 setPartitionKey가 있는 파티션 키로 범위가 지정되고 집계(Distinct, DCount, Group By 등)가 포함되지 않은 매개 변수화된 쿼리의 경우 쿼리 계획을 방지할 수 있습니다.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));

ArrayList<SqlParameter> paramList = new ArrayList<SqlParameter>();
paramList.add(new SqlParameter("@city", "Seattle"));
SqlQuerySpec querySpec = new SqlQuerySpec(
        "SELECT * FROM c WHERE c.city = @city",
        paramList);

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

참고 항목

교차 파티션 쿼리를 사용하려면 SDK가 모든 기존 파티션을 방문하여 결과를 확인해야 합니다. 컨테이너에 실제 파티션이 많을수록 잠재적으로 느려질 수 있습니다.

병렬도 조정

병렬 쿼리는 여러 파티션을 병렬로 쿼리하여 작동합니다. 그러나 분할된 개별 컨테이너의 데이터는 쿼리와 관련하여 직렬로 가져옵니다. 따라서 CosmosQueryRequestOptions에서 setMaxDegreeOfParallelism을 사용하여 보유한 파티션 수로 값을 설정합니다. 파티션 수를 모르는 경우 setMaxDegreeOfParallelism을 사용하여 높은 수를 설정할 수 있으며 시스템은 최솟값(파티션 수, 사용자 제공 입력)을 최대 병렬 처리도로 선택합니다. 값을 -1로 설정하면 SDK가 최적의 동시성을 결정할 수 있습니다.

데이터가 쿼리와 관련하여 모든 파티션에 균등하게 분산되어 있는 경우 병렬 쿼리가 최고의 성능을 발휘한다는 것이 중요합니다. 파티션된 컨테이너가 쿼리에 의해 반환된 데이터의 전부 또는 대부분이 몇 개의 파티션(최악의 경우 하나의 파티션)에 집중되는 방식으로 파티션된 경우 쿼리의 성능이 저하됩니다.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxDegreeOfParallelism(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

다음을 가정해보세요.

• D = 기본 최대 병렬 작업 수(= 클라이언트 컴퓨터의 총 프로세서 수)
• P = 사용자 지정 최대 병렬 작업 수
• N = 쿼리 응답을 위해 방문해야 하는 파티션 수

다음은 병렬 쿼리가 P의 여러 다른 값에 대해 어떻게 작동하는지를 나타냅니다.

• (P == 0) => 직렬 모드
• (P == 1) => 한 작업의 최대
• (P > 1) => 최소(P, N) 병렬 작업
• (P == -1) => 최소(N, D) 병렬 작업

페이지 크기 조정

SQL 쿼리를 실행할 때 결과 집합이 너무 크면 결과가 분할된 방식으로 반환됩니다. 기본적으로, 100개의 항목 또는 4MB 단위(둘 중 먼저 도달하는 단위)로 결과가 반환됩니다. 페이지 크기를 늘리면 필요한 왕복 수가 줄어들고 100개 이상의 항목을 반환하는 쿼리의 성능이 향상됩니다. 어떤 값을 설정할지 잘 모르는 경우 일반적으로 1000을 선택하는 것이 좋습니다. 페이지 크기가 증가함에 따라 메모리 사용량이 증가하므로 워크로드가 메모리에 민감한 경우 더 낮은 값을 고려합니다.

동기화 API의 경우 iterableByPage(), 비동기 API의 경우 byPage()에서 pageSize 매개 변수를 사용하여 페이지 크기를 정의할 수 있습니다.

//  Sync API
Iterable<FeedResponse<MyItem>> filteredItemsAsPages =
    container.queryItems(querySpec, options, MyItem.class).iterableByPage(continuationToken,pageSize);

for (FeedResponse<MyItem> page : filteredItemsAsPages) {
    for (MyItem item : page.getResults()) {
        //...
    }
}

//  Async API
Flux<FeedResponse<MyItem>> filteredItemsAsPages =
    asyncContainer.queryItems(querySpec, options, MyItem.class).byPage(continuationToken,pageSize);

filteredItemsAsPages.map(page -> {
    for (MyItem item : page.getResults()) {
        //...
    }
}).subscribe();

버퍼 크기 조정

병렬 쿼리는 클라이언트에서 현재 결과 일괄 처리를 처리하는 동안 결과를 프리페치하도록 설계되었습니다. 프리페치는 쿼리의 전체 대기 시간 개선 사항에 도움이 됩니다. CosmosQueryRequestOptions의 setMaxBufferedItemCount는 미리 가져온 결과의 수를 제한합니다. 사전 페치를 최대화하려면 maxBufferedItemCount을(를) pageSize보다 높은 숫자로 설정합니다(참고: 메모리 사용량이 높을 수도 있음). 사전 페치를 최소화하려면 maxBufferedItemCount을(를) pageSize(으)로 설정합니다. 이 값을 0으로 설정하면 시스템이 버퍼링할 항목 수를 자동으로 결정합니다.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
options.setPartitionKey(new PartitionKey("Washington"));
options.setMaxBufferedItemCount(-1);

// Define the query

//  Sync API
CosmosPagedIterable<MyItem> filteredItems = 
    container.queryItems(querySpec, options, MyItem.class);

//  Async API
CosmosPagedFlux<MyItem> filteredItems = 
    asyncContainer.queryItems(querySpec, options, MyItem.class);

프리페치는 병렬 처리 수준과 관계없이 같은 방식으로 작동하고, 모든 파티션의 데이터를 위한 단일 버퍼가 있습니다.

다음 단계

Java SDK를 사용한 성능에 대해 자세히 알아보려면:

• Azure Cosmos DB Java V4 SDK 모범 사례
• Azure Cosmos DB Java V4 SDK에 대한 성능 팁

쿼리 계획 호출 줄이기

쿼리를 실행하려면 쿼리 계획을 세워야 합니다. 이는 일반적으로 쿼리 작업의 대기 시간을 추가하는 Azure Cosmos DB 게이트웨이에 대한 네트워크 요청을 나타냅니다. 이 요청을 제거하고 단일 파티션 쿼리 작업의 대기 시간을 줄이는 방법이 있습니다. 단일 파티션 쿼리의 경우 항목의 파티션 키 값을 지정하고 partition_key 인수로 전달합니다.

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington"
    )

페이지 크기 조정

SQL 쿼리를 실행할 때 결과 집합이 너무 크면 결과가 분할된 방식으로 반환됩니다. max_item_count를 사용하면 열거형 작업에서 반환할 최대 항목 수를 설정할 수 있습니다.

items = container.query_items(
        query="SELECT * FROM r where r.city = 'Seattle'",
        partition_key="Washington",
        max_item_count=1000
    )

다음 단계

NoSQL용 Python SDK for API를 사용하는 방법에 대해 자세히 알아보려면 다음을 수행합니다.

• Azure Cosmos DB Python SDK for API for NoSQL
• 빠른 시작: Python용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리

쿼리 계획 호출 줄이기

쿼리를 실행하려면 쿼리 계획을 세워야 합니다. 이는 일반적으로 쿼리 작업의 대기 시간을 추가하는 Azure Cosmos DB 게이트웨이에 대한 네트워크 요청을 나타냅니다. 이 요청을 제거하고 단일 파티션 쿼리 작업의 대기 시간을 줄이는 방법이 있습니다. 단일 파티션 쿼리의 경우 단일 파티션에 대한 쿼리 범위 지정을 두 가지 방법으로 수행할 수 있습니다.

매개 변수화된 쿼리 식을 사용하고 쿼리 문에 파티션 키를 지정합니다. 쿼리는 프로그래밍 방식으로 SELECT * FROM todo t WHERE t.partitionKey = 'Bikes, Touring Bikes'로 구성됩니다.

// find all items with same categoryId (partitionKey)
const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: "Bikes, Touring Bikes"
        }
    ]
};

// Get items 
const { resources } = await container.items.query(querySpec).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

또는 partitionKey를 FeedOptions에 지정하고 인수로 전달합니다.

const querySpec = {
    query: "select * from products p"
};

const { resources } = await container.items.query(querySpec, { partitionKey: "Bikes, Touring Bikes" }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

페이지 크기 조정

SQL 쿼리를 실행할 때 결과 집합이 너무 크면 결과가 분할된 방식으로 반환됩니다. maxItemCount를 사용하면 열거형 작업에서 반환할 최대 항목 수를 설정할 수 있습니다.

const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: items[2].categoryId
        }
    ]
};

const { resources } = await container.items.query(querySpec, { maxItemCount: 1000 }).fetchAll();

for (const item of resources) {
    console.log(`${item.id}: ${item.name}, ${item.sku}`);
}

다음 단계

NoSQL용 Node.js SDK for API를 사용하는 방법에 대해 자세히 알아보려면 다음을 수행합니다.

• Azure Cosmos DB Node.js SDK for API for NoSQL
• 빠른 시작: Node.js용 Azure Cosmos DB for NoSQL 클라이언트 라이브러리