분할되지 않은 컨테이너를 분할된 컨테이너로 마이그레이션

  • 아티클

적용 대상: NoSQL

Azure Cosmos DB는 파티션 키 없이 컨테이너 만들기를 지원합니다. 현재는 2.x 버전보다 작거나 같은 버전의 Azure CLI 및 Azure Cosmos DB SDK(.NET, Java, NodeJs)를 사용하여 분할되지 않은 컨테이너를 만들 수 있습니다. Azure Portal을 사용하여 분할되지 않은 컨테이너를 만들 수 없습니다. 하지만 이러한 분할되지 않은 컨테이너는 탄력적이지 않으며 스토리지 용량은 20GB로 고정되어 있으며 처리량 제한은 10,000RU/s입니다.

분할되지 않은 컨테이너는 레거시 컨테이너이므로 분할되지 않은 기존 컨테이너를 분할된 컨테이너로 마이그레이션하여 스토리지 및 처리량의 크기를 조정해야 합니다. Azure Cosmos DB는 분할되지 않은 컨테이너를 분할된 컨테이너로 마이그레이션하기 위한 시스템 정의 메커니즘을 제공합니다. 이 문서에서는 기존의 분할되지 않은 모든 컨테이너를 분할된 컨테이너로 자동 마이그레이션하는 방법에 대해 설명합니다. 모든 언어에서 V3 버전의 SDK를 사용하는 경우에만 자동 마이그레이션 기능을 사용할 수 있습니다.

참고 항목

현재 이 문서에서 설명한 단계를 통해 Azure Cosmos DB MongoDB 및 API for Gremlin 계정을 마이그레이션할 수는 없습니다.

시스템 정의 파티션 키를 사용하여 컨테이너 마이그레이션

마이그레이션을 지원하기 위해 Azure Cosmos DB는 파티션 키가 없는 모든 컨테이너에서 /_partitionkey라는 시스템 정의 파티션 키를 제공합니다. 컨테이너를 마이그레이션한 후에는 파티션 키 정의를 변경할 수 없습니다. 예를 들어, 분할된 컨테이너로 마이그레이션되는 컨테이너에 대한 정의는 다음과 같습니다.

{
    "Id": "CollId"
  "partitionKey": {
    "paths": [
      "/_partitionKey"
    ],
    "kind": "Hash"
  },
}

컨테이너를 마이그레이션한 후에는 문서의 다른 속성과 함께 _partitionKey 속성을 채워서 문서를 만들 수 있습니다. _partitionKey 속성은 문서의 파티션 키를 나타냅니다.

프로비전된 처리량을 최적으로 활용하려면 올바른 파티션 키를 선택하는 것이 중요합니다. 자세한 내용은 파티션 키를 선택하는 방법 문서를 참조하세요.

참고 항목

모든 언어에서 최신 V3 버전의 SDK를 사용하는 경우에만 시스템 정의 파티션 키를 활용할 수 있습니다.

다음 예제에서는 시스템 정의 파티션 키로 문서를 만들고 해당 문서를 읽는 샘플 코드를 보여줍니다.

문서의 JSON 표현

DeviceInformationItem = new DeviceInformationItem
{
   "id": "elevator/PugetSound/Building44/Floor1/1",
   "deviceId": "3cf4c52d-cc67-4bb8-b02f-f6185007a808",
   "_partitionKey": "3cf4c52d-cc67-4bb8-b02f-f6185007a808"
}

public class DeviceInformationItem
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }

    [JsonProperty(PropertyName = "deviceId")]
    public string DeviceId { get; set; }

    [JsonProperty(PropertyName = "_partitionKey", NullValueHandling = NullValueHandling.Ignore)]
    public string PartitionKey { get {return this.DeviceId; set; }
}

CosmosContainer migratedContainer = database.Containers["testContainer"];

DeviceInformationItem deviceItem = new DeviceInformationItem() {
  Id = "1234",
  DeviceId = "3cf4c52d-cc67-4bb8-b02f-f6185007a808"
}

ItemResponse<DeviceInformationItem > response =
  await migratedContainer.CreateItemAsync<DeviceInformationItem>(
    deviceItem.PartitionKey,
    deviceItem
  );

// Read back the document providing the same partition key
ItemResponse<DeviceInformationItem> readResponse =
  await migratedContainer.ReadItemAsync<DeviceInformationItem>(
    partitionKey: deviceItem.PartitionKey,
    id: device.Id
  );

전체 샘플은 .NET 샘플 GitHub 리포지토리를 참조하세요.

문서 마이그레이션

컨테이너 정의는 파티션 키 속성을 사용하여 향상되지만 컨테이너 내의 문서는 자동으로 마이그레이션되지 않습니다. 즉 시스템 파티션 키 속성 /_partitionKey 경로가 기존 문서에 자동으로 추가되지 않습니다. 파티션 키 없이 만든 문서를 읽고 문서에서 _partitionKey 속성을 사용하여 다시 작성하여 기존 문서를 다시 분할해야 합니다.

파티션 키가 없는 문서에 액세스

애플리케이션은 "PartitionKey.None"이라는 특수 시스템 속성을 사용하여 파티션 키가 없는 기존 문서에 액세스할 수 있습니다. 이는 마이그레이션되지 않은 문서의 값입니다. 모든 CRUD 및 쿼리 작업에서 이 속성을 사용할 수 있습니다. 다음 예제에서는 NonePartitionKey에서 단일 문서를 읽는 샘플을 보여줍니다.

CosmosItemResponse<DeviceInformationItem> readResponse =
await migratedContainer.Items.ReadItemAsync<DeviceInformationItem>(
  partitionKey: PartitionKey.None,
  id: device.Id
);

SDK와의 호환성

이전 버전의 Azure Cosmos DB SDK(예: V2.x.x) 및 V1.x.x는 시스템 정의 파티션 키 속성을 지원하지 않습니다. 따라서 이전 SDK에서 컨테이너 정의를 읽으면 파티션 키 정의가 포함되지 않으며 이러한 컨테이너는 이전과 정확히 동일하게 동작합니다. 이전 버전의 SDK를 사용하여 빌드된 애플리케이션은 변경 없이 그대로 분할되지 않은 상태로 계속 작동합니다.

마이그레이션된 컨테이너가 SDK의 최신/V3 버전에서 사용되고 새 문서 내에서 시스템 정의 파티션 키를 채우기 시작하면 이전 SDK에서 이러한 문서에 대한 액세스(읽기, 업데이트, 삭제, 쿼리)를 더 이상 할 수 없습니다.

알려진 문제

V3 SDK를 사용하여 파티션 키 없이 삽입된 항목 수에 대한 쿼리는 더 높은 처리량 사용을 포함할 수 있습니다.

V2 SDK를 사용하여 삽입된 항목 또는 PartitionKey.None 매개 변수로 V3 SDK를 사용하여 삽입된 항목에 대해 V3 SDK에서 쿼리하는 경우 COUNT 쿼리는 PartitionKey.None 매개 변수가 FeedOptions에서 제공되는 경우 더 많은 RU/s를 사용할 수 있습니다. 파티션 키와 함께 삽입된 다른 항목이 없는 경우 PartitionKey.None 매개 변수를 제공하지 않는 것이 좋습니다.

파티션 키에 대해 다른 값을 사용하여 새 항목을 삽입하는 경우 FeedOptions에서 적절한 키를 전달하여 이러한 항목 수를 쿼리하면 문제가 발생하지 않습니다. 파티션 키를 사용하여 새 문서를 삽입한 후 파티션 키 값을 사용하지 않고 문서 개수만 쿼리해야 하는 경우, 해당 쿼리는 일반 분할된 컬렉션과 비슷하게 높은 RU/s를 초래할 수 있습니다.

다음 단계