Niet-gepartitioneerde containers migreren naar gepartitioneerde containers

VAN TOEPASSING OP: NoSQL

Azure Cosmos DB ondersteunt het maken van containers zonder partitiesleutel. Momenteel kunt u niet-gepartitioneerde containers maken met behulp van Azure CLI en Azure Cosmos DB SDK's (.NET, Java, NodeJs) met een versie die kleiner is dan of gelijk is aan 2.x. U kunt geen niet-gepartitioneerde containers maken met behulp van de Azure Portal. Dergelijke niet-gepartitioneerde containers zijn echter niet elastisch en hebben een vaste opslagcapaciteit van 20 GB en een doorvoerlimiet van 10.000 RU/s.

De niet-gepartitioneerde containers zijn verouderd en u moet uw bestaande niet-gepartitioneerde containers migreren naar gepartitioneerde containers om opslag en doorvoer te schalen. Azure Cosmos DB biedt een door het systeem gedefinieerd mechanisme voor het migreren van uw niet-gepartitioneerde containers naar gepartitioneerde containers. In dit document wordt uitgelegd hoe alle bestaande niet-gepartitioneerde containers automatisch worden gemigreerd naar gepartitioneerde containers. U kunt alleen profiteren van de functie voor automatische migratie als u de V3-versie van SDK's in alle talen gebruikt.

Notitie

Op dit moment kunt u Azure Cosmos DB MongoDB en API voor Gremlin-accounts niet migreren met behulp van de stappen die in dit document worden beschreven.

Container migreren met behulp van de door het systeem gedefinieerde partitiesleutel

Ter ondersteuning van de migratie biedt Azure Cosmos DB een door het systeem gedefinieerde partitiesleutel met de naam /_partitionkey voor alle containers die geen partitiesleutel hebben. U kunt de definitie van de partitiesleutel niet wijzigen nadat de containers zijn gemigreerd. De definitie van een container die wordt gemigreerd naar een gepartitioneerde container is bijvoorbeeld als volgt:

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

Nadat de container is gemigreerd, kunt u documenten maken door de _partitionKey eigenschap samen met de andere eigenschappen van het document in te vullen. De _partitionKey eigenschap vertegenwoordigt de partitiesleutel van uw documenten.

Het kiezen van de juiste partitiesleutel is belangrijk om de ingerichte doorvoer optimaal te gebruiken. Zie het artikel Een partitiesleutel kiezen voor meer informatie.

Notitie

U kunt alleen profiteren van de door het systeem gedefinieerde partitiesleutel als u de nieuwste/V3-versie van SDK's in alle talen gebruikt.

In het volgende voorbeeld ziet u een voorbeeldcode voor het maken van een document met de door het systeem gedefinieerde partitiesleutel en het lezen van dat document:

JSON-weergave van het 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", 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
  );

Zie de GitHub-opslagplaats met .NET-voorbeelden voor het volledige voorbeeld.

De documenten migreren

Hoewel de containerdefinitie is uitgebreid met een partitiesleuteleigenschap, worden de documenten in de container niet automatisch gemigreerd. Dit betekent dat het eigenschapspad /_partitionKey van de systeempartitiesleutel niet automatisch wordt toegevoegd aan de bestaande documenten. U moet de bestaande documenten opnieuw partitioneren door de documenten te lezen die zonder partitiesleutel zijn gemaakt en ze opnieuw te schrijven met _partitionKey de eigenschap in de documenten.

Toegang tot documenten die geen partitiesleutel hebben

Toepassingen hebben toegang tot de bestaande documenten die geen partitiesleutel hebben met behulp van de speciale systeemeigenschap genaamd PartitionKey.None. Dit is de waarde van de niet-gemigreerde documenten. U kunt deze eigenschap gebruiken in alle CRUD- en querybewerkingen. In het volgende voorbeeld ziet u een voorbeeld voor het lezen van één document uit de NonePartitionKey.

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

Compatibiliteit met SDK's

Oudere versie van Azure Cosmos DB SDK's, zoals V2.x.x en V1.x.x, bieden geen ondersteuning voor de door het systeem gedefinieerde partitiesleuteleigenschap. Wanneer u de containerdefinitie van een oudere SDK leest, bevat deze dus geen partitiesleuteldefinitie en gedragen deze containers zich precies zoals voorheen. Toepassingen die zijn gebouwd met de oudere versie van SDK's, blijven werken met niet-gepartitioneerde zonder wijzigingen.

Als een gemigreerde container wordt gebruikt door de nieuwste/V3-versie van SDK en u begint met het invullen van de door het systeem gedefinieerde partitiesleutel in de nieuwe documenten, hebt u geen toegang meer tot dergelijke documenten (lezen, bijwerken, verwijderen, query's) vanuit de oudere SDK's.

Bekende problemen

Het uitvoeren van query's voor het aantal items dat is ingevoegd zonder een partitiesleutel met behulp van de V3 SDK kan leiden tot een hoger doorvoerverbruik

Als u vanuit de V3 SDK een query uitvoert op de items die zijn ingevoegd met behulp van de V2 SDK of de items die zijn ingevoegd met behulp van de V3 SDK met PartitionKey.None parameter, kan de tellingsquery meer RU/s verbruiken als de PartitionKey.None parameter wordt opgegeven in de FeedOptions. U wordt aangeraden de PartitionKey.None parameter niet op te geven als er geen andere items worden ingevoegd met een partitiesleutel.

Als nieuwe items worden ingevoegd met verschillende waarden voor de partitiesleutel, heeft het uitvoeren van query's op dergelijke itemtellingen door de juiste sleutel door te geven in FeedOptions geen problemen. Nadat u nieuwe documenten met een partitiesleutel hebt ingevoegd en u alleen het aantal documenten wilt opvragen zonder de waarde van de partitiesleutel, kan die query opnieuw hogere RU/s opleveren, vergelijkbaar met de normale gepartitioneerde verzamelingen.

Volgende stappen