Hromadné ingestování dat ve službě Azure Cosmos DB pro Gremlin pomocí knihovny Bulk Executor

  • Článek

PLATÍ PRO: Gremlin

Grafové databáze často potřebují ingestovat data hromadně, aby bylo možné aktualizovat celý graf nebo jeho část. Azure Cosmos DB, distribuovaná databáze a páteřní síť Azure Cosmos DB pro Gremlin, je určená k tomu, aby fungovala co nejlépe, když jsou zatížení dobře distribuovaná. Knihovny bulk executoru ve službě Azure Cosmos DB jsou navržené tak, aby využívaly tuto jedinečnou možnost služby Azure Cosmos DB a poskytovaly optimální výkon. Další informace najdete v tématu Představení hromadné podpory v sadě .NET SDK.

V tomto kurzu zjistíte, jak pomocí knihovny Bulk Executor služby Azure Cosmos DB importovat a aktualizovat objekty grafu do kontejneru Azure Cosmos DB pro Gremlin. Během tohoto procesu pomocí knihovny programově vytvoříte objekty vrcholů a hran a pak vložíte více objektů na síťový požadavek.

Místo odesílání dotazů Gremlin do databáze, kde se příkazy vyhodnocují a následně spouští po jednom, použijete k místnímu vytvoření a ověření objektů knihovnu Bulk Executor. Jakmile knihovna inicializuje objekty grafu, umožní vám je postupně odesílat do databázové služby.

Pomocí této metody můžete zvýšit rychlost příjmu dat až stonásobně, což z ní dělá ideální způsob, jak provádět počáteční migrace dat nebo pravidelné operace přesunu dat.

Knihovna Bulk Executor se teď dodává v následujících variantách.

.NET

Požadavky

Než začnete, ujistěte se, že máte následující:

Clone

Pokud chcete použít tuto ukázku, spusťte následující příkaz:

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

Pokud chcete získat ukázku, přejděte na .\azure-cosmos-graph-bulk-executor\dotnet\src\adresu .

Ukázka


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

Spuštěním

Upravte parametry, jak je popsáno v následující tabulce:

Parametr Popis
ConnectionString Připojovací řetězec služby, který najdete v části Klíče vašeho účtu Azure Cosmos DB pro Gremlin. Je naformátovaný jako AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Názvy cílové databáze a kontejneru
DocumentsToInsert Počet dokumentů, které se mají vygenerovat (relevantní pouze pro syntetická data).
PartitionKey Zajišťuje, že se při příjmu dat u každého dokumentu zadá klíč oddílu.
NumberOfRUs Je relevantní jenom v případě, že kontejner ještě neexistuje a je potřeba ho vytvořit během provádění.

Stáhněte si úplnou ukázkovou aplikaci v .NET.

Java

Ukázkové využití

Následující ukázková aplikace ukazuje, jak používat balíček GraphBulkExecutor. Ukázky používají buď poznámky k objektu domény , nebo objekty POJO (prostý starý objekt Java). Doporučujeme vyzkoušet oba přístupy a určit, který z nich lépe vyhovuje vašim požadavkům na implementaci a výkon.

Clone

Pokud chcete použít ukázku, spusťte následující příkaz:

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

Pokud chcete získat ukázku, přejděte na .\azure-cosmos-graph-bulk-executor\java\adresu .

Požadavky

Pokud chcete spustit tuto ukázku, musíte mít následující software:

  • OpenJDK 11
  • Maven
  • Účet služby Azure Cosmos DB nakonfigurovaný tak, aby používal rozhraní Gremlin API

Ukázka

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

Konfigurace

Pokud chcete ukázku spustit, projděte si následující konfiguraci a podle potřeby ji upravte.

Soubor /resources/application.properties definuje data potřebná ke konfiguraci služby Azure Cosmos DB. Požadované hodnoty jsou popsány v následující tabulce:

Vlastnost Popis
sample.sql.host Hodnota poskytovaná službou Azure Cosmos DB. Ujistěte se, že používáte identifikátor URI sady .NET SDK, který najdete v části Přehled účtu služby Azure Cosmos DB.
sample.sql.key Primární nebo sekundární klíč můžete získat v části Klíče účtu služby Azure Cosmos DB.
sample.sql.database.name Název databáze v rámci účtu Azure Cosmos DB, pro který se má ukázka spustit. Pokud se databáze nenajde, vzorový kód ji vytvoří.
sample.sql.container.name Název kontejneru v databázi, pro který se má ukázka spustit. Pokud se kontejner nenajde, vzorový kód ho vytvoří.
sample.sql.partition.path Pokud potřebujete vytvořit kontejner, použijte tuto hodnotu k definování partitionKey cesty.
sample.sql.allow.throughput Kontejner se aktualizuje tak, aby používal hodnotu propustnosti, která je zde definovaná. Pokud zkoumáte různé možnosti propustnosti, které splňují vaše požadavky na výkon, nezapomeňte propustnost kontejneru resetovat, až budete s průzkumem hotovi. S ponechání zřízeného kontejneru s vyšší propustností jsou spojené náklady.

Spuštěním

Po úpravě konfigurace podle vašeho prostředí spusťte následující příkaz:

mvn clean package

Pro zvýšení bezpečnosti můžete také spustit integrační testy změnou skipIntegrationTests hodnoty v souborupom.xml na false.

Po úspěšném spuštění testů jednotek můžete spustit ukázkový kód:

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

Spuštěním předchozího příkazu se ukázka spustí s malou dávkou (1 000 vrcholů a přibližně 5 000 hran). Pomocí argumentů příkazového řádku v následujících částech můžete upravit svazky, které se spouští, a ukázkovou verzi, která se má spustit.

Argumenty příkazového řádku

Při spuštění této ukázky je k dispozici několik argumentů příkazového řádku, jak je popsáno v následující tabulce:

Argument Description
--vertexCount (-v) Sděluje aplikaci, kolik vrcholů osob má vygenerovat.
--edgeMax (-e) Řekne aplikaci maximální počet hran, které se mají vygenerovat pro každý vrchol. Generátor náhodně vybere číslo od 1 do zadané hodnoty.
--domainSample (-d) Řekne aplikaci, aby ukázku spustila pomocí doménových struktur osob a vztahů místo GraphBulkExecutorsobjektů , GremlinVertexa GremlinEdge POJO.
--createDocuments (-c) Říká aplikaci, aby používala create operace. Pokud argument není k dispozici, aplikace ve výchozím nastavení použije upsert operace.

Podrobné informace o ukázce

Vrchol osoby

Třída person je jednoduchý objekt domény, který je zdoben několika poznámkami, které pomáhají transformovat do GremlinVertex třídy, jak je popsáno v následující tabulce:

Anotace třídy Description
GremlinVertex Používá volitelný label parametr k definování všech vrcholů, které vytvoříte pomocí této třídy.
GremlinId Slouží k definování pole, které se použije jako ID hodnota. Název pole ve třídě person je ID, ale není povinný.
GremlinProperty Používá se u email pole ke změně názvu vlastnosti uložené v databázi.
GremlinPartitionKey Slouží k definování pole ve třídě, které obsahuje klíč oddílu. Zadaný název pole by se měl shodovat s hodnotou definovanou cestou k oddílu v kontejneru.
GremlinIgnore Slouží k vyloučení isSpecial pole z vlastnosti, která se zapisuje do databáze.

The RelationshipEdge – třída

Třída RelationshipEdge je univerzální objekt domény. Pomocí poznámky popisku na úrovni pole můžete vytvořit dynamickou kolekci typů hran, jak je znázorněno v následující tabulce:

Anotace třídy Description
GremlinEdge Dekorace GremlinEdge ve třídě definuje název pole pro zadaný klíč oddílu. Když vytvoříte hraniční dokument, přiřazená hodnota pochází z informací o zdrojovém vrcholu.
GremlinEdgeVertex Jsou definovány dvě instance , GremlinEdgeVertex jedna pro každou stranu okraje (zdroj a cíl). Naše ukázka má datový typ pole jako GremlinEdgeVertexInfo. Informace poskytované GremlinEdgeVertex třídou jsou vyžadovány pro správné vytvoření edge v databázi. Další možností je, aby datový typ vrcholů byl třída, která byla zdobena poznámkami GremlinVertex .
GremlinLabel Vzorová hrana používá k definování label hodnoty pole. Umožňuje definovat různé popisky, protože používá stejnou základní třídu domény.

Vysvětlení výstupu

Konzola dokončí spuštění s řetězcem JSON, který popisuje časy spuštění ukázky. Řetězec JSON obsahuje následující informace:

Řetězec ve formátu JSON Description
startTime Kdy System.nanoTime() proces začal.
endTime Po System.nanoTime() dokončení procesu.
durationInNanoSeconds Rozdíl mezi endTime hodnotami a startTime
durationInMinutes Hodnota durationInNanoSeconds převedená na minuty. Hodnota durationInMinutes je reprezentována jako plovoucí číslo, nikoli jako časová hodnota. Například hodnota 2,5 představuje 2 minuty a 30 sekund.
vertexCount Objem vygenerovaných vrcholů, který by měl odpovídat hodnotě předané do provádění příkazového řádku.
edgeCount Objem vygenerovaných hran, který není statický a je sestaven s prvkem náhodnosti.
Výjimka Vyplněno pouze v případě, že při pokusu o spuštění dojde k výjimce.

Pole Stavů

Pole stavů poskytuje přehled o tom, jak dlouho každý krok v rámci provádění trvá. Postup je popsaný v následující tabulce:

Krok spuštění Description
Sestavení ukázkových vrcholů Doba potřebná k vytvoření požadovaného objemu objektů osob.
Sestavení ukázkových okrajů Doba potřebná k vytvoření objektu relace.
Konfigurace databáze Doba potřebná ke konfiguraci databáze na základě hodnot zadaných v application.propertiesnástroji .
Psaní dokumentů Doba potřebná k zápisu dokumentů do databáze.

Každý stav obsahuje následující hodnoty:

Hodnota stavu Description
stateName Název hlášeného stavu.
startTime Hodnota System.nanoTime() , kdy stav začal.
endTime Hodnota System.nanoTime() po dokončení stavu.
durationInNanoSeconds Rozdíl mezi endTime hodnotami a startTime
durationInMinutes Hodnota durationInNanoSeconds převedená na minuty. Hodnota durationInMinutes je reprezentována jako plovoucí číslo, nikoli jako časová hodnota. Například hodnota 2,5 představuje 2 minuty a 30 sekund.

Další kroky