Erfassen von Daten per Massenvorgang in Azure Cosmos DB for Gremlin unter Verwendung einer Bulk Executor-Bibliothek
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:
Visual Studio 2019 mit der Workload „Azure-Entwicklung“. Mit der Visual Studio 2019 Community Edition können Sie kostenlos beginnen.
Ein Azure-Abonnement. Falls Sie noch nicht über ein Abonnement verfügen, können Sie ein kostenloses Azure-Konto erstellen.
Alternativ dazu können Sie ein kostenloses Azure Cosmos DB-Konto erstellen, für das kein Azure-Abonnement erforderlich ist.
Eine Azure Cosmos DB for Gremlin-Datenbank mit einer unbegrenzten Sammlung. Beginnen Sie mit Azure Cosmos DB for Gremlin in .NET.
Git. Besuchen Sie als Erstes die Seite mit Git-Downloads.
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
- Weitere Informationen zu den Klassen und Methoden, die in diesem Namespace definiert sind, finden Sie in der Open-Source-Java-Dokumentation zu BulkExecutor.
- Weiterführende Informationen finden Sie auch im Artikel Ausführen eines Massenimports von Daten in ein Azure Cosmos DB-SQL-API-Konto mithilfe des .NET SDK. Die Dokumentation zum Bulkmodus ist Teil des .NET V3 SDK.