Sdílet prostřednictvím

Hromadná příjem dat ve službě Azure Cosmos DB pro Gremlin pomocí knihovny Bulk Executor

PLATÍ PRO: Skřítek

Grafové databáze často potřebují hromadně ingestovat data, aby bylo možné aktualizovat celý graf nebo aktualizovat jeho část. Azure Cosmos DB, distribuovaná databáze a páteřní síť služby Azure Cosmos DB pro Gremlin, je určená k dosažení nejlepšího výkonu, když jsou zatížení dobře distribuována. Knihovny bulk executoru 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 naleznete v tématu Představujeme hromadnou podporu v sadě .NET SDK.

V tomto kurzu se dozví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 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 následně spouští po jednom, použijete knihovnu bulk executoru k místnímu vytvoření a ověření objektů. Jakmile knihovna inicializuje objekty grafu, umožňuje je odesílat do databázové služby postupně.

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

Knihovna bulk executoru teď přichází v následujících odrůdá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\.

Vzorek


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

Spustit

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

Parametr Popis
ConnectionString Vaše služba připojovací řetězec, kterou najdete v části Klíče vašeho účtu Azure Cosmos DB for Gremlin. Formátuje se 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 vygenerovaných dokumentů (relevantní pouze pro syntetická data).
PartitionKey Zajišťuje, že se klíč oddílu zadává s každým dokumentem během příjmu dat.
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í přímo poznámky k objektu domény nebo objekty POJO (prostý starý objekt Java). Doporučujeme vyzkoušet oba přístupy, abyste zjistili, 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ý tak, aby používal rozhraní Gremlin API

Vzorek

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 služby Azure Cosmos DB pro spuštění ukázky. Pokud se databáze nenajde, vzorový kód ji vytvoří.
sample.sql.container.name Název kontejneru v databázi pro spuštění ukázky. 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é vyhovují vašim požadavkům na výkon, nezapomeňte při zkoumání obnovit propustnost kontejneru. K opuštění kontejneru zřízeného s vyšší propustností jsou spojené náklady.

Spustit

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 souboru pom.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í předchozího příkazu spustí vzorek 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 jakou ukázkovou verzi 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 Popis
--vertexCount (-v) Řekne aplikaci, kolik vrcholů osob se 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 spustila ukázku pomocí struktury domény osob a vztahů místo GraphBulkExecutorsobjektů , GremlinVertexa GremlinEdge POJOs.
--createDocuments (-c) Řekne aplikaci, aby používala create operace. Pokud argument není k dispozici, použije aplikace výchozí použití upsert operací.

Podrobné ukázkové informace

Vrchol osoby

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

Poznámky ke třídě Popis
GremlinVertex Pomocí volitelného label parametru definuje všechny vrcholy, které vytvoříte pomocí této třídy.
GremlinId Slouží k definování pole, které se použije jako ID hodnota. Jméno pole předmětu osoby je ID, ale není povinné.
GremlinProperty Používá se v email poli ke změně názvu vlastnosti, když je uložena v databázi.
GremlinPartitionKey Slouží k definování pole třídy obsahující klíč oddílu. Zadaný název pole by měl odpovídat hodnotě definované 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 všestranný 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:

Poznámky ke třídě Popis
GremlinEdge Dekorace GremlinEdge třídy definuje název pole pro zadaný klíč oddílu. Při vytváření hraničního dokumentu pochází přiřazená hodnota z informací o zdrojovém vrcholu.
GremlinEdgeVertex Jsou definovány GremlinEdgeVertex dvě instance, 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 se vyžadují, aby se hraniční zařízení správně vytvořilo v databázi. Další možností by bylo mít datový typ vrcholů třída, která byla zdobena GremlinVertex poznámkami.
GremlinLabel Ukázková hrana používá pole k definování label hodnoty. 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í řetězcem JSON, který popisuje časy spuštění ukázky. Řetězec JSON obsahuje následující informace:

Řetězec JSON Popis
startTime Kdy System.nanoTime() proces začal.
endTime Po System.nanoTime() dokončení procesu.
durationInNanoSeconds Rozdíl mezi endTime hodnotami a startTime hodnotami
durationInMinutes Hodnota durationInNanoSeconds se převede na minuty. Hodnota durationInMinutes je reprezentována jako číslo s plovoucí hodnotou, nikoli jako časová hodnota. Například hodnota 2,5 představuje 2 minuty a 30 sekund.
vertexCount Svazek 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.
exception Naplněno pouze v případě, že je vyvolán výjimka při pokusu o spuštění.

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í Popis
Sestavení ukázkových vrcholů Doba, kterou trvá vytvoření požadovaného objemu objektů osob.
Sestavení ukázkových okrajů Doba, kterou trvá vytvoření prostředků relace.
Konfigurace databáze Doba potřebnou ke konfiguraci databáze na základě hodnot zadaných v application.propertiessouboru .
Psaní dokumentů Doba, kterou trvá zápis dokumentů do databáze.

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

Hodnota stavu Popis
stateName Název hlášeného stavu.
startTime Hodnota System.nanoTime() při spuštění stavu.
endTime Hodnota System.nanoTime() po dokončení stavu.
durationInNanoSeconds Rozdíl mezi endTime hodnotami a startTime hodnotami
durationInMinutes Hodnota durationInNanoSeconds se převede na minuty. Hodnota durationInMinutes je reprezentována jako číslo s plovoucí hodnotou, nikoli jako časová hodnota. Například hodnota 2,5 představuje 2 minuty a 30 sekund.

Další kroky