Share via

Migrar contentores não particionados para contentores particionados

  • Artigo

APLICA-SE A: NoSQL

O Azure Cosmos DB suporta a criação de contentores sem uma chave de partição. Atualmente, pode criar contentores não particionados com a CLI do Azure e os SDKs do Azure Cosmos DB (.NET, Java, NodeJs) com uma versão inferior ou igual a 2.x. Não pode criar contentores não particionados com a portal do Azure. No entanto, esses contentores não particionados não são elásticos e têm uma capacidade de armazenamento fixa de 20 GB e um limite de débito de 10 mil RU/s.

Os contentores não particionados são legados e deve migrar os contentores não particionados existentes para contentores particionados para dimensionar o armazenamento e o débito. O Azure Cosmos DB fornece um mecanismo definido pelo sistema para migrar os contentores não particionados para contentores particionados. Este documento explica como todos os contentores não particionados existentes são migrados automaticamente para contentores particionados. Só pode tirar partido da funcionalidade de migração automática se estiver a utilizar a versão V3 dos SDKs em todos os idiomas.

Nota

Atualmente, não pode migrar o MongoDB e a API do Azure Cosmos DB para contas Gremlin com os passos descritos neste documento.

Migrar o contentor com a chave de partição definida pelo sistema

Para suportar a migração, o Azure Cosmos DB fornece uma chave de partição definida pelo sistema com o nome /_partitionkey em todos os contentores que não têm uma chave de partição. Não pode alterar a definição da chave de partição após a migração dos contentores. Por exemplo, a definição de um contentor que é migrado para um contentor particionado será a seguinte:

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

Após a migração do contentor, pode criar documentos preenchendo a _partitionKey propriedade juntamente com as outras propriedades do documento. A _partitionKey propriedade representa a chave de partição dos seus documentos.

Escolher a chave de partição correta é importante para utilizar o débito aprovisionado de forma ideal. Para obter mais informações, veja como escolher uma chave de partição .

Nota

Só pode tirar partido da chave de partição definida pelo sistema se estiver a utilizar a versão mais recente/V3 dos SDKs em todos os idiomas.

O exemplo seguinte mostra um código de exemplo para criar um documento com a chave de partição definida pelo sistema e ler esse documento:

Representação JSON do documento

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

Para obter o exemplo completo, veja o repositório do GitHub de exemplos de .NET .

Migrar os documentos

Embora a definição do contentor seja melhorada com uma propriedade de chave de partição, os documentos no contentor não são migrados automaticamente. O que significa que o caminho da propriedade /_partitionKey da chave de partição do sistema não é adicionado automaticamente aos documentos existentes. Tem de dividir novamente os documentos existentes ao ler os documentos que foram criados sem uma chave de partição e reescrevê-los novamente com _partitionKey a propriedade nos documentos.

Aceder a documentos que não têm uma chave de partição

As aplicações podem aceder aos documentos existentes que não têm uma chave de partição através da propriedade do sistema especial denominada "PartitionKey.None", este é o valor dos documentos não migrados. Pode utilizar esta propriedade em todas as operações CRUD e de consulta. O exemplo seguinte mostra um exemplo para ler um único Documento a partir de NonePartitionKey.

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

Compatibilidade com SDKs

A versão mais antiga dos SDKs do Azure Cosmos DB, como V2.x.x e V1.x.x, não suporta a propriedade da chave de partição definida pelo sistema. Por isso, quando lê a definição do contentor a partir de um SDK mais antigo, não contém nenhuma definição de chave de partição e estes contentores terão um comportamento exatamente igual ao anterior. As aplicações criadas com a versão mais antiga dos SDKs continuam a funcionar com não partições como estão sem alterações.

Se um contentor migrado for consumido pela versão mais recente/V3 do SDK e começar a preencher a chave de partição definida pelo sistema nos novos documentos, já não poderá aceder (ler, atualizar, eliminar, consultar) a esses documentos a partir dos SDKs mais antigos.

Problemas conhecidos

Consultar a contagem de itens que foram inseridos sem uma chave de partição através do SDK V3 pode envolver um consumo de débito mais elevado

Se consultar a partir do SDK V3 para os itens inseridos com o SDK V2 ou os itens inseridos com o SDK V3 com PartitionKey.None o parâmetro , a consulta de contagem poderá consumir mais RU/s se o PartitionKey.None parâmetro for fornecido nas FeedOptions. Recomendamos que não forneça o PartitionKey.None parâmetro se não forem inseridos outros itens com uma chave de partição.

Se forem inseridos novos itens com valores diferentes para a chave de partição, a consulta para essas contagens de itens ao transmitir a chave adequada não FeedOptions terá problemas. Depois de inserir novos documentos com a chave de partição, se precisar de consultar apenas a contagem de documentos sem o valor da chave de partição, essa consulta poderá voltar a incorrer em RU/s superiores semelhantes às coleções particionadas normais.

Passos seguintes