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

  • Articolo

SI APPLICA A: Gremlin

I database graph spesso devono inserire dati in blocco per aggiornare un intero grafico 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 di 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 bulk in .NET SDK.

Questa esercitazione descrive come usare la libreria di executor bulk di Azure Cosmos DB per importare e aggiornare gli oggetti graph in un contenitore Azure Cosmos DB per Gremlin. Durante questo processo, si usa la libreria per creare oggetti vertice e 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 in locale. Dopo l'inizializzazione sequenziale degli oggetti grafico, la libreria 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, in modo da poter eseguire migrazioni di dati iniziali o operazioni di spostamento periodico dei dati.

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

.NET

Prerequisiti

Prima di iniziare, assicurarsi di avere quanto segue:

Clone

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

Esecuzione

Modificare i parametri, come descritto nella tabella seguente:

Parametro Descrizione
ConnectionString Stringa di connessione del servizio, 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 di destinazione e del contenitore.
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 le annotazioni dell'oggetto di dominio o gli oggetti POJO (oggetto Java precedente normale). È consigliabile provare entrambi gli approcci per determinare quale soluzione soddisfa meglio le esigenze di implementazione e prestazioni.

Clone

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

Configurazione

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 necessari sono descritti nella tabella seguente:

Proprietà Descrizione
sample.sql.host Valore fornito da Azure Cosmos DB. Assicurarsi di usare l'URI .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 per 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 partitionKey percorso.
sample.sql.allow.throughput Il contenitore verrà aggiornato per usare il valore di velocità effettiva definito qui. Se si esplorano 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 dal contenitore di cui è stato effettuato il provisioning con una velocità effettiva maggiore.

Esecuzione

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

mvn clean package

Per la sicurezza aggiunta, è anche possibile eseguire i test di integrazione modificando il skipIntegrationTests valore 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 di piccole dimensioni (1.000 vertici e circa 5.000 bordi). 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

Sono disponibili diversi argomenti della riga di comando durante l'esecuzione di questo esempio, 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 bordi 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 di persona e relazione anziché i GraphBulkExecutorsGremlinVertexPOJO , e GremlinEdge .
--createDocuments (-c) Indica all'applicazione di usare create le operazioni. Se l'argomento non è presente, l'applicazione viene predefinita per l'uso upsert delle operazioni.

Informazioni dettagliate sull'esempio

Vertice persona

La classe person è un semplice oggetto di dominio decorato con diverse annotazioni per consentire una trasformazione nella GremlinVertex classe, 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 Usato per definire quale ID campo verrà usato come valore. Il nome del campo nella classe person è ID, ma non è obbligatorio.
GremlinProperty Usato nel email campo per modificare il nome della proprietà quando viene archiviato nel database.
GremlinPartitionKey Usato per definire il campo nella classe contiene la chiave di partizione. Il nome del campo specificato deve corrispondere al valore definito dal percorso di partizione nel contenitore.
GremlinIgnore Consente di escludere il isSpecial campo dalla proprietà scritta nel database.

Classe RelationshipEdge

La RelationshipEdge classe è 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 GremlinEdge decorazione della 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 ha il tipo di dati del campo come GremlinEdgeVertexInfo. Le informazioni fornite dalla GremlinEdgeVertex classe sono necessarie per la creazione corretta del bordo nel database. Un'altra opzione consiste nel fare in modo che il tipo di dati dei vertici sia una classe decorata con le GremlinVertex annotazioni.
GremlinLabel Il bordo di esempio usa un campo per definire il label valore. Consente di definire varie etichette, perché usa la stessa classe di dominio di base.

Spiegazione dell'output

La console termina 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() in cui è stato avviato il processo.
endTime Oggetto System.nanoTime() al termine del processo.
durationInNanoSeconds Differenza tra i endTime valori e startTime .
durationInMinutes Valore durationInNanoSeconds convertito in minuti. Il durationInMinutes valore è rappresentato come numero float, non come valore di ora. 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 Il volume degli archi generati, che non è statico e viene compilato con un elemento di casualità.
exception Popolato solo se viene generata un'eccezione quando si tenta di eseguire l'esecuzione.

Matrice stati

La matrice degli 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 necessaria per fabbricare il volume richiesto di oggetti persona.
Compilare bordi di esempio Quantità di tempo necessaria per creare gli oggetti relazione.
Configurare il database Quantità di tempo necessaria per configurare il database, in base ai valori forniti in application.properties.
Scrivere documenti Tempo necessario per scrivere i documenti nel database.

Ogni stato contiene i valori seguenti:

Valore dello 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 endTime valori e startTime .
durationInMinutes Valore durationInNanoSeconds convertito in minuti. Il durationInMinutes valore è rappresentato come numero float, non come valore di ora. Ad esempio, il valore 2,5 rappresenta 2 minuti e 30 secondi.

Passaggi successivi