Ausführen von Massenvorgängen für Azure Cosmos DB-Daten

In diesem Lernprogramm wird gezeigt, wie Massenvorgänge im Azure Cosmos DB Java V4 SDK ausgeführt werden. Diese Version des SDK enthält die Bulk-Executor-Bibliothek. Wenn Sie eine ältere Version des Java SDK verwenden, migrieren Sie auf die neueste Version. Das Azure Cosmos DB Java V4 SDK ist die aktuell empfohlene Lösung für die Unterstützung von Massenvorgängen in Java.

Zurzeit wird die Bulk Executor-Bibliothek nur von Azure Cosmos DB for NoSQL- und API für Gremlin-Konten unterstützt. Informationen zur Verwendung der .NET-Bibliothek für die Massenausführung mit API für Gremlin finden Sie unter Ausführen von Massenvorgängen in Azure Cosmos DB für Gremlin.

Tip

Agent Kit hilft Programmieragenten, mithilfe empfohlener bewährter Methoden schnell und effizient mit Azure Cosmos DB zu arbeiten. Führen Sie zunächst Folgendes aus:

npx skills add AzureCosmosDB/cosmosdb-agent-kit

Weitere Informationen finden Sie unter Azure Cosmos DB Agent Kit.

Prerequisites

  • Wenn Sie noch kein Azure-Abonnement haben, erstellen Sie ein kostenloses Konto, bevor Sie beginnen. Alternativ dazu können Sie den Azure Cosmos DB-Emulator mit dem Endpunkt https://localhost:8081 verwenden. Den Primärschlüssel finden Sie unter Authentifizieren von Anforderungen.

  • Java Development Kit (JDK) 1,8+

    • Führen Sie unter Ubuntu apt-get install default-jdk aus, um das JDK zu installieren.

    • Achten Sie darauf, dass die Umgebungsvariable „JAVA_HOME“ auf den Ordner verweist, in dem das JDK installiert ist.

  • Laden Sie ein Maven-Binärarchiv herunter und installieren Sie es

    • Unter Ubuntu können Sie apt-get install maven ausführen, um Maven zu installieren.
  • Erstellen Sie anhand der Schritte im Abschnitt Erstellen eines Datenbankkontos des Artikels mit dem Java-Schnellstart ein Azure Cosmos DB for NoSQL-Konto.

Klonen der Beispielanwendung

Laden Sie ein Beispiel-Repository für das Java V4 SDK aus GitHub herunter. Diese Beispielanwendungen führen CRUD-Vorgänge und andere allgemeine Vorgänge in Azure Cosmos DB aus. Um das Repository zu klonen, öffnen Sie eine Eingabeaufforderung, wechseln Sie zu dem Verzeichnis, in das Sie die Anwendung kopieren möchten, und führen Sie den folgenden Befehl aus:

 git clone https://github.com/Azure-Samples/azure-cosmos-java-sql-api-samples 

Das geklonte Repository enthält ein Beispiel für SampleBulkQuickStartAsync.java im Ordner azure-cosmos-java-sql-api-samples/src/main/java/com/azure/cosmos/examples/bulk/async. Die Anwendung generiert Dokumente und führt Vorgänge zum Erstellen, Einfügen/Aktualisieren, Ersetzen und Löschen von Elementen in Azure Cosmos DB aus. In den folgenden Abschnitten wird der Code in der Beispiel-App überprüft.

Massenausführung in Azure Cosmos DB

  1. Die Verbindungszeichenfolgen von Azure Cosmos DB werden als Argumente gelesen und Variablen zugewiesen, die in der Datei /examples/common/AccountSettings.java definiert sind. Diese Umgebungsvariablen müssen festgelegt sein,
ACCOUNT_HOST=your account hostname;ACCOUNT_KEY=your account primary key

Zum Ausführen des Massenbeispiels geben Sie die zugehörige Hauptklasse an:

com.azure.cosmos.examples.bulk.async.SampleBulkQuickStartAsync
  1. Das CosmosAsyncClient-Objekt wird mit den folgenden Anweisungen initialisiert:
client = new CosmosClientBuilder()
    .endpoint(AccountSettings.HOST)
        .credential(new DefaultAzureCredentialBuilder().build())
    .preferredRegions(preferredRegions)
    .contentResponseOnWriteEnabled(true)
    .consistencyLevel(ConsistencyLevel.SESSION).buildAsyncClient();

  1. Im Beispiel werden eine asynchrone Datenbank und ein asynchroner Container erstellt. Anschließend werden mehrere Dokumente erstellt, für die Massenvorgänge ausgeführt werden. Diese Dokumente werden einem reaktiven Flux<Family>-Streamobjekt hinzugefügt:
Family andersenFamilyItem = Families.getAndersenFamilyItem();
Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
Family johnsonFamilyItem = Families.getJohnsonFamilyItem();
Family smithFamilyItem = Families.getSmithFamilyItem();

//  Setup family items to create
Flux<Family> families = Flux.just(andersenFamilyItem, wakefieldFamilyItem, johnsonFamilyItem, smithFamilyItem);
  1. Das Beispiel enthält Methoden für Massenerstellung, Massenupsert, Massenersetzung und Massenlöschung. In jeder Methode ordnen wir die Families-Dokumente im BulkWriter-Stream Flux<Family>mehreren Methodenaufrufen in CosmosBulkOperations zu. Diese Vorgänge werden einem anderen reaktiven Flux<CosmosItemOperation>-Streamobjekt hinzugefügt. Der Stream wird dann an die executeBulkOperations-Methode des asynchronen container übergeben, den wir zu Beginn erstellt haben, und Vorgänge werden als Massenvorgänge ausgeführt. Die nachstehende Massenerstellungsmethode dient als Beispiel:
private void bulkCreateItems(Flux<Family> families) {
    Flux<CosmosItemOperation> cosmosItemOperations = families.map(
        family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
    container.executeBulkOperations(cosmosItemOperations).blockLast();
}
  1. Die BulkWriter.java Klasse im selben Verzeichnis wie die Beispielanwendung veranschaulicht, wie Fehler bei der Ratenbegrenzung (429) und Timeout-Fehler (408) behandelt werden, die während der Massenausführung auftreten, und wie diese Vorgänge wiederholt werden können. Die folgenden Methoden zeigen auch, wie lokale und globale Durchsatzsteuerung implementiert wird.
private void bulkUpsertItemsWithBulkWriterAbstraction() {
    Family andersenFamilyItem = Families.getAndersenFamilyItem();
    Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
    CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getUpsertItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
    CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getUpsertItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
    BulkWriter bulkWriter = new BulkWriter(container);
    bulkWriter.scheduleWrites(andersonItemOperation);
    bulkWriter.scheduleWrites(wakeFieldItemOperation);
    bulkWriter.execute().subscribe();
}

private void bulkUpsertItemsWithBulkWriterAbstractionAndLocalThroughPutControl() {
    ThroughputControlGroupConfig groupConfig =
            new ThroughputControlGroupConfigBuilder()
                    .setGroupName("group1")
                    .setTargetThroughput(200)
                    .build();
    container.enableLocalThroughputControlGroup(groupConfig);
    Family andersenFamilyItem = Families.getAndersenFamilyItem();
    Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
    CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getUpsertItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
    CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getUpsertItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
    BulkWriter bulkWriter = new BulkWriter(container);
    bulkWriter.scheduleWrites(andersonItemOperation);
    bulkWriter.scheduleWrites(wakeFieldItemOperation);
    bulkWriter.execute().subscribe();
}

private void bulkCreateItemsWithBulkWriterAbstractionAndGlobalThroughputControl() {
    String controlContainerId = "throughputControlContainer";
    CosmosAsyncContainer controlContainer = database.getContainer(controlContainerId);
    database.createContainerIfNotExists(controlContainer.getId(), "/groupId").block();

    ThroughputControlGroupConfig groupConfig =
            new ThroughputControlGroupConfigBuilder()
                    .setGroupName("group-" + UUID.randomUUID())
                    .setTargetThroughput(200)
                    .build();

    GlobalThroughputControlConfig globalControlConfig = this.client.createGlobalThroughputControlConfigBuilder(this.database.getId(), controlContainerId)
            .setControlItemRenewInterval(Duration.ofSeconds(5))
            .setControlItemExpireInterval(Duration.ofSeconds(20))
            .build();

    container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);
    CosmosItemRequestOptions requestOptions = new CosmosItemRequestOptions();
    requestOptions.setThroughputControlGroupName(groupConfig.getGroupName());
    Family andersenFamilyItem = Families.getAndersenFamilyItem();
    Family wakefieldFamilyItem = Families.getWakefieldFamilyItem();
    CosmosItemOperation andersonItemOperation = CosmosBulkOperations.getCreateItemOperation(andersenFamilyItem, new PartitionKey(andersenFamilyItem.getLastName()));
    CosmosItemOperation wakeFieldItemOperation = CosmosBulkOperations.getCreateItemOperation(wakefieldFamilyItem, new PartitionKey(wakefieldFamilyItem.getLastName()));
    BulkWriter bulkWriter = new BulkWriter(container);
    bulkWriter.scheduleWrites(andersonItemOperation);
    bulkWriter.scheduleWrites(wakeFieldItemOperation);
    bulkWriter.execute().subscribe();
}
  1. Das Beispiel enthält auch Methoden für die Massenerstellung, die veranschaulichen, wie Sie die Antwortverarbeitung hinzufügen und Ausführungsoptionen festlegen:
private void bulkCreateItemsWithResponseProcessing(Flux<Family> families) {
    Flux<CosmosItemOperation> cosmosItemOperations = families.map(
        family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
    container.executeBulkOperations(cosmosItemOperations).flatMap(cosmosBulkOperationResponse -> {

        CosmosBulkItemResponse cosmosBulkItemResponse = cosmosBulkOperationResponse.getResponse();
        CosmosItemOperation cosmosItemOperation = cosmosBulkOperationResponse.getOperation();

        if (cosmosBulkOperationResponse.getException() != null) {
            logger.error("Bulk operation failed", cosmosBulkOperationResponse.getException());
        } else if (cosmosBulkItemResponse == null ||
            !cosmosBulkOperationResponse.getResponse().isSuccessStatusCode()) {

            logger.error(
                "The operation for Item ID: [{}]  Item PartitionKey Value: [{}] did not complete " +
                    "successfully with " + "a" + " {} response code.",
                cosmosItemOperation.<Family>getItem().getId(),
                cosmosItemOperation.<Family>getItem().getLastName(),
                cosmosBulkItemResponse != null ? cosmosBulkItemResponse.getStatusCode() : "n/a");
        } else {
            logger.info(
                "Item ID: [{}]  Item PartitionKey Value: [{}]",
                cosmosItemOperation.<Family>getItem().getId(),
                cosmosItemOperation.<Family>getItem().getLastName());
            logger.info("Status Code: {}", cosmosBulkItemResponse.getStatusCode());
            logger.info("Request Charge: {}", cosmosBulkItemResponse.getRequestCharge());
        }
        if (cosmosBulkItemResponse == null) {
            return Mono.error(new IllegalStateException("No response retrieved."));
        } else {
            return Mono.just(cosmosBulkItemResponse);
        }
    }).blockLast();
}

private void bulkCreateItemsWithExecutionOptions(Flux<Family> families) {
    CosmosBulkExecutionOptions bulkExecutionOptions = new CosmosBulkExecutionOptions();

    // The default value for maxMicroBatchConcurrency is 1.
    // By increasing it, it means more concurrent requests will be allowed to be sent to the server, which leads to increased RU usage.
    //
    // Before you increase the value, please examine the RU usage of your container - whether it has been saturated or not.
    // When the RU has already been under saturation, increasing the concurrency will not help the situation,
    // rather it may cause more 429 and request timeout.
    bulkExecutionOptions.setMaxMicroBatchConcurrency(2);
    Flux<CosmosItemOperation> cosmosItemOperations = families.map(family -> CosmosBulkOperations.getCreateItemOperation(family, new PartitionKey(family.getLastName())));
    container.executeBulkOperations(cosmosItemOperations, bulkExecutionOptions).blockLast();
}

Strategie für die Datenaufnahme im großen Maßstab

Bei der Erfassung großer Datenmengen sind Durchsatzsteuerung und Wiederholungsrichtlinie die primären Hebel zur Vermeidung von Drosselung – nicht allein Batchgröße oder Parallelität. Wenn Sie sich auf die Batchgröße und Parallelität konzentrieren, ohne Durchsatzgrenzwerte und Wiederholungen zu berücksichtigen, werden 429-Antworten (rate limited) in großem Maßstab nicht zuverlässig verhindert.

Einen Ingestionsansatz wählen

Scenario Empfohlener Ansatz
Groß angelegte verteilte Datenaufnahme über mehrere Computer hinweg Apache Spark Konnektor
Import auf einem einzelnen System, der feinkörnige Steuerung erfordert Java SDK-Bulk-Executor mit Durchsatzsteuerung

Für die groß angelegte Datenaufnahme ist der Apache Spark Connector die bevorzugte Wahl. Es behandelt verteilte Berechnungen, automatische Wiederholung und Rückabruf sowie Lastenausgleich über Arbeitsknoten hinweg, ohne dass eine manuelle Optimierung der Parallelitäts- oder Batchgrößen erforderlich ist.

Java SDK-Bulk-Executor mit Durchsatzsteuerung

Wenn Ihr Szenario das Java SDK direkt erfordert, stellt das azure-cosmos-distributed-bulk-sample eine Referenzimplementierung für die Aufnahme in Produktionsmaßstab bereit. Es veranschaulicht die folgenden Schlüsseleinstellungen:

  • Automatisch abgestimmte Mikrobatchgrößen: Im Beispiel werden Batchgrößen von 1 bis 100 Dokumenten pro physischer Partition dynamisch an den Sättigungsdurchsatz angepasst, während die Drosselung überschaubar bleibt.
  • Konfigurierbare Wiederholungsanzahl: Der Standardwert ist 20 Wiederholungsversuche pro Batch. Passen Sie den Wert basierend auf Ihrer Toleranz für vorübergehende Fehler und nachgeschaltete Latenzanforderungen an.
  • Gleichzeitige Batches pro Computer: Der Standardwert ist 8 gleichzeitige Batches. Der empfohlene Bereich beträgt 25–100 % der verfügbaren CPU-Kerne auf der Ingestionsmaschine.

Tip

Beginnen Sie mit den Standardwerten und überwachen Sie die Antwortraten von 429 (ratenbegrenzten) Antworten. Reduzieren Sie gleichzeitige Batches, oder fügen Sie die Durchsatzsteuerung hinzu, wenn eine übermäßige Drosselung auftritt.

Durchsatzsteuerung für freigegebene Container

Wenn mehrere Workloads denselben Container gemeinsam nutzen, verwenden Sie Durchsatzsteuerungsgruppen , um die ru/s zu kappen, die durch Massenaufnahme verbraucht werden, und verhindern Sie, dass andere Workloads verhungern:

Note

Für die Durchsatzsteuerung ist eine unterstützte Mindestversion des Azure Cosmos DB Java SDK v4 erforderlich. Die APIs zur Durchsatzsteuerung sind ebenfalls mit @Beta annotiert und können sich ändern. Überprüfen Sie die aktuellen Versionsanforderungen und den API-Status in der Dokumentation zur Durchsatzsteuerung, bevor Sie das folgende Beispiel verwenden.

ThroughputControlGroupConfig groupConfig =
    new ThroughputControlGroupConfigBuilder()
        .groupName("bulkIngestionGroup")
        .targetThroughputThreshold(0.75) // limit ingestion to 75% of provisioned throughput
        .defaultControlGroup(true)
        .build();

container.enableLocalThroughputControlGroup(groupConfig);

Verwenden Sie stattdessen die globale Durchsatzsteuerung , um Durchsatzgrenzwerte auf mehreren Aufnahmecomputern zu koordinieren.

Referenzimplementierungen

Beispiel Description
Azure-cosmos-distributed-bulk-sample End-to-End verteilte Erfassung mit Auftragsnachverfolgung, neustartbaren Batches, automatisch abgestimmten Mikrobatchgrößen und konfigurierbaren Wiederholungs- und Parallelitätseinstellungen.
ThroughputControlQuickstartAsync.java Lokale Durchsatzsteuerung, globale Durchsatzsteuerung mit einem freigegebenen RU-Grenzwert über einen Metadatencontainer und prioritätsbasierte Drosselung.

Leistungstipps

Berücksichtigen Sie bei Verwendung der Bulk Executor-Bibliothek die folgenden Punkte für eine bessere Leistung:

  • Um die beste Leistung zu erzielen, führen Sie Ihre Anwendung auf einem virtuellen Azure-Computer in der Region aus, die Sie für Ihre Azure Cosmos DB-Kontoschreibvorgänge verwenden.

  • So erreichen Sie einen höheren Durchsatz:

    • Legen Sie die JVM-Heapgröße groß genug fest, um Speicherprobleme bei der Behandlung großer Anzahl von Dokumenten zu vermeiden. Vorgeschlagene Heapgröße: max(3 GB, 3 * sizeof(all documents passed to bulk import API in one batch)).
    • Massenvorgänge verfügen über eine Vorverarbeitungsphase, sodass Sie beim Verarbeiten großer Dokumentenmappen einen höheren Durchsatz erhalten. Beispielsweise ist das Importieren von 10.000.000 Dokumenten durch 10-maliges Ausführen eines Massenimports mit jeweils 1.000.000 Dokumenten effizienter, als ihn 100 Mal mit jeweils 100.000 Dokumenten auszuführen.
  • Instanziieren Sie ein einzelnes CosmosAsyncClient Objekt für die gesamte Anwendung innerhalb eines einzelnen virtuellen Computers, der einem bestimmten Azure Cosmos DB-Container entspricht.

  • Eine einzelne Massenvorgangs-API-Ausführung verbraucht einen großen Teil der CPU- und Netzwerk-E/A des Clientcomputers, indem mehrere Aufgaben intern abgelegt werden. Vermeiden Sie das Spawning mehrerer gleichzeitiger Aufgaben innerhalb Ihres Anwendungsprozesses, bei dem jede Aufgabe API-Aufrufe für Massenvorgänge ausführt. Wenn ein einzelner API-Aufruf eines Massenvorgangs, der auf einem einzelnen virtuellen Computer ausgeführt wird, den gesamten Containerdurchsatz nicht nutzen kann (wenn der Durchsatz > ihres Containers 1 Million RU/s beträgt), erstellen Sie separate virtuelle Computer, um API-Aufrufe für Massenvorgänge gleichzeitig auszuführen.