Hromadné ingestování dat ve službě Azure Cosmos DB pro Gremlin pomocí knihovny hromadného exekutoru
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í:
Visual Studio 2019 se sadou funkcí Vývoj pro Azure. Se sadou Visual Studio 2019 Community Edition můžete začít zdarma.
Předplatné Azure. Pokud ještě nemáte předplatné, můžete si vytvořit bezplatný účet Azure.
Případně můžete vytvořit bezplatný účet služby Azure Cosmos DB bez předplatného Azure.
Databáze Azure Cosmos DB pro Gremlin s neomezenou kolekcí. Začněte tím, že v .NET přejdete ke službě Azure Cosmos DB pro Gremlin.
Git. Začněte tím, že přejdete na stránku gitu ke stažení .
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 GraphBulkExecutors GremlinVertex , 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.properties ná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
- Další informace o třídách a metodách, které jsou definovány v tomto oboru názvů, najdete v dokumentaci bulkExecutor Java open source.
- Přečtěte si článek o hromadném importu dat do účtu rozhraní SQL API služby Azure Cosmos DB pomocí sady .NET SDK . Tato dokumentace k hromadnému režimu je součástí sady .NET SDK V3.