Erfassen von Daten per Massenvorgang in Azure Cosmos DB for Gremlin unter Verwendung einer Bulk Executor-Bibliothek

  • Artikel

GILT FÜR: Gremlin

Graphdatenbanken müssen häufig Massen von Daten erfassen, um einen Graph ganz oder teilweise zu aktualisieren. Azure Cosmos DB – eine verteilte Datenbank und das Backbone von Azure Cosmos DB for Gremlin – funktioniert am besten, wenn die Lasten gut verteilt sind. Bulk Executor-Bibliotheken in Azure Cosmos DB sind dafür konzipiert, diese einzigartige Fähigkeit von Azure Cosmos DB nutzbar zu machen und für optimale Leistung zu sorgen. Weitere Informationen finden Sie unter Introducing bulk support in the .NET SDK (Einführung in die Unterstützung von Massenvorgängen im .NET SDK).

In diesem Tutorial erfahren Sie, wie Sie die Bulk Executor-Bibliothek von Azure Cosmos DB verwenden, um graph-Objekte in einen Azure Cosmos DB for Gremlin-Container zu importieren und zu aktualisieren. In diesem Prozess verwenden Sie die Bibliothek, um vertex- und edge-Objekte (Vertex bzw. Kante) programmgesteuert zu erstellen und dann mehrere Objekte pro Netzwerkanforderung einzufügen.

Anstatt Gremlin-Abfragen an eine Datenbank zu senden, wobei Befehle einzeln nacheinander ausgewertet und dann ausgeführt werden, verwenden Sie die Bulk Executor-Bibliothek, um Objekte lokal zu erstellen und zu überprüfen. Nachdem die Bibliothek die graph-Objekte initialisiert hat, können Sie diese sequenziell an den Datenbankdienst senden.

Mit dieser Methode können Sie die Datenerfassung um das Hundertfache beschleunigen – damit eignet sich diese Methode ideal für die Erstmigration von Daten oder regelmäßige Datenverschiebungsvorgänge.

Die Bulk Executor-Bibliothek ist in mehreren Varianten verfügbar.

.NET

Voraussetzungen

Bevor Sie beginnen, sollten Sie sicherstellen, dass Sie über Folgendes verfügen:

Klon

Um dieses Beispiel zu verwenden, führen Sie den folgenden Befehl aus:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Navigieren Sie zum Abrufen des Beispiels zu .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Beispiel


IGraphBulkExecutor graphBulkExecutor = new GraphBulkExecutor("MyConnectionString", "myDatabase", "myContainer");

List<IGremlinElement> gremlinElements = new List<IGremlinElement>();
gremlinElements.AddRange(Program.GenerateVertices(Program.documentsToInsert));
gremlinElements.AddRange(Program.GenerateEdges(Program.documentsToInsert));
BulkOperationResponse bulkOperationResponse = await graphBulkExecutor.BulkImportAsync(
    gremlinElements: gremlinElements,
    enableUpsert: true);

Execute

Ändern Sie die Parameter wie in der folgenden Tabelle beschrieben:

Parameter BESCHREIBUNG
ConnectionString Ihre Dienstverbindungszeichenfolge, die Sie im Abschnitt Schlüssel Ihres Azure Cosmos DB for Gremlin-Kontos finden. Er ist als AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>; formatiert.
DatabaseName, ContainerName Die Namen der Zieldatenbank und des Zielcontainers.
DocumentsToInsert Die Anzahl der zu generierenden Dokumente (nur für synthetische Daten relevant).
PartitionKey Stellt sicher, dass während der Datenerfassung ein Partitionsschlüssel für jedes Dokument angegeben wird.
NumberOfRUs Ist nur relevant, wenn ein Container noch nicht vorhanden ist und während der Ausführung erstellt werden muss.

Laden Sie die vollständige Beispielanwendung in .NET hier herunter.

Java

Beispielverwendung

Das folgende Beispiel veranschaulicht die Verwendung des GraphBulkExecutor-Pakets. Diese Beispiele verwenden entweder Anmerkungen für das domain-Objekt oder direkt POJO-Objekte (Plain Old Java Object). Es wird empfohlen, beide Ansätze auszuprobieren, um zu ermitteln, welcher Ihre Implementierungs- und Leistungsanforderungen besser erfüllt.

Klon

Führen Sie den folgenden Befehl aus, um das Beispiel zu verwenden:

git clone https://github.com/Azure-Samples/azure-cosmos-graph-bulk-executor.git

Navigieren Sie zum Abrufen des Beispiels zu .\azure-cosmos-graph-bulk-executor\java\.

Voraussetzungen

Um dieses Beispiel auszuführen, müssen Sie über Folgendes verfügen:

  • OpenJDK 11
  • Maven
  • Ein Azure Cosmos DB-Konto, das für die Verwendung der Gremlin-API konfiguriert ist

Beispiel

private static void executeWithPOJO(Stream<GremlinVertex> vertices,
                                        Stream<GremlinEdge> edges,
                                        boolean createDocs) {
        results.transitionState("Configure Database");
        UploadWithBulkLoader loader = new UploadWithBulkLoader();
        results.transitionState("Write Documents");
        loader.uploadDocuments(vertices, edges, createDocs);
    }

Konfiguration

Verwenden Sie zum Ausführen des Beispiels die folgende Konfiguration, und ändern Sie sie nach Bedarf.

Die Datei /resources/application.properties definiert die Daten, die zum Konfigurieren von Azure Cosmos DB erforderlich sind. Die erforderlichen Werte werden in der folgenden Tabelle beschrieben:

Eigenschaft Beschreibung
sample.sql.host Der von Azure Cosmos DB bereitgestellte Wert. Stellen Sie sicher, dass Sie die .NET SDK-URI verwenden, die Sie im Abschnitt Übersicht des Azure Cosmos DB-Kontos finden.
sample.sql.key Sie können den primären oder sekundären Schlüssel aus dem Abschnitt Schlüssel des Azure Cosmos DB-Kontos abrufen.
sample.sql.database.name Der Name der Datenbank im Azure Cosmos DB-Konto, für die das Beispiel ausgeführt wird. Wenn die Datenbank nicht gefunden wird, wird sie vom Beispielcode erstellt.
sample.sql.container.name Der Name des Containers in der Datenbank, für den das Beispiel ausgeführt wird. Wenn der Container nicht gefunden wird, wird er vom Beispielcode erstellt.
sample.sql.partition.path Wenn Sie den Container erstellen müssen, verwenden Sie diesen Wert, um den partitionKey-Pfad zu definieren.
sample.sql.allow.throughput Der Container wird so aktualisiert, dass er den hier definierten Durchsatzwert verwendet. Wenn Sie verschiedene Durchsatzoptionen untersuchen, um Ihre Leistungsanforderungen zu erfüllen, müssen Sie den Durchsatz für den Container zurücksetzen, wenn Sie mit Ihrer Erkundung fertig sind. Es fallen Kosten an, wenn der Container mit einem höheren Durchsatz bereitgestellt bleibt.

Execute

Nachdem Sie die Konfiguration Ihrer Umgebung entsprechend geändert haben, führen Sie den folgenden Befehl aus:

mvn clean package

Um für zusätzliche Sicherheit zu sorgen, können Sie auch die Integrationstests ausführen, indem Sie den skipIntegrationTests-Wert in der Datei pom.xml zu false ändern.

Nachdem Sie die Komponententests erfolgreich ausgeführt haben, können Sie den Beispielcode ausführen:

java -jar target/azure-cosmos-graph-bulk-executor-1.0-jar-with-dependencies.jar -v 1000 -e 10 -d

Mit dem obigen Befehl wird das Beispiel mit einem kleinen Batch ausgeführt (1.000 Vertices und etwa 5.000 Kanten). Verwenden Sie die Befehlszeilenargumente in den folgenden Abschnitten, um die Datenmengen und die Beispielversion für die Ausführung anzupassen.

Befehlszeilenargumente

Für die Ausführung dieses Beispiels stehen verschiedene Befehlszeilenargumente zur Verfügung, die in der folgenden Tabelle beschrieben werden:

Argument BESCHREIBUNG
--vertexCount (-v) Teilt der Anwendung mit, wie viele Vertices für Personen generiert werden sollen.
--edgeMax (-e) Teilt der Anwendung mit, wie viele Kanten für jeden Vertex maximal generiert werden sollen. Der Generator wählt zufällig eine Zahl zwischen 1 und dem von Ihnen angegebenen Wert aus.
--domainSample (-d) Teilt der Anwendung mit, dass das Beispiel mit den Domänenstrukturen für Personen und Beziehungen ausgeführt werden soll, anstatt mit den POJOs GraphBulkExecutors, GremlinVertex und GremlinEdge.
--createDocuments (-c) Teilt der Anwendung mit, dass create-Vorgänge verwendet werden sollen. Wenn das Argument nicht vorhanden ist, verwendet die Anwendung standardmäßig upsert-Vorgänge.

Detaillierte Informationen zum Beispiel

Personenvertex

Die Klasse „person“ ist ein einfaches Domänenobjekt, das mit verschiedenen Anmerkungen versehen wurde, um eine Transformation in die Klasse GremlinVertex zu unterstützen, wie in der folgenden Tabelle beschrieben:

Anmerkung zur Klasse Beschreibung
GremlinVertex Verwendet den optionalen Parameter label, um alle Vertices zu definieren, die Sie mithilfe dieser Klasse erstellen.
GremlinId Hiermit wird definiert, welches Feld als ID-Wert verwendet wird. Der Feldname der person-Klasse lautet „ID“ ist, aber diese Angabe ist nicht erforderlich.
GremlinProperty Wird im Feld email verwendet, um den Namen der Eigenschaft zu ändern, wenn diese in der Datenbank gespeichert wird.
GremlinPartitionKey Wird verwendet, um zu definieren, welches Feld in der Klasse den Partitionsschlüssel enthält. Der Feldname, den Sie hier angeben, sollte mit dem Wert übereinstimmen, der durch den Partitionspfad im Container definiert wird.
GremlinIgnore Wird verwendet, um das Feld isSpecial aus der Eigenschaft auszuschließen, die in die Datenbank geschrieben wird.

Die Klasse „RelationshipEdge“

Die Klasse RelationshipEdge ist ein vielseitiges Domänenobjekt. Indem Sie Anmerkungen auf Feldebene verwenden, können Sie eine dynamische Sammlung von Edgetypen erstellen, wie in der folgenden Tabelle gezeigt:

Anmerkung zur Klasse Beschreibung
GremlinEdge Die GremlinEdge-Dekoration für die Klasse definiert den Namen des Felds für den angegebenen Partitionsschlüssel. Wenn Sie ein Kantendokument erstellen, stammen die zugewiesenen Werte aus der Information zum Quellvertex.
GremlinEdgeVertex Zwei Instanzen von GremlinEdgeVertex werden definiert: eine für jede Seite der Kante (Quelle und Ziel). In unserem Beispiel weist das Feld den Datentyp GremlinEdgeVertexInfo auf. Die von der GremlinEdgeVertex-Klasse bereitgestellten Informationen sind für die ordnungsgemäße Kantenerstellung in der Datenbank erforderlich. Eine weitere Option wäre es, als Datentyp der Vertices eine Klasse zu verwenden, die mit den GremlinVertex-Anmerkungen versehen wurde.
GremlinLabel Die Beispielkante verwendet ein Feld, um den label-Wert zu definieren. Es können verschiedene Bezeichnungen definiert werden, da ein und dieselbe Basisdomänenklasse verwendet wird.

Erläuterung der Ausgabe

Die Konsole beendet die Ausführung mit einer JSON-Zeichenfolge, die die Laufzeiten des Beispiels beschreibt. Die JSON-Zeichenfolge enthält die folgenden Informationen:

JSON-Zeichenfolge BESCHREIBUNG
startTime Die System.nanoTime(), an der der Prozess gestartet wurde.
endTime Der System.nanoTime()-Wert, bei dem der Prozess abgeschlossen wurde.
durationInNanoSeconds Die Differenz zwischen dem endTime-Wert und dem startTime-Wert.
durationInMinutes Der durationInNanoSeconds-Wert, umgerechnet in Minuten. Der durationInMinutes-Wert wird als Gleitkommazahl dargestellt, nicht als Zeitwert. Der Wert „2.5“ beispielsweise steht für 2 Minuten und 30 Sekunden.
vertexCount Die Anzahl von generierten Vertices – diese sollte dem Wert entsprechen, der an die Befehlszeilenausführung übergeben wurde.
edgeCount Die Anzahl von generierten Kanten – dieser Wert ist nicht statisch und wird mit einem bestimmten Maß an Zufälligkeit erstellt.
exception Dieser Wert wird nur aufgefüllt, wenn beim Ausführungsversuch eine Ausnahme ausgegeben wird.

Zustandsarray

Das Zustandsarray informiert über die Ausführungsdauer der einzelnen Schritte. Die Schritte werden in der folgenden Tabelle beschrieben:

Ausführungsschritt Beschreibung
Erstellen von Beispielvertices Der Zeitraum, der für die Erzeugung der angeforderten Menge an Personenobjekten erforderlich ist.
Erstellen von Beispielkanten Der Zeitraum, der für die Erzeugung der Beziehungsobjekte erforderlich ist.
Konfigurieren der Datenbank Der Zeitraum, der für die Konfiguration der Datenbank erforderlich ist, basierend auf den in application.properties angegebenen Werten.
Schreiben von Dokumenten Der Zeitraum, der für das Schreiben der Dokumente in die Datenbank erforderlich ist.

Jeder Zustand enthält die folgenden Werte:

Zustandswert BESCHREIBUNG
stateName Der Name des gemeldeten Zustands.
startTime Der System.nanoTime()-Wert am Anfang des Zustands.
endTime Der System.nanoTime()-Wert am Ende des Zustands.
durationInNanoSeconds Die Differenz zwischen dem endTime-Wert und dem startTime-Wert.
durationInMinutes Der durationInNanoSeconds-Wert, umgerechnet in Minuten. Der durationInMinutes-Wert wird als Gleitkommazahl dargestellt, nicht als Zeitwert. Der Wert „2.5“ beispielsweise steht für 2 Minuten und 30 Sekunden.

Nächste Schritte