Share via

Migrowanie kontenerów niepartycjonowanych do kontenerów podzielonych na partycje

  • Artykuł

DOTYCZY: NoSQL

Usługa Azure Cosmos DB obsługuje tworzenie kontenerów bez klucza partycji. Obecnie kontenery niepartycyjne można tworzyć przy użyciu interfejsu wiersza polecenia platformy Azure i zestawów SDK usługi Azure Cosmos DB (.NET, Java, NodeJs), które mają wersję mniejszą lub równą 2.x. Nie można tworzyć kontenerów bez partycji przy użyciu Azure Portal. Jednak takie kontenery niepartycyjne nie są elastyczne i mają stałą pojemność magazynu wynoszącą 20 GB i limit przepływności wynoszący 10 000 RU/s.

Kontenery niepartycyjne są starsze i należy przeprowadzić migrację istniejących kontenerów bez partycji do kontenerów podzielonych na partycje w celu skalowania magazynu i przepływności. Usługa Azure Cosmos DB udostępnia mechanizm zdefiniowany przez system do migrowania kontenerów bez partycji do kontenerów podzielonych na partycje. W tym dokumencie wyjaśniono, jak wszystkie istniejące kontenery niepartycyjne są automatycznie migrowane do kontenerów podzielonych na partycje. Możesz korzystać z funkcji automatycznej migracji tylko wtedy, gdy używasz wersji 3 zestawów SDK we wszystkich językach.

Uwaga

Obecnie nie można migrować bazy danych MongoDB i interfejsu API usługi Azure Cosmos DB dla kont gremlin, wykonując kroki opisane w tym dokumencie.

Migrowanie kontenera przy użyciu klucza partycji zdefiniowanego przez system

Aby zapewnić obsługę migracji, usługa Azure Cosmos DB udostępnia zdefiniowany przez system klucz partycji o nazwie /_partitionkey na wszystkich kontenerach, które nie mają klucza partycji. Nie można zmienić definicji klucza partycji po przeprowadzeniu migracji kontenerów. Na przykład definicja kontenera migrowanego do kontenera podzielonego na partycje będzie następująca:

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

Po zmigrowaniu kontenera można tworzyć dokumenty, wypełniając _partitionKey właściwość wraz z innymi właściwościami dokumentu. Właściwość _partitionKey reprezentuje klucz partycji dokumentów.

Wybranie odpowiedniego klucza partycji jest ważne, aby optymalnie wykorzystać aprowizowaną przepływność. Aby uzyskać więcej informacji, zobacz artykuł dotyczący wybierania klucza partycji .

Uwaga

Można korzystać z klucza partycji zdefiniowanego przez system tylko wtedy, gdy używasz najnowszej/3 wersji zestawów SDK we wszystkich językach.

W poniższym przykładzie pokazano przykładowy kod umożliwiający utworzenie dokumentu przy użyciu klucza partycji zdefiniowanego przez system i odczytanie tego dokumentu:

Reprezentacja JSON dokumentu

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

Pełny przykład można znaleźć w repozytorium GitHub przykładów dla platformy .NET .

Migrowanie dokumentów

Chociaż definicja kontenera jest rozszerzona o właściwość klucza partycji, dokumenty w kontenerze nie są migrowane automatycznie. Oznacza to, że ścieżka właściwości /_partitionKey klucza partycji systemowej nie jest automatycznie dodawana do istniejących dokumentów. Aby ponownie podzielić istniejące dokumenty, należy odczytać dokumenty utworzone bez klucza partycji i zapisać je ponownie za pomocą _partitionKey właściwości w dokumentach.

Uzyskiwanie dostępu do dokumentów, które nie mają klucza partycji

Aplikacje mogą uzyskiwać dostęp do istniejących dokumentów, które nie mają klucza partycji przy użyciu specjalnej właściwości systemowej o nazwie "PartitionKey.None", jest to wartość dokumentów niemigrowanych. Tej właściwości można używać we wszystkich operacjach CRUD i zapytań. W poniższym przykładzie pokazano przykład odczytu pojedynczego dokumentu z elementu NonePartitionKey.

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

Zgodność z zestawami SDK

Starsza wersja zestawów SDK usługi Azure Cosmos DB, takich jak V2.x.x i V1.x.x, nie obsługuje właściwości klucza partycji zdefiniowanego przez system. Dlatego podczas odczytywania definicji kontenera ze starszego zestawu SDK nie zawiera ona żadnej definicji klucza partycji, a te kontenery będą zachowywać się dokładnie tak jak wcześniej. Aplikacje, które są kompilowane przy użyciu starszej wersji zestawów SDK, nadal działają bez żadnych zmian.

Jeśli zmigrowany kontener jest używany przez najnowszą/3 wersję zestawu SDK i rozpoczynasz wypełnianie klucza partycji zdefiniowanego przez system w nowych dokumentach, nie możesz już uzyskać dostępu (do odczytu, aktualizacji, usuwania, wykonywania zapytań) takich dokumentów ze starszych zestawów SDK.

Znane problemy

Wykonywanie zapytań dotyczących liczby elementów wstawionych bez klucza partycji przy użyciu zestawu SDK w wersji 3 może wiązać się z większym użyciem przepływności

Jeśli wykonujesz zapytanie z zestawu SDK w wersji 3 dla elementów wstawionych przy użyciu zestawu SDK w wersji 2 lub elementów wstawionych przy użyciu zestawu SDK w wersji 3 z parametrem PartitionKey.None , zapytanie count może zużywać więcej jednostek RU/s, jeśli PartitionKey.None parametr jest podany w elemecie FeedOptions. Zalecamy, aby nie podawać parametru PartitionKey.None , jeśli żadne inne elementy nie zostaną wstawione z kluczem partycji.

Jeśli nowe elementy zostaną wstawione z różnymi wartościami klucza partycji, wykonywanie zapytań o takie liczby elementów przez przekazanie odpowiedniego klucza w elemencie FeedOptions nie będzie miało żadnych problemów. Po wstawieniu nowych dokumentów z kluczem partycji, jeśli musisz wykonać zapytanie tylko o liczbę dokumentów bez wartości klucza partycji, to zapytanie może ponownie spowodować wyższe jednostki RU/s podobne do zwykłych kolekcji partycjonowanych.

Następne kroki