Delen via

Gegevens bulksgewijs opnemen in Azure Cosmos DB voor Gremlin met behulp van een bulkexecutorbibliotheek

  • 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 backbone van Azure Cosmos DB voor Gremlin, is bedoeld om het beste te presteren wanneer de belastingen goed worden gedistribueerd. Bulkexecutorbibliotheken in Azure Cosmos DB zijn ontworpen om deze unieke mogelijkheid van Azure Cosmos DB te benutten en optimale prestaties te bieden. Zie Inleiding tot bulkondersteuning in de .NET SDK voor meer informatie.

In deze zelfstudie leert u hoe u de bulkexecutorbibliotheek van Azure Cosmos DB 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 via een programma hoekpunt- en randobjecten te maken en vervolgens meerdere objecten per netwerkaanvraag in te voegen.

In plaats van Gremlin-query's naar een database te verzenden, waarbij de opdrachten worden geëvalueerd en vervolgens één voor één worden uitgevoerd, gebruikt u de bibliotheek voor bulkexecutor 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.

Door deze methode te gebruiken, kunt u de gegevensopnamesnelheden zoveel verhogen als honderden, waardoor het een ideale manier is om initiële gegevensmigraties of periodieke gegevensverplaatsingsbewerkingen uit te voeren.

De bulkexecutorbibliotheek wordt nu geleverd in de volgende varianten.

.NET

Vereisten

Controleer voordat u begint of u het volgende hebt:

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 Description
ConnectionString Uw service verbindingsreeks, die u vindt in de sectie Sleutels van uw Azure Cosmos DB voor Gremlin-account. Het 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 een partitiesleutel bij elk document wordt opgegeven tijdens gegevensopname.
NumberOfRUs Is alleen relevant als er nog geen container bestaat en deze moet worden gemaakt tijdens de uitvoering.

Download de volledige voorbeeldtoepassing in .NET.

Java

Voorbeeldgebruik

In de volgende voorbeeldtoepassing ziet u hoe u het GraphBulkExecutor-pakket gebruikt. In de voorbeelden worden de aantekeningen van het domeinobject 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, moet u over de volgende software beschikken:

  • 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 het indien nodig.

Het bestand /resources/application.properties definieert de gegevens die nodig zijn om Azure Cosmos DB te configureren. De vereiste waarden worden beschreven in de volgende tabel:

Eigenschappen Beschrijving
sample.sql.host De waarde die wordt geleverd door Azure Cosmos DB. Zorg ervoor dat u de .NET SDK-URI gebruikt. Deze vindt u 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 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 voor het uitvoeren van het voorbeeld. Als de container niet wordt gevonden, wordt deze door de voorbeeldcode gemaakt.
sample.sql.partition.path Als u de container moet 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 te voldoen aan uw prestatievereisten, moet u de doorvoer voor de container opnieuw instellen wanneer u klaar bent met uw verkenning. Er zijn kosten verbonden aan het verlaten van de container die is ingericht met een hogere doorvoer.

Uitvoeren

Nadat u de configuratie hebt gewijzigd volgens uw omgeving, voert u de volgende opdracht uit:

mvn clean package

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

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) Hiermee wordt aangegeven hoeveel hoekpunten voor personen moeten worden gegenereerd.
--edgeMax (-e) Hiermee wordt aan de toepassing het maximum aantal randen aangegeven dat voor elk hoekpunt moet worden gegenereerd. De generator selecteert willekeurig een getal van 1 tot de waarde die u opgeeft.
--domainSample (-d) Geeft aan dat de toepassing het voorbeeld uitvoert met behulp van de persoons- en relatiedomeinstructuren in plaats van de GraphBulkExecutors, GremlinVertexen GremlinEdge POJOs.
--createDocuments (-c) Geeft aan dat de toepassing bewerkingen moet gebruiken create . Als het argument niet aanwezig is, gebruikt de toepassing standaard bewerkingen upsert .

Gedetailleerde voorbeeldinformatie

Hoekpunt van persoon

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

Klasaantekening Beschrijving
GremlinVertex Hiermee gebruikt u 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 wordt gebruikt als de ID waarde. De veldnaam van de persoonsklasse is id, maar dit 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 op 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 bronpuntinformatie.
GremlinEdgeVertex Er worden twee exemplaren 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 rand correct te kunnen maken in de database. Een andere optie is dat het gegevenstype van de hoekpunten een klasse is die is ingericht met de GremlinVertex aantekeningen.
GremlinLabel De voorbeeldrand gebruikt een veld om de label waarde te definiëren. Hiermee kunnen verschillende labels worden gedefinieerd, omdat deze dezelfde basisdomeinklasse gebruikt.

Uitleg over uitvoer

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

JSON-tekenreeks Beschrijving
startTime Het System.nanoTime() moment waarop het proces is gestart.
endTime Het System.nanoTime() moment waarop het proces is voltooid.
durationInNanoSeconds Het verschil tussen de endTime en startTime waarden.
durationInMinutes De durationInNanoSeconds waarde, geconverteerd naar minuten. De durationInMinutes waarde wordt weergegeven als een float-getal, niet als tijdwaarde. Een waarde van 2,5 vertegenwoordigt bijvoorbeeld 2 minuten en 30 seconden.
hoekpuntAantal Het volume van gegenereerde hoekpunten, die overeenkomen met de waarde die wordt doorgegeven aan de uitvoering van de opdrachtregel.
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 in 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 en startTime waarden.
durationInMinutes De durationInNanoSeconds waarde, geconverteerd naar minuten. De durationInMinutes waarde wordt weergegeven als een float-getal, niet als tijdwaarde. Een waarde van 2,5 vertegenwoordigt bijvoorbeeld 2 minuten en 30 seconden.

Volgende stappen