Condividi tramite

Inserire i dati in blocco in Azure Cosmos DB per Gremlin usando una libreria bulk executor

  • Articolo

SI APPLICA A: Gremlin

I database a grafo spesso devono inserire i dati in blocco per aggiornare un intero grafo o aggiornare una parte di esso. Azure Cosmos DB, un database distribuito e il backbone di Azure Cosmos DB per Gremlin, è progettato per ottenere prestazioni ottimali quando i carichi sono ben distribuiti. Le librerie dell'executor bulk in Azure Cosmos DB sono progettate per sfruttare questa funzionalità unica di Azure Cosmos DB e offrire prestazioni ottimali. Per altre informazioni, vedere Introduzione al supporto in blocco in .NET SDK.

Questa esercitazione illustra come usare la libreria bulk executor di Azure Cosmos DB per importare e aggiornare gli oggetti grafo in un contenitore Azure Cosmos DB per Gremlin. Durante questo processo, si usa la libreria per creare vertex e oggetti perimetrali a livello di codice e quindi inserire più oggetti per ogni richiesta di rete.

Anziché inviare query Gremlin a un database, in cui i comandi vengono valutati e quindi eseguiti uno alla volta, si usa la libreria dell'executor bulk per creare e convalidare gli oggetti localmente. Dopo che la libreria inizializza gli oggetti grafico, consente di inviarli al servizio di database in sequenza.

Usando questo metodo, è possibile aumentare la velocità di inserimento dei dati fino a un centinaio di volte, che lo rende un modo ideale per eseguire migrazioni iniziali dei dati o operazioni periodiche di spostamento dei dati.

La libreria bulk executor è ora disponibile nelle varietà seguenti.

.NET

Prerequisiti

Prima di iniziare, assicurarsi di disporre degli elementi seguenti:

Clona

Per usare questo esempio, eseguire il comando seguente:

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

Per ottenere l'esempio, passare a .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Esempio


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

Execute

Modificare i parametri, come descritto nella tabella seguente:

Parametro Descrizione
ConnectionString Il servizio stringa di connessione, disponibile nella sezione Chiavi dell'account Azure Cosmos DB per Gremlin. È formattato come AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Nomi del database e del contenitore di destinazione.
DocumentsToInsert Numero di documenti da generare (rilevanti solo per i dati sintetici).
PartitionKey Assicura che venga specificata una chiave di partizione con ogni documento durante l'inserimento dei dati.
NumberOfRUs È rilevante solo se un contenitore non esiste già e deve essere creato durante l'esecuzione.

Scaricare l'applicazione di esempio completa in .NET.

Java

Esempio di utilizzo

L'applicazione di esempio seguente illustra come usare il pacchetto GraphBulkExecutor. Gli esempi usano direttamente gli oggetti di dominio o POJO (classici oggetti Java). È consigliabile provare entrambi gli approcci per determinare quale approccio soddisfi meglio le esigenze di implementazione e prestazioni.

Clona

Per usare l'esempio, eseguire il comando seguente:

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

Per ottenere l'esempio, passare a .\azure-cosmos-graph-bulk-executor\java\.

Prerequisiti

Per eseguire questo esempio, è necessario disporre del software seguente:

  • OpenJDK 11
  • Maven
  • Un account Azure Cosmos DB configurato per l'uso dell'API Gremlin

Esempio

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

Impostazione

Per eseguire l'esempio, fare riferimento alla configurazione seguente e modificarla in base alle esigenze.

Il file /resources/application.properties definisce i dati necessari per configurare Azure Cosmos DB. I valori obbligatori sono descritti nella tabella seguente:

Proprietà Descrizione
sample.sql.host Valore fornito da Azure Cosmos DB. Assicurarsi di usare l'URI di .NET SDK, disponibile nella sezione Panoramica dell'account Azure Cosmos DB.
sample.sql.key È possibile ottenere la chiave primaria o secondaria dalla sezione Chiavi dell'account Azure Cosmos DB.
sample.sql.database.name Nome del database all'interno dell'account Azure Cosmos DB in cui eseguire l'esempio. Se il database non viene trovato, il codice di esempio lo crea.
sample.sql.container.name Nome del contenitore all'interno del database in cui eseguire l'esempio. Se il contenitore non viene trovato, il codice di esempio lo crea.
sample.sql.partition.path Se è necessario creare il contenitore, usare questo valore per definire il percorso partitionKey.
sample.sql.allow.throughput Il contenitore verrà aggiornato per usare il valore di velocità effettiva definito qui. Se si stanno esplorando varie opzioni di velocità effettiva per soddisfare le esigenze di prestazioni, assicurarsi di reimpostare la velocità effettiva nel contenitore al termine dell'esplorazione. Sono previsti costi associati all'uscita del contenitore di cui è stato effettuato il provisioning con una velocità effettiva più elevata.

Execute

Dopo aver modificato la configurazione in base all'ambiente, eseguire il comando seguente:

mvn clean package

Per una maggiore sicurezza, è anche possibile eseguire i test di integrazione modificando il valore skipIntegrationTests nel file pom.xml in false.

Dopo aver eseguito correttamente gli unit test, è possibile eseguire il codice di esempio:

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

L'esecuzione del comando precedente esegue l'esempio con un batch piccolo (1.000 vertici e circa 5.000 archi). Usare gli argomenti della riga di comando nelle sezioni seguenti per modificare i volumi eseguiti e la versione di esempio da eseguire.

Argomenti della riga di comando

Durante l'esecuzione di questo esempio sono disponibili diversi argomenti della riga di comando, come descritto nella tabella seguente:

Argomento Descrizione
--vertexCount (-v) Indica all'applicazione il numero di vertici di persona da generare.
--edgeMax (-e) Indica all'applicazione il numero massimo di archi da generare per ogni vertice. Il generatore seleziona in modo casuale un numero compreso tra 1 e il valore specificato.
--domainSample (-d) Indica all'applicazione di eseguire l'esempio usando le strutture di dominio person e relationship anziché GraphBulkExecutors, GremlinVertex e GremlinEdge POJO.
--createDocuments (-c) Indica all'applicazione di usare operazioni create. Se l'argomento non è presente, l'applicazione usa per impostazione predefinita operazioni upsert.

Informazioni dettagliate sull'esempio

Vertice Person

La classe Person è un oggetto di dominio semplice decorato con diverse annotazioni per facilitare una trasformazione nella classe GremlinVertex, come descritto nella tabella seguente:

Annotazione della classe Descrizione
GremlinVertex Usa il parametro facoltativo label per definire tutti i vertici creati usando questa classe.
GremlinId Consente di definire quale campo verrà usato come valore ID. Il nome del campo nella classe person è ID, ma non è obbligatorio.
GremlinProperty Usato nel campo email per modificare il nome della proprietà quando viene archiviato nel database.
GremlinPartitionKey Consente di definire il campo nella classe contenente la chiave di partizione. Il nome del campo specificato deve corrispondere al valore definito dal percorso della partizione nel contenitore.
GremlinIgnore Usato per escludere il campo isSpecial dalla proprietà scritta nel database.

Classe RelationshipEdge

La classe RelationshipEdge è un oggetto di dominio versatile. Usando l'annotazione etichetta a livello di campo, è possibile creare una raccolta dinamica di tipi di arco, come illustrato nella tabella seguente:

Annotazione della classe Descrizione
GremlinEdge La decorazione GremlinEdge sulla classe definisce il nome del campo per la chiave di partizione specificata. Quando si crea un documento perimetrale, il valore assegnato proviene dalle informazioni sui vertici di origine.
GremlinEdgeVertex Vengono definite due istanze di GremlinEdgeVertex, una per ogni lato del bordo (origine e destinazione). L'esempio include il tipo di dati del campo come GremlinEdgeVertexInfo. Le informazioni fornite dalla classe GremlinEdgeVertex sono necessarie affinché il bordo venga creato correttamente nel database. Un'altra opzione consiste nel fare in modo che il tipo di dati dei vertici sia una classe decorata con le annotazioni GremlinVertex.
GremlinLabel Il bordo di esempio usa un campo per definire il valore label. Consente di definire varie etichette, perché usa la stessa classe di dominio di base.

Spiegazione dell'output

La console completa l'esecuzione con una stringa JSON che descrive i tempi di esecuzione dell'esempio. La stringa JSON contiene le informazioni seguenti:

Stringa JSON Descrizione
startTime System.nanoTime() all'avvio del processo.
endTime System.nanoTime() al termine del processo.
durationInNanoSeconds Differenza tra i valori endTime e startTime.
durationInMinutes Valore durationInNanoSeconds, convertito in minuti. Il valore durationInMinutes è rappresentato come numero float, non come valore di tempo. Ad esempio, il valore 2,5 rappresenta 2 minuti e 30 secondi.
vertexCount Volume dei vertici generati, che deve corrispondere al valore passato nell'esecuzione della riga di comando.
edgeCount Volume di archi generati, che non è statico ed è costruito con un elemento di casualità.
exception Popolato solo se viene generata un'eccezione quando si tenta di eseguire l'esecuzione.

Matrice di stati

La matrice di stati fornisce informazioni dettagliate sul tempo necessario per ogni passaggio all'interno dell'esecuzione. I passaggi sono descritti nella tabella seguente:

Passaggio di esecuzione Descrizione
Compilare vertici di esempio Quantità di tempo necessario per fabbricare il volume richiesto di oggetti persona.
Compilare i bordi di esempio Quantità di tempo impiegato per creare gli oggetti relazione.
Configurare il database Quantità di tempo necessario per configurare il database, in base ai valori forniti in application.properties.
Scrivere documenti Quantità di tempo necessario per scrivere i documenti nel database.

Ogni stato contiene i valori seguenti:

Valore di stato Descrizione
stateName Nome dello stato segnalato.
startTime Valore System.nanoTime() all'avvio dello stato.
endTime Valore System.nanoTime() al termine dello stato.
durationInNanoSeconds Differenza tra i valori endTime e startTime.
durationInMinutes Valore durationInNanoSeconds, convertito in minuti. Il valore durationInMinutes è rappresentato come numero float, non come valore di tempo. Ad esempio, il valore 2,5 rappresenta 2 minuti e 30 secondi.

Passaggi successivi