非パーティション分割コンテナーをパーティション分割コンテナーに移行するMigrate non-partitioned containers to partitioned containers

Azure Cosmos DB では、パーティション キーのないコンテナーの作成がサポートされています。Azure Cosmos DB supports creating containers without a partition key. 現在は、Azure CLI とバージョン 2.x 以下の Azure Cosmos DB SDK (.Net、Java、NodeJs) を使って、非パーティション分割コンテナーを作成できます。Currently you can create non-partitioned containers by using Azure CLI and Azure Cosmos DB SDKs (.Net, Java, NodeJs) that have a version less than or equal to 2.x. Azure portal を使って非パーティション分割コンテナーを作成することはできません。You cannot create non-partitioned containers using the Azure portal. ただし、そのような非パーティション分割コンテナーはエラスティックではなく、ストレージ容量 10 GB およびスループット制限 10 K RU/秒の固定です。However, such non-partitioned containers aren’t elastic and have fixed storage capacity of 10 GB and throughput limit of 10K RU/s.

非パーティション分割コンテナーはレガシであり、ストレージとスループットをスケーリングするには、既存の非パーティション分割コンテナーをパーティション分割コンテナーに移行する必要があります。The non-partitioned containers are legacy and you should migrate your existing non-partitioned containers to partitioned containers to scale storage and throughput. Azure Cosmos DB では、非パーティション分割コンテナーをパーティション分割コンテナーに移行するためのメカニズムが、システムで定義されています。Azure Cosmos DB provides a system defined mechanism to migrate your non-partitioned containers to partitioned containers. このドキュメントでは、既存のすべての非パーティション分割コンテナーをパーティション分割コンテナーに自動的に移行する方法について説明します。This document explains how all the existing non-partitioned containers are auto-migrated into partitioned containers. 自動移行機能は、どの言語でも V3 バージョンの SDK を使っている場合にのみ利用できます。You can take advantage of the auto-migration feature only if you are using the V3 version of SDKs in all the languages.

注意

現時点では、このドキュメントで説明されている手順を使って、Azure Cosmos DB の MongoDB および Gremlin API アカウントを移行することはできません。Currently, you cannot migrate Azure Cosmos DB MongoDB and Gremlin API accounts by using the steps described in this document.

システム定義のパーティション キーを使用してコンテナーを移行するMigrate container using the system defined partition key

Azure Cosmos DB では、移行をサポートするため、パーティション キーを持たないすべてのコンテナーにおいて、/_partitionkey という名前のシステム定義のパーティション キーが定義されています。To support the migration, Azure Cosmos DB defines a system defined partition key named /_partitionkey on all the containers that don’t have a partition key. コンテナーが移行された後で、パーティション キーの定義を変更することはできません。You cannot change the partition key definition after the containers are migrated. たとえば、パーティション分割コンテナーに移行されたコンテナーの定義は次のようになります。For example, the definition of a container that is migrated to a partitioned container will be as follows:

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

コンテナーが移行された後、_partitionKey プロパティと共にドキュメントの他のプロパティを設定することにより、ドキュメントを作成できます。After the container is migrated, you can create documents by populating the _partitionKey property along with the other properties of the document. _partitionKey プロパティは、ドキュメントのパーティション キーを表します。The _partitionKey property represents the partition key of your documents.

適切なパーティション キーを選択することは、プロビジョニング済みスループットを最適に利用するために重要です。Choosing the right partition key is important to utilize the provisioned throughput optimally. 詳しくは、パーティション キーの選択方法に関する記事をご覧ください。For more information, see how to choose a partition key article.

注意

システム定義のパーティション キーは、どの言語でも最新/V3 バージョンの SDK を使っている場合にのみ利用できます。You can take advantage of system defined partition key only if you are using the latest/V3 version of SDKs in all the languages.

次の例では、システム定義のパーティション キーでドキュメントを作成し、そのドキュメントを読み取るサンプル コードを示します。The following example shows a sample code to create a document with the system defined partition key and read that document:

ドキュメントの JSON 表現JSON representation of the document

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")]
    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"
} 

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

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

完全なサンプルについては、.Net サンプルの GitHub リポジトリをご覧ください。For the complete sample, see the .Net samples GitHub repository.

ドキュメントを移行するMigrate the documents

コンテナー定義がパーティション キー プロパティで拡張されている間は、コンテナー内のドキュメントは自動的に移行されません。While the container definition is enhanced with a partition key property, the documents within the container aren’t auto migrated. つまり、システム パーティション キー プロパティのパス /_partitionKey は、既存のドキュメントには自動的に追加されません。Which means the system partition key property /_partitionKey path is not automatically added to the existing documents. パーティション キーなしで作成されたドキュメントを読み取り、_partitionKey プロパティを指定してドキュメントに書き戻すことによって、既存のドキュメントを再パーティション分割する必要があります。You need to repartition the existing documents by reading the documents that were created without a partition key and rewrite them back with _partitionKey property in the documents.

パーティション キーを持たないドキュメントにアクセスするAccess documents that don't have a partition key

アプリケーションでは、"CosmosContainerSettings.NonePartitionKeyValue" という特殊なシステム プロパティを使って、パーティション キーを持たない既存のドキュメントにアクセスできます。これは、移行されないドキュメントの値です。Applications can access the existing documents that don’t have a partition key by using the special system property called "CosmosContainerSettings.NonePartitionKeyValue", this is the value of the non-migrated documents. このプロパティは、すべての CRUD とクエリ操作で使用できます。You can use this property in all the CRUD and query operations. 次の例では、NonePartitionKey から 1 つのドキュメントを読み取るサンプルを示します。The following example shows a sample to read a single Document from the NonePartitionKey.

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

ドキュメントを再パーティション分割する方法の完全なサンプルについては、.Net サンプルの GitHub リポジトリをご覧ください。For the complete sample on how to repartition the documents, see the .Net samples GitHub repository.

SDK との互換性Compatibility with SDKs

V2.x.x や V1.x.x などの古いバージョンの Azure Cosmos DB SDK では、システム定義のパーティション キー プロパティはサポートされていません。Older version of Azure Cosmos DB SDKs such as V2.x.x and V1.x.x don’t support the system defined partition key property. そのため、古い SDK からコンテナー定義を読み取ると、パーティション キーの定義は含まれず、これらのコンテナーは以前とまったく同様に動作します。So, when you read the container definition from an older SDK, it doesn’t contain any partition key definition and these containers will behave exactly as before. 古いバージョンの SDK でビルドされたアプリケーションは、何も変更されないので、引き続き非パーティション分割で動作します。Applications that are built with the older version of SDKs continue to work with non-partitioned as is without any changes.

移行されたコンテナーが最新/V3 バージョンの SDK によって使用され、ユーザーが新しいドキュメント内のシステム定義パーティション キーの設定を開始すると、古い SDK からそのようなドキュメントにアクセスする (読み取り、更新、削除、クエリ) ことはできなくなります。If a migrated container is consumed by the latest/V3 version of SDK and you start populating the system defined partition key within the new documents, you cannot access (read, update, delete, query) such documents from the older SDKs anymore.

次の手順Next steps