Massinmatning av data i Azure Cosmos DB för Gremlin med hjälp av ett massexecutor-bibliotek

  • Artikel

GÄLLER FÖR: Gremlin

Grafdatabaser behöver ofta mata in data i grupp för att uppdatera en hel graf eller uppdatera en del av den. Azure Cosmos DB, en distribuerad databas och ryggraden i Azure Cosmos DB for Gremlin, är tänkt att fungera bäst när belastningarna är väl fördelade. Massexecutor-bibliotek i Azure Cosmos DB är utformade för att utnyttja den här unika funktionen i Azure Cosmos DB och ge optimala prestanda. Mer information finns i Introduktion till massstöd i .NET SDK.

I den här självstudien får du lära dig hur du använder masskörningsbiblioteket i Azure Cosmos DB för att importera och uppdatera diagramobjekt till en Azure Cosmos DB for Gremlin-container. Under den här processen använder du biblioteket för att skapa hörn - och kantobjekt programmatiskt och sedan infoga flera objekt per nätverksbegäran.

I stället för att skicka Gremlin-frågor till en databas, där kommandona utvärderas och sedan körs en i taget, använder du masskörningsbiblioteket för att skapa och verifiera objekten lokalt. När biblioteket har initierat grafobjekten kan du skicka dem till databastjänsten sekventiellt.

Med den här metoden kan du öka datainmatningshastigheten så mycket som hundrafalt, vilket gör det till ett idealiskt sätt att utföra inledande datamigreringar eller periodiska åtgärder för dataflytt.

Massexecutor-biblioteket finns nu i följande sorter.

.NET

Krav

Kontrollera att du har följande innan du börjar:

Klona

Om du vill använda det här exemplet kör du följande kommando:

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

Hämta exemplet genom att gå till .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Exempel


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

Genomförande

Ändra parametrarna enligt beskrivningen i följande tabell:

Parameter Beskrivning
ConnectionString Din tjänstanslutningssträng, som du hittar i avsnittet Nycklar i ditt Azure Cosmos DB for Gremlin-konto. Den är formaterad som AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Namnen på måldatabasen och containern.
DocumentsToInsert Antalet dokument som ska genereras (endast relevanta för syntetiska data).
PartitionKey Säkerställer att en partitionsnyckel anges med varje dokument under datainmatningen.
NumberOfRUs Är endast relevant om det inte redan finns en container och den måste skapas under körningen.

Ladda ned det fullständiga exempelprogrammet i .NET.

Java

Exempelanvändning

Följande exempelprogram visar hur du använder GraphBulkExecutor-paketet. Exemplen använder antingen domänobjektanteckningarna eller POJO-objekten (vanligt gammalt Java-objekt) direkt. Vi rekommenderar att du provar båda metoderna för att avgöra vilken som bättre uppfyller dina implementerings- och prestandakrav.

Klona

Om du vill använda exemplet kör du följande kommando:

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

Hämta exemplet genom att gå till .\azure-cosmos-graph-bulk-executor\java\.

Krav

Om du vill köra det här exemplet måste du ha följande programvara:

  • OpenJDK 11
  • Maven
  • Ett Azure Cosmos DB-konto som är konfigurerat för att använda Gremlin-API:et

Exempel

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

Om du vill köra exemplet läser du följande konfiguration och ändrar den efter behov.

Filen /resources/application.properties definierar de data som krävs för att konfigurera Azure Cosmos DB. De obligatoriska värdena beskrivs i följande tabell:

Egenskap Beskrivning
sample.sql.host Det värde som tillhandahålls av Azure Cosmos DB. Se till att du använder .NET SDK-URI:n, som du hittar i avsnittet Översikt i Azure Cosmos DB-kontot.
sample.sql.key Du kan hämta den primära eller sekundära nyckeln från avsnittet Nycklar i Azure Cosmos DB-kontot.
sample.sql.database.name Namnet på databasen i Azure Cosmos DB-kontot som exemplet ska köras mot. Om databasen inte hittas skapar exempelkoden den.
sample.sql.container.name Namnet på containern i databasen som exemplet ska köras mot. Om containern inte hittas skapar exempelkoden den.
sample.sql.partition.path Om du behöver skapa containern använder du det här värdet för att definiera partitionKey sökvägen.
sample.sql.allow.throughput Containern uppdateras för att använda dataflödesvärdet som definieras här. Om du utforskar olika dataflödesalternativ för att uppfylla dina prestandakrav måste du återställa dataflödet på containern när du är klar med utforskningen. Det finns kostnader för att lämna containern etablerad med ett högre dataflöde.

Genomförande

När du har ändrat konfigurationen enligt din miljö kör du följande kommando:

mvn clean package

För ökad säkerhet kan du också köra integreringstesterna genom att ändra skipIntegrationTests värdet i filenpom.xml till false.

När du har kört enhetstesterna kan du köra exempelkoden:

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

När du kör föregående kommando körs exemplet med en liten batch (1 000 hörn och ungefär 5 000 kanter). Använd kommandoradsargumenten i följande avsnitt för att justera de volymer som körs och vilken exempelversion som ska köras.

Kommandoradsargument

Flera kommandoradsargument är tillgängliga när du kör det här exemplet, enligt beskrivningen i följande tabell:

Argument Description
--vertexCount (-v) Talar om för programmet hur många personhörn som ska genereras.
--edgeMax (-e) Meddelar programmet det maximala antalet kanter som ska genereras för varje hörn. Generatorn väljer slumpmässigt ett tal från 1 till det värde som du anger.
--domainSample (-d) Instruerar programmet att köra exemplet med hjälp av person- och relationsdomänstrukturerna i stället för GraphBulkExecutorsPOJO:erna , GremlinVertexoch GremlinEdge .
--createDocuments (-c) Instruerar programmet att använda create åtgärder. Om argumentet inte finns använder programmet som standard upsert åtgärder.

Detaljerad exempelinformation

Personhörn

Personklassen är ett enkelt domänobjekt som har dekorerats med flera anteckningar för att hjälpa till med en omvandling till GremlinVertex klassen, enligt beskrivningen i följande tabell:

Klassanteckning Description
GremlinVertex Använder den valfria label parametern för att definiera alla hörn som du skapar med hjälp av den här klassen.
GremlinId Används för att definiera vilket fält som ska användas som ID värde. Fältnamnet på personklassen är ID, men det krävs inte.
GremlinProperty Används i fältet email för att ändra namnet på egenskapen när den lagras i databasen.
GremlinPartitionKey Används för att definiera vilket fält i klassen som innehåller partitionsnyckeln. Det fältnamn som du anger ska matcha det värde som definieras av partitionssökvägen i containern.
GremlinIgnore Används för att exkludera isSpecial fältet från den egenskap som skrivs till databasen.

Klassen RelationshipEdge

Klassen RelationshipEdge är ett mångsidigt domänobjekt. Med hjälp av etikettanteckningen på fältnivå kan du skapa en dynamisk samling kanttyper, som du ser i följande tabell:

Klassanteckning Description
GremlinEdge Dekorationen GremlinEdge i klassen definierar namnet på fältet för den angivna partitionsnyckeln. När du skapar ett kantdokument kommer det tilldelade värdet från källhörnsinformationen.
GremlinEdgeVertex Två instanser av GremlinEdgeVertex definieras, en för varje sida av gränsen (källa och mål). Vårt exempel har fältets datatyp som GremlinEdgeVertexInfo. Informationen som tillhandahålls av GremlinEdgeVertex klassen krävs för att gränsen ska skapas korrekt i databasen. Ett annat alternativ är att datatypen för hörnen ska vara en klass som har dekorerats med anteckningarna GremlinVertex .
GremlinLabel Exempelgränsen använder ett fält för att definiera värdet label . Det gör att olika etiketter kan definieras, eftersom den använder samma basdomänklass.

Förklaring av utdata

Konsolen slutför körningen med en JSON-sträng som beskriver körningstiderna för exemplet. JSON-strängen innehåller följande information:

JSON-sträng Description
startTime När System.nanoTime() processen startade.
endTime När System.nanoTime() processen har slutförts.
durationInNanoSeconds Skillnaden mellan endTime värdena och startTime .
durationInMinutes Värdet durationInNanoSeconds , konverterat till minuter. Värdet durationInMinutes representeras som ett flyttalsnummer, inte ett tidsvärde. Till exempel representerar värdet 2,5 2 minuter och 30 sekunder.
vertexCount Volymen av genererade hörn, som ska matcha värdet som skickas till kommandoradskörningen.
edgeCount Volymen av genererade kanter, som inte är statiska och skapas med ett slumpmässigt element.
-undantag Fylls endast i om ett undantag utlöses när du försöker köra körningen.

Tillståndsmatris

Tillståndsmatrisen ger insikt i hur lång tid varje steg i körningen tar. Stegen beskrivs i följande tabell:

Körningssteg Description
Skapa exempelhörn Hur lång tid det tar att fabricera den begärda volymen personobjekt.
Skapa exempelkanter Hur lång tid det tar att fabricera relationsobjekten.
Konfigurera databas Hur lång tid det tar att konfigurera databasen baserat på de värden som anges i application.properties.
Skriva dokument Hur lång tid det tar att skriva dokumenten till databasen.

Varje tillstånd innehåller följande värden:

Tillståndsvärde Description
stateName Namnet på det tillstånd som rapporteras.
startTime Värdet System.nanoTime() när tillståndet startade.
endTime Värdet System.nanoTime() när tillståndet har slutförts.
durationInNanoSeconds Skillnaden mellan endTime värdena och startTime .
durationInMinutes Värdet durationInNanoSeconds , konverterat till minuter. Värdet durationInMinutes representeras som ett flyttalsnummer, inte ett tidsvärde. Till exempel representerar värdet 2,5 2 minuter och 30 sekunder.

Nästa steg