Поделиться через

Перенос несекционированных контейнеров в секционированные контейнеры

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

Azure Cosmos DB поддерживает возможность создания контейнеров без ключа секции. В настоящее время можно создавать непартийные контейнеры с помощью Azure CLI и пакетов SDK Azure Cosmos DB (.NET, Java, NodeJs), которые имеют версию меньше или равно 2.x. Не удается создать непартиментированные контейнеры с помощью портал Azure. Однако такие непараментированные контейнеры не являются эластичными и имеют фиксированную емкость хранилища размером 20 ГБ и ограничение пропускной способности в 10 ЕЗ/с.

Непартиментированные контейнеры являются устаревшими и следует перенести существующие непартийные контейнеры в секционированные контейнеры для масштабирования хранилища и пропускной способности. Azure Cosmos DB предоставляет системный механизм для переноса непартийных контейнеров в секционированные контейнеры. В этом документе объясняется, как все существующие непартийные контейнеры автоматически переносятся в секционированные контейнеры. Вы можете воспользоваться функцией автоматической миграции, только если вы используете версию SDK версии 3 на всех языках.

Примечание.

В настоящее время нельзя перенести учетные записи MongoDB и Azure Cosmos DB для Gremlin, выполнив действия, описанные в этом документе.

Перенос контейнера с помощью системного ключа секции

В целях миграции Azure Cosmos DB предоставляет системный ключ секции /_partitionkey для всех контейнеров, у которых нет ключа секции. После переноса контейнеров нельзя изменить определение ключа секции. Например, определение контейнера, перенесенного в секционированный контейнер, будет выглядеть следующим образом:

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

После переноса контейнера можно создавать документы, заполняя свойство _partitionKey вместе с другими свойствами документа. Свойство _partitionKey представляет ключ секции документов.

Выбор правильного ключа секции важен для оптимального использования подготовленной пропускной способности. Дополнительные сведения см. в статье о выборе ключа секции.

Примечание.

Функция системного ключа секции доступна, только если используются пакеты SDK последней версии или версии 3 на всех языках.

Ниже показан пример кода для создания документа с системным ключом секции и для его чтения:

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

Полный пример см. в репозитории GitHub примеров .NET.

Перенос документов

Несмотря на добавление свойства ключа секции в определение контейнера документы из такого контейнера не переносятся в автоматическом режиме. Это означает, что путь к свойству /_partitionKey ключа системного раздела не добавляется в существующие документы автоматически. Необходимо выполнить повторное секционирование для существующих документов: для этого нужно прочитать документы, созданные без ключа секции, и перезаписать их со свойством _partitionKey.

Доступ к документам, у которых нет ключа секции

Приложения могут обращаться к существующим документам, у которых нет ключа секции, с помощью специального системного свойства под названием "PartitionKey.None" (это значение для неперенесенных документов). Это свойство можно использовать во всех операциях CRUD и запросах. Ниже показан пример чтения одного документа из раздела NonePartitionKey.

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

Совместимость с SDK

Более старые версии SDK для Azure Cosmos DB, такие как 2.x.x и 1.x.x, не поддерживают свойство системного ключа секции. Таким образом, при чтении определения контейнера из старого пакета SDK оно не содержит определения ключа секции, и такие контейнеры работают точно так же, как и раньше. Приложения, созданные с более старой версией пакетов SDK, продолжают работать с непартиментными пакетами SDK без каких-либо изменений.

Если перенесенный контейнер используется последней версией пакета SDK версии 3 и начинает заполнять системный ключ секции в новых документах, вы больше не сможете получить доступ (чтение, обновление, удаление, запрос) таких документов из старых пакетов SDK.

Известные проблемы

Запрос количества элементов, которые были вставлены без ключа секции с помощью пакета SDK версии 3, может привести к повышению потребляемой пропускной способности.

При запросе из пакета SDK версии 3 элементов, вставленных с помощью пакета SDK версии 2, или элементов, вставленных с помощью пакета SDK версии 3 с параметром PartitionKey.None, запрос количества может потреблять больше ЕЗ/с, если в FeedOptions указан параметр PartitionKey.None. Рекомендуем не указывать параметр PartitionKey.None, если с ключом секции не вставляются больше никакие другие элементы.

Если новые элементы вставляются с разными значениями для ключа секции, запрос на количество таких элементов путем передачи соответствующего ключа в FeedOptions не будет проблем. Если после вставки новых документов с ключом секции потребуется запросить только количество документов без значения ключа секции, этот запрос также может потребить больше ЕЗ/с (так же, как в обычных коллекциях с секционированием).

Следующие шаги