Gegevens bulksgewijs opnemen in De Azure Cosmos DB voor Gremlin met behulp van een bibliotheek voor bulkuitvoering

  • Artikel

VAN TOEPASSING OP: Gremlin

Grafiekdatabases moeten vaak bulksgewijs gegevens opnemen om een hele grafiek te vernieuwen of een deel ervan bij te werken. Azure Cosmos DB, een gedistribueerde database en de ruggengraat van de Azure Cosmos DB voor Gremlin, is bedoeld om het beste te presteren wanneer de belastingen goed zijn verdeeld. Bulkexecutorbibliotheken in Azure Cosmos DB zijn ontworpen om deze unieke mogelijkheid van Azure Cosmos DB te benutten en optimale prestaties te bieden. Zie Introductie van bulkondersteuning in de .NET SDK voor meer informatie.

In deze zelfstudie leert u hoe u de azure Cosmos DB-bibliotheek voor bulkuitvoering gebruikt om grafiekobjecten te importeren en bij te werken in een Azure Cosmos DB voor Gremlin-container. Tijdens dit proces gebruikt u de bibliotheek om programmatisch hoekpunt - en randobjecten te maken en vervolgens meerdere objecten per netwerkaanvraag in te voegen.

In plaats van Gremlin-query's te verzenden naar een database, waar de opdrachten worden geëvalueerd en vervolgens één voor één worden uitgevoerd, gebruikt u de bibliotheek voor bulkuitvoering om de objecten lokaal te maken en te valideren. Nadat de bibliotheek de grafiekobjecten heeft geïnitialiseerd, kunt u ze sequentieel naar de databaseservice verzenden.

Met deze methode kunt u de gegevensopnamesnelheden maar liefst honderd verhogen, waardoor het een ideale manier is om initiële gegevensmigraties of periodieke gegevensverplaatsingsbewerkingen uit te voeren.

De bulkexecutorbibliotheek is nu beschikbaar in de volgende varianten.

.NET

Vereisten

Voordat u begint, moet u ervoor zorgen dat u over het volgende beschikt:

Klonen

Voer de volgende opdracht uit om dit voorbeeld te gebruiken:

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

Als u het voorbeeld wilt ophalen, gaat u naar .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Voorbeeld


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

Uitvoeren

Wijzig de parameters, zoals beschreven in de volgende tabel:

Parameter Beschrijving
ConnectionString Uw service connection string, die u vindt in de sectie Sleutels van uw Azure Cosmos DB voor Gremlin-account. Deze is opgemaakt als AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName De namen van de doeldatabase en container.
DocumentsToInsert Het aantal documenten dat moet worden gegenereerd (alleen relevant voor synthetische gegevens).
PartitionKey Zorgt ervoor dat bij elk document een partitiesleutel wordt opgegeven tijdens de gegevensopname.
NumberOfRUs Is alleen relevant als er nog geen container bestaat en deze tijdens de uitvoering moet worden gemaakt.

Download de volledige voorbeeldtoepassing in .NET.

Java

Voorbeeldgebruik

In de volgende voorbeeldtoepassing ziet u hoe u het Pakket GraphBulkExecutor gebruikt. In de voorbeelden worden de domeinobjectannotaties of de POJO-objecten (gewoon oud Java-object) rechtstreeks gebruikt. We raden u aan beide benaderingen uit te proberen om te bepalen welke beter voldoet aan uw implementatie- en prestatievereisten.

Klonen

Voer de volgende opdracht uit om het voorbeeld te gebruiken:

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

Als u het voorbeeld wilt ophalen, gaat u naar .\azure-cosmos-graph-bulk-executor\java\.

Vereisten

Als u dit voorbeeld wilt uitvoeren, hebt u de volgende software nodig:

  • OpenJDK 11
  • Maven
  • Een Azure Cosmos DB-account dat is geconfigureerd voor het gebruik van de Gremlin-API

Voorbeeld

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

Configuratie

Als u het voorbeeld wilt uitvoeren, raadpleegt u de volgende configuratie en wijzigt u deze indien nodig.

Het bestand /resources/application.properties definieert de gegevens die vereist zijn voor het configureren van Azure Cosmos DB. De vereiste waarden worden beschreven in de volgende tabel:

Eigenschap Beschrijving
sample.sql.host De waarde die wordt geleverd door Azure Cosmos DB. Zorg ervoor dat u de .NET SDK-URI gebruikt, die u vindt in de sectie Overzicht van het Azure Cosmos DB-account.
sample.sql.key U kunt de primaire of secundaire sleutel ophalen uit de sectie Sleutels van het Azure Cosmos DB-account.
sample.sql.database.name De naam van de database in het Azure Cosmos DB-account om het voorbeeld op uit te voeren. Als de database niet wordt gevonden, wordt deze door de voorbeeldcode gemaakt.
sample.sql.container.name De naam van de container in de database om het voorbeeld op uit te voeren. Als de container niet wordt gevonden, wordt deze door de voorbeeldcode gemaakt.
sample.sql.partition.path Als u de container wilt maken, gebruikt u deze waarde om het partitionKey pad te definiëren.
sample.sql.allow.throughput De container wordt bijgewerkt om de doorvoerwaarde te gebruiken die hier is gedefinieerd. Als u verschillende doorvoeropties verkent om aan uw prestatievereisten te voldoen, moet u de doorvoer voor de container opnieuw instellen wanneer u klaar bent met uw verkenning. Er zijn kosten verbonden aan het laten inrichten van de container met een hogere doorvoer.

Uitvoeren

Nadat u de configuratie hebt gewijzigd op basis van uw omgeving, voert u de volgende opdracht uit:

mvn clean package

Voor extra veiligheid kunt u de integratietests ook uitvoeren door de skipIntegrationTests waarde in het pom.xml-bestand te wijzigen in false.

Nadat u de eenheidstests hebt uitgevoerd, kunt u de voorbeeldcode uitvoeren:

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

Als u de voorgaande opdracht uitvoert, wordt het voorbeeld uitgevoerd met een kleine batch (1000 hoekpunten en ongeveer 5000 randen). Gebruik de opdrachtregelargumenten in de volgende secties om de volumes aan te passen die worden uitgevoerd en welke voorbeeldversie moet worden uitgevoerd.

Opdrachtregelargumenten

Er zijn verschillende opdrachtregelargumenten beschikbaar terwijl u dit voorbeeld uitvoert, zoals beschreven in de volgende tabel:

Argument Beschrijving
--vertexCount (-v) Geeft aan de toepassing door hoeveel hoekpunten van personen moeten worden gegenereerd.
--edgeMax (-e) Vertelt de toepassing het maximum aantal randen dat moet worden gegenereerd voor elk hoekpunt. De generator selecteert willekeurig een getal van 1 tot de waarde die u opgeeft.
--domainSample (-d) Hiermee geeft u de toepassing de opdracht om het voorbeeld uit te voeren met behulp van de domeinstructuren persoon en relatie in plaats van de GraphBulkExecutorsPOJO's , GremlinVertexen GremlinEdge .
--createDocuments (-c) Hiermee wordt aangegeven dat de toepassing bewerkingen moet gebruiken create . Als het argument niet aanwezig is, gebruikt de toepassing standaard bewerkingen upsert .

Gedetailleerde voorbeeldinformatie

Hoekpunt persoon

De klasse person is een eenvoudig domeinobject dat is versierd met verschillende aantekeningen om een transformatie naar de GremlinVertex klasse te helpen, zoals beschreven in de volgende tabel:

Klasaantekening Beschrijving
GremlinVertex Gebruikt de optionele label parameter om alle hoekpunten te definiëren die u maakt met behulp van deze klasse.
GremlinId Wordt gebruikt om te definiëren welk veld als waarde ID wordt gebruikt. De veldnaam van de persoonsklasse is id, maar is niet vereist.
GremlinProperty Wordt in het email veld gebruikt om de naam van de eigenschap te wijzigen wanneer deze wordt opgeslagen in de database.
GremlinPartitionKey Wordt gebruikt om te definiëren welk veld in de klasse de partitiesleutel bevat. De veldnaam die u opgeeft, moet overeenkomen met de waarde die is gedefinieerd door het partitiepad in de container.
GremlinIgnore Wordt gebruikt om het isSpecial veld uit te sluiten van de eigenschap die naar de database wordt geschreven.

De klasse RelationshipEdge

De RelationshipEdge klasse is een veelzijdig domeinobject. Met behulp van de labelaantekening op veldniveau kunt u een dynamische verzameling randtypen maken, zoals wordt weergegeven in de volgende tabel:

Klasaantekening Beschrijving
GremlinEdge De GremlinEdge decoratie van de klasse definieert de naam van het veld voor de opgegeven partitiesleutel. Wanneer u een Edge-document maakt, is de toegewezen waarde afkomstig van de bronpuntgegevens.
GremlinEdgeVertex Er zijn twee exemplaren van GremlinEdgeVertex gedefinieerd, één voor elke kant van de rand (bron en doel). Ons voorbeeld heeft het gegevenstype van het veld als GremlinEdgeVertexInfo. De informatie die door de GremlinEdgeVertex klasse wordt verstrekt, is vereist om de edge correct te maken in de database. Een andere optie is om het gegevenstype van de hoekpunten een klasse te laten zijn die is versierd met de GremlinVertex aantekeningen.
GremlinLabel De voorbeeldrand gebruikt een veld om de label waarde te definiëren. Hiermee kunnen verschillende labels worden gedefinieerd, omdat dezelfde basisdomeinklasse wordt gebruikt.

Uitleg over uitvoer

De uitvoering van de console wordt voltooid met een JSON-tekenreeks die de uitvoeringstijden van het voorbeeld beschrijft. De JSON-tekenreeks bevat de volgende informatie:

JSON-tekenreeks Beschrijving
startTime De System.nanoTime() wanneer het proces is gestart.
endTime De System.nanoTime() wanneer het proces is voltooid.
durationInNanoSeconds Het verschil tussen de endTime waarden en startTime .
durationInMinutes De durationInNanoSeconds waarde, geconverteerd naar minuten. De durationInMinutes waarde wordt weergegeven als een float-getal, niet als een tijdwaarde. Een waarde van 2,5 vertegenwoordigt bijvoorbeeld 2 minuten en 30 seconden.
vertexCount Het volume van gegenereerde hoekpunten, dat moet overeenkomen met de waarde die wordt doorgegeven aan de opdrachtregeluitvoering.
edgeCount Het volume van gegenereerde randen, dat niet statisch is en is gebouwd met een willekeurig element.
Uitzondering Alleen ingevuld als er een uitzondering wordt gegenereerd wanneer u de uitvoering probeert uit te voeren.

Statusmatrix

De statusmatrix geeft inzicht in hoe lang elke stap binnen de uitvoering duurt. De stappen worden beschreven in de volgende tabel:

Uitvoeringsstap Beschrijving
Voorbeeldpunten bouwen De hoeveelheid tijd die nodig is om het aangevraagde volume van persoonsobjecten te fabriceren.
Voorbeeldranden bouwen De hoeveelheid tijd die nodig is om de relatieobjecten te fabriceren.
Database configureren De hoeveelheid tijd die nodig is om de database te configureren, op basis van de waarden die zijn opgegeven in application.properties.
Documenten schrijven De hoeveelheid tijd die nodig is om de documenten naar de database te schrijven.

Elke status bevat de volgende waarden:

Statuswaarde Beschrijving
stateName De naam van de status die wordt gerapporteerd.
startTime De System.nanoTime() waarde wanneer de status is gestart.
endTime De System.nanoTime() waarde wanneer de status is voltooid.
durationInNanoSeconds Het verschil tussen de endTime waarden en startTime .
durationInMinutes De durationInNanoSeconds waarde, geconverteerd naar minuten. De durationInMinutes waarde wordt weergegeven als een float-getal, niet als een tijdwaarde. Een waarde van 2,5 vertegenwoordigt bijvoorbeeld 2 minuten en 30 seconden.

Volgende stappen