Azure Cosmos DB의 계층적 파티션 키

아티클
08/15/2024

적용 대상: NoSQL

Azure Cosmos DB는 수평적 크기 조정을 지원하기 위해 파티션 키를 기반으로 논리 파티션 및 물리 파티션에 데이터를 분산합니다. 계층적 파티션 키(하위 분할이라고도 함)를 사용하면 파티션 키에 대해 최대 세 개 수준의 계층 구조를 구성하여 데이터 배포를 더 최적화하고 더 높은 수준의 크기 조정을 구현할 수 있습니다.

현재 가상 키를 사용하고 파티션 키가 20GB의 데이터를 초과할 수 있는 시나리오가 있거나 각 테넌트의 문서가 자체 논리 파티션에 매핑되도록 하려는 경우 하위 분할이 도움이 될 수 있습니다. 이 기능을 사용하는 경우 논리 파티션 키 접두사는 초당 20GB 및 10,000RU/s(초당 요청 단위)를 초과할 수 있습니다. 접두사별 쿼리는 데이터를 보유하는 파티션의 하위 집합으로 효율적으로 라우팅됩니다.

계층적 파티션 키 선택

다중 테넌트 애플리케이션이 있고 현재 파티션 키로 테넌트를 격리하는 경우 계층적 파티션이 도움이 될 수 있습니다. 계층적 파티션을 사용하면 논리 파티션 키 제한인 20GB 이상으로 확장할 수 있으며, 각 테넌트의 문서를 무한대로 확장할 수 있도록 하려는 경우 좋은 솔루션입니다. 현재 파티션 키 또는 단일 파티션 키가 자주 20GB에 도달하는 경우 계층적 파티션은 워크로드에 적합한 선택입니다.

그러나 워크로드의 성격과 첫 번째 수준 키가 얼마나 중요한지에 따라 계층적 파티션 시나리오 페이지에서 자세히 다루는 몇 가지 장단점이 있을 수 있습니다.

계층적 파티션 키의 각 수준을 선택할 때 다음과 같은 일반적인 분할 개념을 염두에 두고 각 개념이 워크로드에 어떤 영향을 미칠 수 있는지 이해해야 합니다.

모든 컨테이너의 경우 계층 파티션 키의 전체 경로(첫 번째 수준부터 시작)의 각 수준은 다음을 수행해야 합니다.
- 높은 카디널리티를 갖습니다. 계층 파티션의 첫 번째, 두 번째 및 세 번째 키(해당하는 경우)에는 모두 가능한 광범위한 값이 있어야 합니다.
  - 계층적 파티션 키의 첫 번째 수준에서 카디널리티가 낮으면 수집 시 모든 쓰기 작업이 50GB에 도달하고 두 개의 실제 파티션으로 분할될 때까지 하나의 실제 파티션으로 제한됩니다. 예를 들어, 첫 번째 수준 키가 TenantId에 있고 고유한 테넌트가 5개만 있다고 가정합니다. 이러한 각 테넌트의 작업 범위는 하나의 실제 파티션으로만 제한되므로 처리량 사용량은 해당 하나의 실제 파티션에 있는 것만으로 제한됩니다. 계층적 파티션은 전체 팬아웃 쿼리를 방지하기 위해 동일한 1차 키를 가진 모든 문서가 동일한 실제 파티션에 함께 배치되도록 최적화하기 때문입니다.
  - 이는 모든 테넌트의 데이터를 일회성으로 수집하고 이후에 다음 작업이 주로 읽기 작업이 많은 워크로드에는 괜찮을 수 있지만 비즈니스 요구 사항에 특정 시간 내에 데이터를 수집해야 하는 워크로드에는 적합하지 않을 수 있습니다. 예를 들어, 대기 시간을 방지하기 위한 엄격한 비즈니스 요구 사항이 있는 경우 워크로드가 이론적으로 데이터를 수집하기 위해 달성할 수 있는 최대 처리량은 실제 파티션 수 * 10k입니다. 최상위 키의 카디널리티가 낮은 경우 완료하는 데 4~6시간이 걸릴 수 있는 분할 후 여러 파티션에 분산될 수준 1 키에 대한 충분한 데이터가 없는 한 실제 파티션 수는 1이 될 가능성이 높습니다.
- 모든 논리 파티션에 RU(요청 단위) 사용량과 데이터 스토리지를 균등하게 분산합니다. 이 분산을 통해 실제 파티션에서 균등한 RU 사용량과 스토리지 배포가 가능합니다.
  - UserId와 같이 카디널리티가 높은 것처럼 보이는 첫 번째 수준 키를 선택했지만 실제로는 워크로드가 하나의 특정 UserId에서만 작업을 수행하는 경우 모든 작업의 범위가 하나 또는 몇 개의 실제 파티션으로 제한되므로 핫 파티션으로 실행될 수 있습니다.
읽기가 많은 워크로드: 쿼리에 자주 나타나는 계층적 파티션 키를 선택하는 것이 좋습니다.
- 예를 들어 다중 테넌트 애플리케이션에서 특정 사용자 세션을 필터링하기 위해 쿼리를 자주 실행하는 워크로드는 TenantId, UserId 및 SessionId의 계층적 파티션 키를 순서대로 활용할 수 있습니다. 필터 조건자에 파티션 키를 포함하여 쿼리를 관련 물리 파티션에만 효율적으로 라우팅할 수 있습니다. 읽기 작업이 많은 워크로드에 대한 파티션 키를 선택하는 방법에 대한 자세한 내용은 분할 개요를 참조하세요.
쓰기가 많은 워크로드: 계층적 파티션 키의 첫 번째 수준에 대해 높은 기본값을 사용하는 것이 좋습니다. 높은 카디널리티는 첫 번째 수준 키(및 후속 수준)에 최소 수천 개의 고유 값이 있고 실제 파티션 수보다 더 많은 고유 값이 있음을 의미합니다.
- 예를 들어, 파티션 키로 테넌트를 격리하는 워크로드가 있고 다른 테넌트보다 쓰기가 더 많은 대규모 테넌트가 몇 개 있다고 가정해 보겠습니다. 현재 Azure Cosmos DB는 데이터가 20GB를 초과하는 경우 모든 파티션 키 값에 대한 데이터 수집을 중지합니다. 이 워크로드에서 Microsoft와 Contoso는 대규모 테넌트이므로 다른 테넌트보다 훨씬 빠르게 성장할 것으로 예상됩니다. 이러한 테넌트에 대한 데이터를 수집할 수 없는 위험을 방지하기 위해 계층적 파티션 키를 사용하면 이러한 테넌트를 20GB 한도 이상으로 크기 조정할 수 있습니다. 테넌트 전체에서 더 높은 확장성을 보장하기 위해 UserId 및 SessionId와 같은 수준을 더 추가할 수 있습니다.
- 워크로드가 동일한 첫 번째 수준 키를 사용하는 모든 문서에 대한 쓰기를 수용할 수 있도록 하려면 항목 ID를 두 번째 또는 세 번째 수준 키로 사용하는 것이 좋습니다.
- 첫 번째 수준의 카디널리티가 높지 않고 현재 파티션 키의 논리 파티션 제한이 20GB에 도달하는 경우 계층적 파티션 키 대신 가상 파티션 키를 사용하는 것이 좋습니다.

사용 사례

각 테넌트의 사용자에 대한 이벤트 정보를 저장하는 다중 테넌트 시나리오가 있다고 가정합니다. 이벤트 정보에는 로그인, 클릭스트림 또는 결제 이벤트를 포함하되 이에 국한되지 않는 이벤트 발생이 포함될 수 있습니다.

실제 시나리오에서 일부 테넌트는 수천 명의 사용자로 크게 확장할 수 있지만, 다른 많은 테넌트는 규모가 작고 사용자가 적습니다. /TenantId로 분할하면 단일 논리 파티션에서 Azure Cosmos DB 20GB 스토리지 제한을 초과할 수 있습니다. /UserId로 분할하면 테넌트 교차 파티션에 대한 모든 쿼리가 만들어집니다. 두 방법 모두에는 심각한 단점이 있습니다.

TenantId와 UserId를 결합한 가상 파티션 키를 사용하면 애플리케이션이 복잡해집니다. 또한 모든 사용자를 미리 알고 지정하는 경우를 제외하고 한 테넌트에 대한 가상 파티션 키 쿼리는 여전히 파티션 간 쿼리입니다.

워크로드에 거의 동일한 워크로드 패턴을 가진 테넌트가 있는 경우 계층적 파티션 키가 도움이 될 수 있습니다. 계층적 파티션 키를 사용하면 먼저 TenantId에서 분할한 다음, UserId에서 분할할 수 있습니다. TenantId 및 UserId 조합이 20GB를 초과하는 파티션을 생성할 것으로 예상되는 경우 SessionId와 같은 다른 수준으로 더 아래로 파티션을 분할할 수도 있습니다. 전체 깊이는 세 수준을 초과할 수 없습니다. 실제 파티션이 50GB의 스토리지를 초과하는 경우 Azure Cosmos DB는 실제 파티션을 자동으로 분할하여 데이터의 약 절반이 한 실제 파티션에 있고, 나머지 절반은 다른 실제 파티션에 있습니다. 사실상 하위 분할은 단일 TenantId 값에서 20GB의 데이터를 초과할 수 있으며, 이는 TenantId 데이터가 여러 실제 파티션에 걸쳐 있을 수 있음을 의미합니다.

TenantId 또는 TenantId와 UserId 모두를 지정하는 쿼리는 관련 데이터가 포함된 실제 파티션의 하위 집합에만 효율적으로 라우팅됩니다. 전체 또는 접두사로 하위 분할된 파티션 키 경로를 지정하면 전체 팬아웃 쿼리를 효과적으로 방지할 수 있습니다. 예를 들어 컨테이너에 1,000개의 실제 파티션이 있지만 특정 TenantId 값이 5개의 실제 파티션에만 있는 경우 쿼리는 더 적은 수의 관련 실제 파티션으로 라우팅됩니다.

계층 구조에서 항목 ID 사용

컨테이너에 가능한 값의 범위가 큰 속성이 있는 경우 속성은 계층의 마지막 수준에 대한 훌륭한 파티션 키 선택일 수 있습니다. 이러한 유형의 속성 중 가능한 한 가지 예는 항목 ID입니다. 컨테이너의 모든 항목에 시스템 속성 항목 ID가 있습니다. 항목 ID를 다른 수준으로 추가하면 논리 파티션 키 제한인 20GB를 초과하여 크기를 조정할 수 있습니다. 첫 번째 수준 또는 키의 첫 번째 및 두 번째 수준에 대해 이 제한을 초과하여 크기 조정할 수 있습니다.

예를 들어 TenantId 및 UserId로 분할된 다중 테넌트 워크로드에 대한 컨테이너가 있을 수 있습니다. TenantId 및 UserId의 단일 조합이 20GB를 초과할 수 있는 경우 세 가지 수준의 키 및 높은 카디널리티를 가진 세 번째 키를 사용하여 분할하는 것이 좋습니다. 이 시나리오의 예로는 세 번째 수준 키가 기본적으로 높은 카디널리티를 갖는 GUID인 경우입니다. TenantId, UserId 및 GUID의 조합이 20GB를 초과할 가능성은 거의 없으므로 TenantId 및 UserId의 조합이 20GB를 초과하여 효과적으로 크기 조정될 수 있습니다.

항목 ID를 파티션 키로 사용하는 방법에 대한 자세한 내용은 분할 개요를 참조하세요.

시작하기

Important

계층적 파티션 키를 사용하는 컨테이너 작업은 다음 SDK 버전에서만 지원됩니다. 계층적 파티션 키를 사용하여 새 컨테이너를 만들고 데이터에 대한 CRUD(만들기, 읽기, 업데이트 및 삭제기) 또는 쿼리 작업을 수행하려면 지원되는 SDK를 사용해야 합니다. 현재 지원되지 않는 SDK 또는 커넥터를 사용하려면 커뮤니티 포럼에 요청을 제출하세요.

지원되는 각 SDK의 최신 미리 보기 버전을 찾습니다.

SDK	지원되는 버전	패키지 관리자 링크
.NET SDK v3	>= 3.33.0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Java SDK v4	>= 4.42.0	https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md#4420-2023-03-17/
JavaScript SDK v4	4.0.0	https://www.npmjs.com/package/@azure/cosmos/
Python SDK	>= 4.6.0	https://pypi.org/project/azure-cosmos/4.6.0/

계층적 파티션 키를 사용하여 컨테이너 만들기

시작하려면 최대 3개 수준의 깊이까지 미리 정의된 하위 분할 키 경로 목록을 사용하여 새 컨테이너를 만듭니다.

다음 옵션 중 하나를 사용하여 새 컨테이너를 만들 수 있습니다.

Azure Portal
SDK
Azure Resource Manager 템플릿
Azure Cosmos DB 에뮬레이터

Azure Portal

컨테이너를 만들고 계층적 파티션 키를 지정하는 가장 간단한 방법은 Azure Portal을 사용하는 것입니다.

Azure Portal에 로그인합니다.
기존 Azure Cosmos DB for NoSQL 계정 페이지로 이동합니다.
왼쪽 메뉴에서 Data Explorer를 선택합니다.
Data Explorer에서 새 컨테이너 옵션을 선택합니다.
새 컨테이너에서 파티션 키에 /TenantId를 입력합니다. 나머지 필드의 경우 시나리오와 일치하는 값을 입력합니다.

참고 항목

여기서는 /TenantId를 예제로 사용합니다. 자체 컨테이너에서 계층적 파티션 키를 구현할 때 첫 번째 수준에 대한 키를 지정할 수 있습니다.
계층적 파티션 키 추가를 두 번 선택합니다.
하위 분할의 두 번째 및 세 번째 계층에 대해 각각 /UserId 및 /SessionId를 입력합니다.
확인을 선택하여 컨테이너를 만듭니다.

SDK

SDK를 사용하여 새 컨테이너를 만드는 경우 최대 세 개 깊이 수준의 하위 분할 키 경로 목록을 정의합니다. 새 컨테이너의 속성을 구성할 때 하위 파티션 키 목록을 사용합니다.

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<string> subpartitionKeyPaths = new List<string> { 
    "/TenantId",
    "/UserId",
    "/SessionId"
};

// Create a container properties object
ContainerProperties containerProperties = new ContainerProperties(
    id: "<container-name>",
    partitionKeyPaths: subpartitionKeyPaths
);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput: 400);

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<String> subpartitionKeyPaths = new ArrayList<String>();
subpartitionKeyPaths.add("/TenantId");
subpartitionKeyPaths.add("/UserId");
subpartitionKeyPaths.add("/SessionId");

//Create a partition key definition object with Kind ("MultiHash") and Version V2
PartitionKeyDefinition subpartitionKeyDefinition = new PartitionKeyDefinition();
subpartitionKeyDefinition.setPaths(subpartitionKeyPaths);
subpartitionKeyDefinition.setKind(PartitionKind.MULTI_HASH);
subpartitionKeyDefinition.setVersion(PartitionKeyDefinitionVersion.V2);

// Create a container properties object
CosmosContainerProperties containerProperties = new CosmosContainerProperties("<container-name>", subpartitionKeyDefinition);

// Create a throughput properties object
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Mono<CosmosContainerResponse> container = database.createContainerIfNotExists(containerProperties, throughputProperties);

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

container = database.create_container(
        id=container_name, partition_key=PartitionKey(path=["/tenantId", "/userId", "/sessionId"], kind="MultiHash")
    )

Azure Resource Manager 템플릿

하위 분할된 컨테이너에 대한 Azure Resource Manager 템플릿은 표준 컨테이너와 거의 동일합니다. 유일한 주요 차이점은 properties/partitionKey 경로의 값입니다. Azure Cosmos DB 리소스에 대한 Azure Resource Manager 템플릿을 만드는 방법에 대한 자세한 내용은 Azure Cosmos DB에 대한 Azure Resource Manager 템플릿 참조를 참조하세요.

다음 표의 값을 사용하여 partitionKey 개체를 구성하여 하위 분할된 컨테이너를 만듭니다.

Path	값
`paths`	계층적 파티션 키 목록(최대 3개 깊이 수준)
`kind`	`MultiHash`
`version`	`2`

파티션 키 정의 예제

예를 들어 TenantId>UserId>SessionId로 구성된 계층적 파티션 키가 있다고 가정합니다. partitionKey 개체는 paths 속성의 세 가지 값, 즉 MultiHash의 kind 값 및 2의 version 값을 모두 포함하도록 구성됩니다.

Bicep
JSON

partitionKey: {
  paths: [
    '/TenantId'
    '/UserId'
    '/SessionId'
  ]
  kind: 'MultiHash'
  version: 2
}

"partitionKey": {
    "paths": [
        "/TenantId",
        "/UserId",
        "/SessionId"
    ],
    "kind": "MultiHash",
    "version": 2
}

partitionKey 개체에 대한 자세한 내용은 ContainerPartitionKey 사양을 참조하세요.

Azure Cosmos DB 에뮬레이터

하위 분할 기능은 Azure Cosmos DB용 로컬 에뮬레이터의 최신 버전을 사용하여 테스트할 수 있습니다. 에뮬레이터에서 하위 분할을 사용하도록 설정하려면 /EnablePreview 플래그를 사용하여 설치 디렉터리에서 에뮬레이터를 시작합니다.

.\CosmosDB.Emulator.exe /EnablePreview

Warning

에뮬레이터는 현재 모든 계층적 파티션 키 기능을 포털로 지원하지 않습니다. 에뮬레이터는 현재 다음을 지원하지 않습니다.

Data Explorer를 사용하여 계층적 파티션 키를 사용하여 컨테이너 만들기
Data Explorer를 사용하여 계층적 파티션 키를 사용하여 항목으로 이동 및 상호 작용

자세한 내용은 Azure Cosmos DB 에뮬레이터를 참조하세요.

SDK를 사용하여 계층적 파티션 키가 있는 컨테이너 작업

계층적 파티션 키가 포함된 컨테이너가 있는 경우 이전에 지정된 버전의 .NET 또는 Java SDK를 사용하여 해당 컨테이너에서 작업을 수행하고 쿼리를 실행합니다.

컨테이너에 항목 추가

새 항목을 계층적 파티션 키가 사용하도록 설정된 컨테이너에 추가하는 두 가지 옵션이 있습니다.

자동 추출
수동으로 경로 지정

자동 추출

파티션 키 값이 설정된 개체를 전달하면 SDK에서 자동으로 전체 파티션 키 경로를 추출할 수 있습니다.

// Create a new item
UserSession item = new UserSession()
{
    id = "f7da01b0-090b-41d2-8416-dacae09fbb4a",
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Pass in the object, and the SDK automatically extracts the full partition key path
ItemResponse<UserSession> createResponse = await container.CreateItemAsync(item);

// Create a new item
UserSession item = new UserSession();
item.setId("f7da01b0-090b-41d2-8416-dacae09fbb4a");
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
item.setSessionId("0000-11-0000-1111");
   
// Pass in the object, and the SDK automatically extracts the full partition key path
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item);

 // Create a new item
const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
    SessionId: '0000-11-0000-1111'
}

// Pass in the object, and the SDK automatically extracts the full partition key path
const { resource: document } = await = container.items.create(item);

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

수동으로 경로 지정

SDK의 PartitionKeyBuilder 클래스에서 이전에 정의된 계층적 파티션 키 경로에 대한 값을 생성할 수 있습니다. 이 클래스는 새 항목을 하위 분할이 사용하도록 설정된 컨테이너에 추가할 때 사용됩니다.

팁

SDK에서 개체로부터 경로를 추출할 수 있는 경우에도 규모에 맞게 전체 파티션 키 경로를 지정하면 성능이 향상될 수 있습니다.

// Create a new item object
PaymentEvent item = new PaymentEvent()
{
    id = Guid.NewGuid().ToString(),
    TenantId = "Microsoft",
    UserId = "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    SessionId = "0000-11-0000-1111"
};

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .Add(item.TenantId)
            .Add(item.UserId)
            .Add(item.SessionId)
            .Build();

// Create the item in the container
ItemResponse<PaymentEvent> createResponse = await container.CreateItemAsync(item, partitionKey);

// Create a new item object
UserSession item = new UserSession();
item.setTenantId("Microsoft");
item.setUserId("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
item.setSessionId("0000-11-0000-1111");
item.setId(UUID.randomUUID().toString());

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .add(item.getTenantId())
            .add(item.getUserId())
            .add(item.getSessionId())
            .build();
       
// Create the item in the container     
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item, partitionKey);

const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
    SessionId: '0000-11-0000-1111'
}

// Specify the full partition key path when creating the item
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Create the item in the container
const { resource: document } = await container.items.create(item, partitionKey);

Python의 경우 파티션 키 경로의 모든 필드에 대한 값이 항목 정의에 지정되어 있는지 확인합니다.

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '00aa00aa-bb11-cc22-dd33-44ee44ee44ee',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

항목의 키/값 조회(포인트 읽기) 수행

키/값 조회(포인트 읽기)는 하위 분할되지 않은 컨테이너와 비슷한 방식으로 수행됩니다. 예를 들어 TenantId>UserId>SessionId로 구성된 계층적 파티션 키가 있다고 가정합니다. 항목의 고유 식별자는 GUID입니다. 고유 문서 트랜잭션 식별자 역할을 하는 문자열로 표시됩니다. 단일 항목에서 포인트 읽기를 수행하려면 항목의 id 속성과 경로의 세 가지 구성 요소를 모두 포함한 파티션 키의 전체 값을 전달합니다.

// Store the unique identifier
string id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .Add("Microsoft") //TenantId
    .Add("00aa00aa-bb11-cc22-dd33-44ee44ee44ee") //UserId
    .Add("0000-11-0000-1111") //SessionId
    .Build();

// Perform a point read
ItemResponse<UserSession> readResponse = await container.ReadItemAsync<UserSession>(
    id,
    partitionKey
);

// Store the unique identifier
String id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"; 

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .add("Microsoft") //TenantId
    .add("00aa00aa-bb11-cc22-dd33-44ee44ee44ee") //UserId
    .add("0000-11-0000-1111") //SessionId
    .build();
    
// Perform a point read
Mono<CosmosItemResponse<UserSession>> readResponse = container.readItem(id, partitionKey, UserSession.class);

// Store the unique identifier
const id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Perform a point read
const { resource: document } = await container.item(id, partitionKey).read();

item_id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"
pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

쿼리 실행

하위 분할된 컨테이너에서 쿼리를 실행하는 데 사용되는 SDK 코드는 하위 분할되지 않은 컨테이너에서 쿼리를 실행하는 것과 동일합니다.

쿼리에서 WHERE 필터 또는 키 계층 구조의 접두사에 있는 파티션 키의 모든 값을 지정하면 SDK에서 쿼리를 해당 실제 파티션으로 자동으로 라우팅합니다. 계층 구조의 "중간"만 제공하는 쿼리는 파티션 간 쿼리입니다.

예를 들어 TenantId>UserId>SessionId로 구성된 계층적 파티션 키를 고려합니다. 쿼리 필터의 구성 요소는 쿼리가 단일 파티션 쿼리인지, 대상 파티션 간 쿼리인지 또는 팬아웃 쿼리인지를 결정합니다.

쿼리	라우팅
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'`	지정된 `TenantId`, `UserId` 및 `SessionId` 값에 대한 데이터가 포함된 단일 논리 및 실제 파티션으로 라우팅됩니다.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	지정된 `TenantId` 및 `UserId` 값에 대한 데이터가 포함된 논리 및 실제 파티션의 대상 하위 집합으로만 라우팅됩니다. 이 쿼리는 테넌트의 특정 사용자에 대한 데이터를 반환하는 대상 파티션 간 쿼리입니다.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft'`	지정된 `TenantId` 값에 대한 데이터가 포함된 논리 및 실제 파티션의 대상 하위 집합으로만 라우팅됩니다. 이 쿼리는 테넌트의 모든 사용자에 대한 데이터를 반환하는 대상 파티션 간 쿼리입니다.
`SELECT * FROM c WHERE c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee'`	모든 실제 파티션으로 라우팅되어 팬아웃 파티션 간 쿼리가 발생합니다.
`SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'`	모든 실제 파티션으로 라우팅되어 팬아웃 파티션 간 쿼리가 발생합니다.

하위 분할된 컨테이너에 대한 단일 파티션 쿼리

다음은 모든 수준의 하위 분할을 포함하는 쿼리를 실행하여 쿼리를 단일 파티션 쿼리로 효과적으로 만드는 예제입니다.

// Define a single-partition query that specifies the full partition key path
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id AND c.UserId = @user-id AND c.SessionId = @session-id")
    .WithParameter("@tenant-id", "Microsoft")
    .WithParameter("@user-id", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee")
    .WithParameter("@session-id", "0000-11-0000-1111");

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a single-partition query that specifies the full partition key path
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s' AND c.UserId = '%s' AND c.SessionId = '%s'",
    "Microsoft",
    "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "0000-11-0000-1111"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a single-partition query that specifies the full partition key path
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '00aa00aa-bb11-cc22-dd33-44ee44ee44ee' AND c.SessionId = '0000-11-0000-1111'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id and r.sessionId=@session_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]},
        {"name": "@session_id", "value": pk[2]}
    ]
))

하위 분할된 컨테이너에 대한 대상 다중 파티션 쿼리

다음은 하위 분할 수준의 하위 집합을 포함하는 쿼리의 예제로, 이 쿼리를 대상 다중 파티션 쿼리로 효과적으로 만듭니다.

// Define a targeted cross-partition query specifying prefix path[s]
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id")
    .WithParameter("@tenant-id", "Microsoft")

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a targeted cross-partition query specifying prefix path[s]
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s'",
    "Microsoft"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a targeted cross-partition query specifying prefix path[s]
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "00aa00aa-bb11-cc22-dd33-44ee44ee44ee", "0000-11-0000-1111"]
# enable_cross_partition_query should be set to True as the container is partitioned
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]}
    ],
    enable_cross_partition_query=True
))

제한 사항 및 알려진 문제

계층적 파티션 키를 사용하는 컨테이너 작업은 .NET v3 SDK, Java v4 SDK, Python SDK 및 JavaScript SDK의 미리 보기 버전에서만 지원됩니다. 계층적 파티션 키가 있는 새 컨테이너를 만들고 데이터에 대한 CRUD 또는 쿼리 작업을 수행하려면 지원되는 SDK를 사용해야 합니다. Python을 포함한 다른 SDK에 대한 지원은 현재 사용할 수 없습니다.
다양한 Azure Cosmos DB 커넥터(예: Azure Data Factory 사용)에는 제한 사항이 있습니다.
계층적 파티션 키는 최대 세 개의 깊이 계층까지만 지정할 수 있습니다.
계층적 파티션 키는 현재 새 컨테이너에서만 사용하도록 설정할 수 있습니다. 컨테이너를 만들 때 파티션 키 경로를 설정해야 하며 나중에 변경할 수 없습니다. 기존 컨테이너에서 계층적 파티션을 사용하려면 계층적 파티션 키가 설정된 새 컨테이너를 만들고 컨테이너 복사 작업을 사용하여 데이터를 이동합니다.
계층적 파티션 키는 현재 API for NoSQL 계정에 대해서만 지원됩니다. API for MongoDB 및 Cassandra는 현재 지원되지 않습니다.
계층적 파티션 키는 현재 사용자 및 권한 기능에서 지원되지 않습니다. 계층적 파티션 키 경로의 부분 접두사에는 권한을 할당할 수 없습니다. 권한은 전체 논리 파티션 키 경로에만 할당될 수 있습니다. 예를 들어, TenantId - >UserId로 분할한 경우 특정 값 TenantId에 대한 권한을 할당할 수 없습니다. 그러나 TenantId 및 ``UserId``` 값을 모두 할당하면 파티션 키에 대한 권한을 할당할 수 있습니다.

다음 단계

계층적 파티션 키에 대한 FAQ를 참조합니다.
Azure Cosmos DB의 분할에 대해 자세히 알아봅니다.
Azure Cosmos DB에서 Azure Resource Manager 템플릿을 사용하는 방법에 대해 자세히 알아봅니다.

다음을 통해 공유