Hromadné ingestování dat ve službě Azure Cosmos DB pro Gremlin pomocí knihovny hromadného exekutoru

  • Článek
  • 6 min ke čtení

PLATÍ PRO: Gremlin

Grafové databáze často potřebují hromadně ingestovat data, aby se aktualizoval celý graf nebo jeho část. Služba Azure Cosmos DB, distribuovaná databáze a páteřní síť Azure Cosmos DB pro Gremlin, je určená k tomu, aby fungovala nejlépe, když jsou zatížení správně distribuovaná. Knihovny hromadného exekutoru ve službě Azure Cosmos DB jsou navržené tak, aby využívaly tuto jedinečnou funkci 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 se naučíte používat knihovnu bulk executoru služby Azure Cosmos DB k importu a aktualizaci objektů grafu do kontejneru Azure Cosmos DB for Gremlin. Během tohoto procesu použijete knihovnu k programovému vytvoření vrcholů a hraničních objektů a následnému vložení více objektů na síťový požadavek.

Místo odesílání dotazů Gremlin do databáze, kde se příkazy vyhodnocují a pak spouštějí jeden po druhém, použijete knihovnu bulk executor k místnímu vytvoření a ověření objektů. Jakmile knihovna inicializuje objekty grafu, umožňuje 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í:

Klonování

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

Ukázku získáte tak, že přejdete na .\azure-cosmos-graph-bulk-executor\dotnet\src\.

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 Koncový bod sady .NET SDK, který najdete v části Přehled účtu databáze Azure Cosmos DB for Gremlin. Je naformátovaný jako https://your-graph-database-account.documents.azure.com:443/.
DatabaseName, ContainerName Názvy cílové databáze a kontejneru
DocumentsToInsert Počet dokumentů, které se mají generovat (relevantní pouze pro syntetická data).
PartitionKey Zajišťuje, že při příjmu dat je u každého dokumentu zadán 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 objektu domény , nebo přímo 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.

Klonování

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

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

Ukázku získáte tak, že přejdete na .\azure-cosmos-graph-bulk-executor\java\.

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, který je nakonfigurovaný pro použití 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 popsané v následující tabulce:

Vlastnost Popis
sample.sql.host Hodnota, kterou poskytuje 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 služby Azure Cosmos DB pro spuštění ukázky. Pokud se databáze nenajde, vytvoří ji ukázkový kód.
sample.sql.container.name Název kontejneru v databázi, pro který se má ukázka spustit. Pokud se kontejner nenajde, vytvoří ho ukázkový kód.
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, abyste splnili své požadavky na výkon, nezapomeňte resetovat propustnost kontejneru, 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 testy integrace 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

Během spouš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) Řekne 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 GraphBulkExecutorsGremlinVertex, a GremlinEdge POJO.
--createDocuments (-c) Řekne aplikaci, aby používala create operace. Pokud argument neexistuje, 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ě osoby je ID, ale není povinný.
GremlinProperty Používá se v email poli ke změně názvu vlastnosti uložené v databázi.
GremlinPartitionKey Slouží k definování pole ve třídě obsahujícího klíč oddílu. Zadaný název pole by se měl shodovat s hodnotou definovanou cestou 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ů okrajů, 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í by bylo, 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 se měl shodovat s hodnotou předanou 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