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에서 true로 설정합니다 EnableOptimisticDirectExecution .

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에서 false로 설정합니다 EnableOptimisticDirectExecution .
모든 노드에 대해 두 번째 배포의 일부로 ODE를 사용하도록 설정합니다.

로컬 쿼리 계획 생성 사용

SQL SDK에는 쿼리를 로컬로 구문 분석하고 최적화하는 네이티브 ServiceInterop.dll 포함되어 있습니다. ServiceInterop.dllWindows 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을 수동으로 복사하거나 사용자 지정 빌드/배포 시스템이 있는 경우에만 문제가 됩니다.

PartitionKey 속성을 QueryRequestOptions 설정하여 파티션 키를 대상으로 하고 집계를 포함하지 않는 쿼리의 경우(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를 실행하는 클라이언트에서 파티션 키는 항상 요청 옵션 개체에 지정되어야 합니다.

PartitionKey 속성을 FeedOptions 설정하여 파티션 키를 대상으로 하고 집계를 포함하지 않는 쿼리의 경우(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
V2 .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
        }
    }
}

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
V2 .NET SDK

쿼리의 경우, 특히 파티션 키 값에 대한 필터 없이 교차 파티션 쿼리를 수행하는 경우 에서 QueryRequestOptions 속성을 조정하여 애플리케이션에 가장 적합한 구성을 식별합니다. 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 }))
{
    // ...
}

쿼리의 경우 에서 FeedOptions 속성을 조정하여 특히 파티션 키 값에 대한 필터 없이 교차 파티션 쿼리를 수행하는 경우 애플리케이션에 가장 적합한 구성을 식별합니다. 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
V2 .NET SDK

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

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

또한 Azure Cosmos DB SDK를 사용하여 페이지 크기를 설정할 수도 있습니다. 의 FeedOptions 속성을 사용하면 열거 작업에서 반환할 최대 항목 수를 설정할 수 있습니다. MaxItemCount로 설정하면 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
V2 .NET SDK

병렬 쿼리는 현재 결과 일괄 처리가 클라이언트에서 처리되는 동안 결과를 프리페치하도록 설계되었습니다. 이 프리페치를 사용하면 쿼리의 전체 대기 시간을 향상시킬 수 있습니다. MaxBufferedItemCount 속성 QueryRequestOptions 은 프리페치된 결과의 수를 제한합니다. 쿼리가 프리페치를 통해 최대 혜택을 받을 수 있도록 반환된 예상 결과 수(또는 더 높은 수)로 설정합니다 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}))
{
    // ...
}

병렬 쿼리는 현재 결과 일괄 처리가 클라이언트에서 처리되는 동안 결과를 프리페치하도록 설계되었습니다. 이 프리페치를 사용하면 쿼리의 전체 대기 시간을 향상시킬 수 있습니다. MaxBufferedItemCount 속성 FeedOptions 은 프리페치된 결과의 수를 제한합니다. 쿼리가 프리페치를 통해 최대 혜택을 받을 수 있도록 반환된 예상 결과 수(또는 더 높은 수)로 설정합니다 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 게이트웨이에 대한 네트워크 요청은 쿼리 작업의 대기 시간에 추가됩니다.

쿼리 계획 캐싱 사용

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

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

setPartitionKeyCosmosQueryRequestOptions 가 포함된 파티션 키로 범위가 지정되고 집계(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);

참고 항목

병렬도 조정

병렬 쿼리는 여러 파티션을 병렬로 쿼리하여 작동합니다. 그러나 분할된 개별 컨테이너의 데이터는 쿼리와 관련하여 직렬로 가져옵니다. 따라서 에서 CosmosQueryRequestOptions을 사용하여 보유한 파티션 수로 값을 설정합니다. 파티션 수를 모르는 경우 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의 경우 pageSize, 비동기 API의 경우 iterableByPage()에서 byPage() 매개 변수를 사용하여 페이지 크기를 정의할 수 있습니다.

//  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();

버퍼 크기 조정

병렬 쿼리는 현재 결과 일괄 처리가 클라이언트에서 처리되는 동안 결과를 프리페치하도록 설계되었습니다. 프리페치를 사용하면 쿼리의 전반적인 대기 시간을 개선하는 데 도움이 됩니다. setMaxBufferedItemCount 는 CosmosQueryRequestOptions 프리페치된 결과의 수를 제한합니다. 프리페치를 최대화하려면 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 게이트웨이에 대한 네트워크 요청은 쿼리 작업의 대기 시간에 추가됩니다. 이 요청을 제거하고 단일 파티션 쿼리 작업의 대기 시간을 줄이는 방법이 있습니다. 단일 파티션 쿼리의 경우 항목의 파티션 키 값을 지정하고 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 게이트웨이에 대한 네트워크 요청은 쿼리 작업의 대기 시간에 추가됩니다. 이 요청을 제거하고 단일 파티션 쿼리 작업의 대기 시간을 줄이는 방법이 있습니다. 단일 파티션 쿼리의 경우 쿼리 범위를 단일 파티션으로 지정할 수 있습니다.

매개 변수화된 쿼리 식을 사용하고 쿼리 문에 파티션 키를 지정합니다. 쿼리는 프로그래밍 방식으로 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}`);
}

향상된 쿼리 컨트롤

Cosmos DB JS SDK 버전 4.3.0 이상 enableQueryControl 에서는 쿼리 실행을 보다 효과적으로 제어할 수 있는 플래그가 도입되어 RU(요청 단위) 사용을 보다 유연하게 관리할 수 있습니다.

기본적으로 enableQueryControl는 false로 설정되어 있으며, 백 엔드에 충분한 결과가 있는 경우 각 fetchNext 호출에서 maxItemCount개의 결과를 반환하도록 SDK가 보장합니다. 그러나 보장된 결과 수를 충족하기 위해 SDK는 백 엔드 파티션을 한 fetchNext 번의 반복으로 여러 번 쿼리할 수 있습니다. 이로 인해 특히 결과가 파티션에 분산되어 있는 경우 사용자 제어 없이 예측할 수 없는 대기 시간 및 RU 드레이닝이 발생할 수 있습니다.

enableQueryControl이 true로 설정되면, 각각의 fetchNext 호출은 이제 최대 maxDegreeOfParallelism개의 실제 파티션을 쿼리합니다. 결과가 없거나 결과를 아직 처리할 준비가 되지 않은 경우 SDK는 백그라운드에서 모든 파티션을 계속 검색하는 대신 빈 페이지를 반환합니다. 이렇게 하면 사용자는 예측 가능한 대기 시간 및 세분화된 RU 사용량 데이터를 사용하여 쿼리 실행을 보다 세부적으로 제어할 수 있습니다.

const options = {
  enableQueryControl: true, // Flag to enable new query pipeline.
  maxItemCount: 100,
  maxDegreeOfParallelism: 6
};

const querySpec = {
    query: "select * from products p where p.categoryId=@categoryId",
    parameters: [
        {
            name: "@categoryId",
            value: items[2].categoryId
        }
    ]
};
const queryIterator = container.items.query(querySpec, options);
// use this iterator to fetch results.

다음 단계

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-11

다음을 통해 공유

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

쿼리 계획 호출 줄이기

단일 파티션 쿼리를 낙관적 직접 실행 방식으로 최적화하기

로컬 쿼리 계획 생성 사용

단일 파티션 쿼리 사용

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

병렬도 조정

페이지 크기 조정

버퍼 크기 조정

다음 단계

쿼리 계획 호출 줄이기

쿼리 계획 캐싱 사용

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

병렬도 조정

페이지 크기 조정

버퍼 크기 조정

다음 단계

쿼리 플랜 호출 수 줄이기

페이지 크기 조정

다음 단계

쿼리 계획 호출 줄이기

페이지 크기 조정

향상된 쿼리 컨트롤

다음 단계

피드백

추가 리소스