Dela via

Mata in data i bulk i Azure Cosmos DB for Gremlin med hjälp av ett massexekutorbibliotek

  • Artikel

GÄLLER FÖR: Gremlin

Grafdatabaser behöver ofta mata in data i bulk för att uppdatera en hel graf eller uppdatera en del av den. Azure Cosmos DB, en distribuerad databas och stamnätet i Azure Cosmos DB for Gremlin, är tänkt att fungera bäst när belastningarna är väl fördelade. Massexekutorbibliotek 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 massexekutorbiblioteket för Azure Cosmos DB för att importera och uppdatera grafobjekt till en Azure Cosmos DB för 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 massexekutorbiblioteket 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 hundrafaldigt, vilket gör det till ett idealiskt sätt att utföra inledande datamigreringar eller periodiska dataförflyttningsåtgärder.

Massexekutorbiblioteket finns nu i följande sorter.

.NET

Förutsättningar

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

Om du vill hämta exemplet går du 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 Description
ConnectionString Din tjänst anslutningssträng, som du hittar i avsnittet Nycklar i ditt Azure Cosmos DB för 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 en container inte redan finns 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änobjektanteckningar eller POJO-objekt (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

Kör följande kommando för att använda exemplet:

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

Om du vill hämta exemplet går du till .\azure-cosmos-graph-bulk-executor\java\.

Förutsättningar

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 har konfigurerats 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:

Property beskrivning
sample.sql.host Värdet som tillhandahålls av Azure Cosmos DB. Se till att du använder .NET SDK-URI:n, som du hittar i avsnittet Översikt för 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 du vill köra exemplet 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 i 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 filen pom.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 beskrivning
--vertexCount (-v) Meddelar 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 GraphBulkExecutors, GremlinVertexoch GremlinEdge POJO:er.
--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 en omvandling till GremlinVertex klassen, enligt beskrivningen i följande tabell:

Klassanteckning beskrivning
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 undanta isSpecial fältet från egenskapen som skrivs till databasen.

Klassen RelationshipEdge

Klassen RelationshipEdge är ett mångsidigt domänobjekt. Genom att använda etikettanteckningen på fältnivå kan du skapa en dynamisk samling kanttyper, som du ser i följande tabell:

Klassanteckning beskrivning
GremlinEdge Dekorationen GremlinEdge i klassen definierar namnet på fältet för den angivna partitionsnyckeln. När du skapar ett edge-dokument 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 är 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 de 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 beskrivning
startTime När System.nanoTime() processen startade.
endTime När System.nanoTime() processen är klar.
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 beskrivning
Skapa exempelhörn Hur lång tid det tar att fabricera den begärda volymen av 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 beskrivning
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