Ingérer des données en bloc dans Azure Cosmos DB pour Gremlin à l’aide d’une bibliothèque d’exécuteur en bloc

  • Article

S’APPLIQUE À : Gremlin

Les bases de données de graphe doivent souvent ingérer des données en bloc pour actualiser un graphe entier ou mettre à jour une partie de celui-ci. Cosmos DB, qui est une base de données distribuée et l’épine dorsale d’Azure Cosmos DB pour Gremlin, fonctionne de manière optimale lorsque les charges sont bien distribuées. Dans Azure Cosmos DB, les bibliothèques d’exécuteur en bloc sont conçues pour exploiter cette fonctionnalité unique d’Azure Cosmos DB et pour fournir des performances optimales. Pour plus d’informations, consultez Introducing bulk support in the .NET SDK.

Dans ce tutoriel, vous allez voir comment utiliser la bibliothèque de l’exécuteur en bloc .NET d’Azure Cosmos DB pour importer et mettre à jour des objets Graph au sein d’un conteneur Azure Cosmos DB pour Gremlin. Au cours de ce processus, vous allez utiliser la bibliothèque pour créer des objets vertex (sommet) et edge (arête) par programmation, puis insérer plusieurs objets par requête réseau.

Au lieu d’envoyer des requêtes Gremlin à une base de données où les commandes sont évaluées puis exécutées une par une, vous utilisez la bibliothèque d’exécuteur en bloc pour créer et valider les objets en local. Une fois que la bibliothèque a initialisé les objets Graph, elle vous permet de les envoyer séquentiellement au service de base de données.

À l’aide de cette méthode, vous pouvez augmenter les vitesses d’ingestion des données (jusqu’à 100 fois plus rapidement), ce qui la rend idéale pour effectuer les migrations de données initiales ou des opérations périodiques de déplacement de données.

La bibliothèque d’exécuteur en bloc est maintenant disponible dans les variantes suivantes.

.NET

Prérequis

Avant de commencer, veillez à effectuer les étapes suivantes :

Clone

Pour exécuter cet exemple, utilisez la commande suivante :

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

Pour obtenir l’exemple, accédez à .\azure-cosmos-graph-bulk-executor\dotnet\src\.

Exemple


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

Modifiez les paramètres comme le montre le tableau suivant :

Paramètre Description
ConnectionString La chaîne de connexion de votre service que vous trouvez dans la section Clés de votre compte Azure Cosmos DB pour Gremlin. Il est au format suivant : AccountEndpoint=https://<account-name>.documents.azure.com:443/;AccountKey=<account-key>;.
DatabaseName, ContainerName Noms de la base de données et du conteneur cibles.
DocumentsToInsert Nombre de documents à générer (pertinent uniquement pour les données synthétiques).
PartitionKey Garantit qu’une clé de partition est spécifiée avec chaque document pendant l’ingestion des données.
NumberOfRUs Est pertinent uniquement si un conteneur n’existe pas déjà et qu’il doit être créé pendant l’exécution.

Téléchargez l’exemple d’application complet dans .NET.

Java

Exemple d’utilisation

L’exemple d’application suivant montre comment utiliser le package GraphBulkExecutor. Les exemples utilisent soit les annotations d’objet domain, soit directement les objets POJO (c’est-à-dire les objets Java). Il est recommandé d’essayer les deux approches pour déterminer ce qui répond le mieux à vos exigences en matière d’implémentation et de performances.

Clone

Pour utiliser l’exemple, exécutez la commande suivante :

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

Pour obtenir l’exemple, accédez à .\azure-cosmos-graph-bulk-executor\java\.

Prérequis

Pour exécuter cet exemple, vous devez disposer des logiciels suivants :

  • OpenJDK 11
  • Maven
  • Un compte de base de données Azure Cosmos DB configuré pour utiliser l’API Gremlin

Exemple

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

Configuration

Pour exécuter l’exemple, reportez-vous à la configuration suivante et modifiez-la.

Le fichier /resources/application.properties définit les données qui sont nécessaires pour configurer Azure Cosmos DB. Les valeurs nécessaires sont décrites dans le tableau suivant :

Propriété Description
sample.sql.host Valeur fournie par Azure Cosmos DB. Vérifiez que vous utilisez l’URI du SDK .NET, que vous trouverez dans la section Vue d’ensemble du compte Azure Cosmos DB.
sample.sql.key Vous pouvez obtenir la clé primaire ou secondaire à partir de la section Clés du compte Azure Cosmos DB.
sample.sql.database.name Nom de la base de données du compte Azure Cosmos DB sur laquelle exécuter l’exemple. Si aucune base de données n’est trouvée, l’exemple de code en crée une.
sample.sql.container.name Nom du conteneur de la base de données sur lequel exécuter l’exemple. Si aucun conteneur n’est trouvé, l’exemple de code en crée un.
sample.sql.partition.path Si vous devez créer le conteneur, utilisez cette valeur pour définir le chemin partitionKey.
sample.sql.allow.throughput Le conteneur sera mis à jour pour utiliser la valeur de débit définie ici. Si vous explorez différentes options de débit pour répondre à vos besoins en performances, veillez à réinitialiser le débit du conteneur lorsque vous avez terminé votre exploration. Il existe des coûts associés à la sortie du conteneur approvisionné avec un débit plus élevé.

Execute

Une fois que vous avez modifié la configuration en fonction de votre environnement, exécutez la commande suivante :

mvn clean package

Pour plus de sécurité, vous pouvez également exécuter les tests d’intégration en définissant la valeur skipIntegrationTests sur false dans pom.xml.

Une fois que vous avez correctement exécuté les tests unitaires, vous pouvez exécuter l’exemple de code :

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

L’exécution de la commande précédente exécute l’exemple avec un petit lot (1 000 sommets et environ 5 000 arêtes). Utilisez les arguments de ligne de commande des sections suivantes pour ajuster les volumes à exécuter et choisir la version d’exemple à exécuter.

Arguments de ligne de commande

Plusieurs arguments de ligne de commande sont disponibles pendant l’exécution de cet exemple, comme le décrit le tableau suivant :

Argument Description
--vertexCount (-v) Indique à l’application le nombre de sommets Person à générer.
--edgeMax (-e) Indique à l’application le nombre maximal d’arêtes à générer pour chaque sommet. Le générateur sélectionne de manière aléatoire un nombre compris entre 1 et la valeur que vous spécifiez.
--domainSample (-d) Indique à l’application d’exécuter l’exemple à l’aide des structures de domaine Person et Relationship au lieu des POJO GraphBulkExecutors, GremlinVertex et GremlinEdge.
--createDocuments (-c) Indique à l’application d’utiliser des opérations create. Si l’argument n’est pas présent, l’application utilisera par défaut des opérations upsert.

Informations détaillées sur les exemples

Sommet Person

La classe Person est un objet Domain simple qui est décoré de plusieurs annotations afin d’aider à sa transformation en classe GremlinVertex, comme décrit dans le tableau suivant :

Annotation de classe Description
GremlinVertex Utilise le paramètre facultatif label pour définir tous les sommets que vous créez à l’aide de cette classe.
GremlinId Utilisé pour définir le champ qui sera utilisé comme valeur ID. Le nom du champ de la classe Person est ID, mais il n’est pas obligatoire.
GremlinProperty Utilisé dans le champ email pour modifier le nom de la propriété lorsque celle-ci est stockée dans la base de données.
GremlinPartitionKey Utilisé pour définir le champ de la classe qui contient la clé de partition. Le nom de champ que vous fournissez doit correspondre à la valeur définie par le chemin de partition du conteneur.
GremlinIgnore Utilisé pour exclure le champ isSpecial de la propriété écrite dans la base de données.

Classe RelationshipEdge

La classe RelationshipEdge est un objet Domain polyvalent. À l’aide de l’annotation d’étiquette au niveau du champ, vous pouvez créer une collection dynamique de types d’arêtes, comme indiqué dans le tableau suivant :

Annotation de classe Description
GremlinEdge La décoration GremlinEdge de la classe définit le nom du champ pour la clé de partition spécifiée. Lorsque vous créez un document d’arête, la valeur affectée provient des informations des sommets sources.
GremlinEdgeVertex Deux instances de GremlinEdgeVertex sont définies, une pour chaque côté de l’arête (source et destination). Dans l’exemple, le type de données du champ est GremlinEdgeVertexInfo. Les informations fournies par la classe GremlinEdgeVertex sont nécessaires pour que l’arête soit correctement créée dans la base de données. Une autre option consisterait à faire en sorte que le type de données des sommets soit une classe décorée avec les annotations GremlinVertex.
GremlinLabel L’exemple d’arête utilise un champ pour définir la valeur label. Celle-ci permet de définir différentes étiquettes, car elle utilise la même classe Domain de base.

Sortie expliquée

La console termine son exécution avec une chaîne JSON décrivant le temps d’exécution de l’exemple. La chaîne JSON contient les informations suivantes :

Chaîne JSON Description
startTime System.nanoTime() à laquelle le processus a démarré.
endTime Le System.nanoTime() lorsque le processus s’est terminé.
durationInNanoSeconds La différence entre les valeurs endTime et startTime.
durationInMinutes La valeur durationInNanoSeconds, convertie en minutes. La valeur durationInMinutes est représentée sous la forme d’un nombre à virgule flottante, et non une valeur de temps. Par exemple, la valeur 2.5 correspond à 2 minutes et 30 secondes.
vertexCount Volume de sommets générés, qui doit correspondre à la valeur qui est passée dans l’exécution de la ligne de commande.
edgeCount Volume des arêtes générées, qui n’est pas statique et qui est généré avec un élément de caractère aléatoire.
exception Renseigné uniquement si une exception est levée lorsque vous tentez l’exécution.

Tableau d’états

Le tableau d’états donne un aperçu du temps nécessaire à chaque étape de l’exécution. Les étapes sont décrites dans le tableau suivant :

Étape d’exécution Description
Créer des exemples de sommets Temps nécessaire pour fabriquer le volume demandé d’objets personne.
Créer des exemples d’arêtes Temps nécessaire pour fabriquer le volume demandé d’objets relation.
Configurer la base de données Temps nécessaire pour configurer la base de données, en fonction des valeurs fournies dans application.properties.
Écrire des documents Temps nécessaire pour écrire les documents dans la base de données.

Chaque état contient les valeurs suivantes :

Valeur d’état Description
stateName Nom de l’état signalé.
startTime La valeur System.nanoTime() au démarrage de l’état.
endTime La valeur System.nanoTime() à la fin de l’état.
durationInNanoSeconds La différence entre les valeurs endTime et startTime.
durationInMinutes La valeur durationInNanoSeconds, convertie en minutes. La valeur durationInMinutes est représentée sous la forme d’un nombre à virgule flottante, et non une valeur de temps. Par exemple, la valeur 2.5 correspond à 2 minutes et 30 secondes.

Étapes suivantes