Prise en charge des graphes Azure Cosmos DB for Gremlin et compatibilité avec les fonctionnalités TinkerPop

  • Article

S’APPLIQUE À : Gremlin

Azure Cosmos DB prend en charge le langage de traversées de graphes Apache Tinkerpop, connu sous le nom de Gremlin. Vous pouvez utiliser le langage Gremlin pour créer des entités de graphes (sommets et arêtes), modifier les propriétés au sein de ces entités, exécuter des requêtes et traversées et supprimer des entités.

Le moteur Azure Cosmos DB Graph suit de près la spécification des étapes de traversée Apache TinkerPop, mais avec quelques différences au niveau de l’implémentation, spécifiques à Azure Cosmos DB. Dans cet article, nous fournissons une procédure pas à pas pour Gremlin, et nous énumérons les fonctionnalités de Gremlin prises en charge par l’API pour Gremlin.

Bibliothèques clientes compatibles

Le tableau suivant présente des pilotes Gremlin courants que vous pouvez utiliser sur Azure Cosmos DB :

Téléchargement Source Mise en route Version prise en charge/recommandée du connecteur
.NET Gremlin.NET sur GitHub Créer un graphe avec .NET 3.4.13
Java Gremlin JavaDoc Créer un graphe avec Java 3.4.13
Python Gremlin-Python sur GitHub Créer un graphe avec Python 3.4.13
Console Gremlin Documents TinkerPop Créer un graphe à l’aide de la console Gremlin 3.4.13
Node.JS Gremlin-JavaScript sur GitHub Créer un graphe avec Node.js 3.4.13
PHP Gremlin-PHP sur GitHub Créer un graphe avec PHP 3.1.0
Go Lang Go Lang Cette bibliothèque a été créée par des contributeurs externes. L’équipe Azure Cosmos DB ne fournit donc aucun support ni maintenance pour celle-ci.

Notes

Les versions du pilote client Gremlin pour la version 3.5.*, 3.6.* présentent des problèmes de compatibilité connus. Nous vous recommandons donc d’utiliser les dernières versions de pilotes prises en charge 3.4.* répertoriées ci-dessus. Ce tableau sera mis à jour lorsque des problèmes de compatibilité ont été résolus pour ces versions de pilotes plus récentes.

Objets graphiques pris en charge

TinkerPop est une norme qui couvre un large éventail de technologies de graphes. Par conséquent, elle dispose de la terminologie standard utilisée pour décrire les fonctionnalités offertes par un fournisseur de graphes. Azure Cosmos DB fournit une base de données de graphes permanente, concurrentielle et accessible en écriture qui peut être partitionnée entre plusieurs serveurs ou clusters.

Le tableau suivant répertorie les fonctionnalités TinkerPop implémentées par Azure Cosmos DB :

Category Implémentation d’Azure Cosmos DB Notes
Fonctionnalités de graphe Fournit la persistance et ConcurrentAccess. Conçu pour prendre en charge les transactions Les méthodes de l’ordinateur peuvent être implémentées via le connecteur Spark.
Fonctionnalités variables Prend en charge les types Boolean, Integer, Byte, Double, Float, Long, String Prend en charge les types primitifs, et est compatible avec des types complexes via un modèle de données
Fonctionnalités de sommet Prend en charge RemoveVertices, MetaProperties, AddVertices, MultiProperties, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Prend en charge la création, la modification et la suppression de sommet
Fonctionnalités de propriétés de sommet StringIds, UserSuppliedIds, AddProperty, RemoveProperty, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Prend en charge la création, la modification et la suppression des propriétés de sommet
Fonctionnalités d’arête AddEdges, RemoveEdges, StringIds, UserSuppliedIds, AddProperty, RemoveProperty Prend en charge la création, la modification et la suppression d’arêtes
Fonctionnalités de propriétés d’arête Properties, BooleanValues, ByteValues, DoubleValues, FloatValues, IntegerValues, LongValues, StringValues Prend en charge la création, la modification et la suppression d’arêtes

Format de communication Gremlin

Azure Cosmos DB utilise le format JSON quand les résultats des opérations Gremlin sont retournés. Azure Cosmos DB prend actuellement en charge le format JSON. Par exemple, l’extrait de code suivant montre une représentation JSON d’un sommet retourné au client à partir d’Azure Cosmos DB :

  {
    "id": "a7111ba7-0ea1-43c9-b6b2-efc5e3aea4c0",
    "label": "person",
    "type": "vertex",
    "outE": {
      "knows": [
        {
          "id": "3ee53a60-c561-4c5e-9a9f-9c7924bc9aef",
          "inV": "04779300-1c8e-489d-9493-50fd1325a658"
        },
        {
          "id": "21984248-ee9e-43a8-a7f6-30642bc14609",
          "inV": "a8e3e741-2ef7-4c01-b7c8-199f8e43e3bc"
        }
      ]
    },
    "properties": {
      "firstName": [
        {
          "value": "Thomas"
        }
      ],
      "lastName": [
        {
          "value": "Andersen"
        }
      ],
      "age": [
        {
          "value": 45
        }
      ]
    }
  }

Les propriétés utilisées par le format JSON pour les sommets sont décrites ci-dessous :

Propriété Description
id ID du sommet. Doit être unique (en association avec la valeur de _partition, si applicable). Si aucune valeur n’est fournie, un GUID est fourni automatiquement.
label Intitulé du sommet. Cette propriété est utilisée pour décrire le type d’entité.
type Utilisé pour distinguer les sommets des documents non-graphes
properties Sac de propriétés définies par l’utilisateur associé au sommet. Chaque propriété peut avoir plusieurs valeurs.
_partition Clé de partition du sommet. Utilisée pour le partitionnement de graphe.
outE Cette propriété contient une liste des arêtes externes d’un sommet. Permet de stocker les informations de contiguïté avec des sommets pour une exécution rapide des traversées. Les arêtes sont regroupées en fonction de leurs intitulés.

Chaque propriété peut stocker plusieurs valeurs dans un tableau.

Propriété Description
value Valeur de la propriété

Et l’arête contient les informations suivantes pour faciliter la navigation vers d’autres parties du graphe.

Propriété Description
id ID de l’arête. Doit être unique (en association avec la valeur de _partition, si applicable).
label Intitulé de l’arête. Cette propriété est facultative, elle est utilisée pour décrire le type de relation.
inV Cette propriété contient la liste des sommets d’une arête. Permet de stocker les informations de contiguïté avec l’arête pour une exécution rapide des traversées. Les sommets sont regroupés en fonction de leurs intitulés.
properties Sac de propriétés définies par l’utilisateur associé à l’arête.

Étapes de Gremlin

Nous allons maintenant examiner les étapes Gremlin prises en charge par Azure Cosmos DB. Pour des références complètes sur Gremlin, consultez Référence TinkerPop.

étape Description Documentation TinkerPop 3.2
addE Ajoute une arête reliant deux sommets étape addE
addV Ajoute un sommet au graphe étape addV
and Fait en sorte que toutes les traversées retournent une valeur étape and
as Un modulateur d’étape pour attribuer une variable à la sortie d’une étape étape as
by Un modulateur d’étape utilisé avec group et order étape by
coalesce Renvoie la première traversée qui renvoie un résultat étape coalesce
constant Renvoie une valeur constante. Utilisé avec coalesce étape constant
count Renvoie le nombre de traversées étape count
dedup Renvoie les valeurs en supprimant les doublons étape dedup
drop Supprime les valeurs (sommet/arête) étape drop
executionProfile Crée une description de toutes les opérations générées par l’étape Gremlin exécutée Étape executionProfile
fold Agit comme une barrière qui calcule l’agrégation des résultats étape fold
group Regroupe les valeurs basées sur les labels spécifiés étape group
has Permet de filtrer les propriétés, les sommets et les arêtes. Prend en charge hasLabel, hasId, hasNot, et les variantes has. étape has
inject Injecter des valeurs dans un flux de données étape inject
is Permet d’exécuter un filtre à l’aide d’une expression booléenne étape is
limit Permet de limiter le nombre d’éléments dans la traversée étape limit
local Local encapsule une section d’une traversée, similaire à une sous-requête étape local
not Permet de produire la négation d’un filtre étape not
optional Renvoie le résultat de la traversée spécifiée si elle produit un résultat, sinon renvoie l’élément appelant étape optional
or Garantit qu’au moins l’une des traversées renvoie une valeur étape or
order Renvoie les résultats dans l’ordre de tri spécifié étape order
path Renvoie le chemin d’accès complet de la traversée étape path
project Projette les propriétés sous forme de carte étape project
properties Renvoie les propriétés pour les labels spécifiés étape properties
range Filtre la plage de valeurs spécifiée étape range
repeat Répète l’étape le nombre de fois spécifié. Permet d’effectuer des boucles répétez l’étape
sample Permet d’échantillonner les résultats à partir de la traversée étape sample
select Permet de projeter les résultats à partir de la traversée étape select
store Pour les agrégations non bloquantes de la traversée étape store
TextP.startingWith(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété avec le début d'une chaîne donnée Prédicats TextP
TextP.endingWith(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété avec la fin d'une chaîne donnée Prédicats TextP
TextP.containing(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété avec le contenu d'une chaîne donnée Prédicats TextP
TextP.notStartingWith(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété qui ne commence pas par une chaîne donnée Prédicats TextP
TextP.notEndingWith(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété qui ne finit pas par une chaîne donnée Prédicats TextP
TextP.notContaining(string) Fonction de filtrage de chaîne. Cette fonction est utilisée comme prédicat de l'étape has() pour faire correspondre une propriété qui ne contient pas une chaîne donnée Prédicats TextP
tree Chemins d’agrégation à partir d’un sommet dans une arborescence étape tree
unfold Dérouler un itérateur comme une étape étape unfold
union Fusionner les résultats à partir de plusieurs traversées étape union
V Inclut les étapes nécessaires pour les traversées entre les sommets et les arêtes V, E, out, in, both, outE, inE, bothE, outV, inV, bothV et otherV pour étapes sommet
where Permet de filtrer les résultats à partir de la traversée. Prend en charge les opérateurs eq, neq, lt, lte, gt, gte et between étape where

Le moteur optimisé pour l’écriture fourni par Azure Cosmos DB prend en charge l’indexation automatique de toutes les propriétés au sein des sommets et des arêtes par défaut. Par conséquent, les requêtes avec des filtres, les requêtes de plage, le tri ou les agrégations sur toutes les propriétés sont traités à partir de l’index et exécutés efficacement. Pour plus d’informations sur la façon dont fonctionne l’indexation dans Azure Cosmos DB, consultez notre article sur l’indexation indépendante du schéma.

Différences de comportement

  • Le moteur de graphe Azure Cosmos DB fonctionne en largeur d’abord sur la traversée tandis que TinkerPop Gremlin fonctionne en profondeur d’abord. Ce comportement permet d’obtenir de meilleures performances dans un système horizontalement évolutif comme Azure Cosmos DB.

Fonctionnalités non prises en charge

  • Gremlin Bytecode est une spécification pour les traversées de graphe indépendante du langage de programmation. Le graph Azure Cosmos DB ne la prend pas encore en charge. Utilisez GremlinClient.SubmitAsync() et passez la traversée en tant que chaîne de texte.

  • La cardinalité des ensembles property(set, 'xyz', 1) n’est pas prise en charge. Utilisez property(list, 'xyz', 1) à la place. Pour plus d’informations, consultez Vertex properties with TinkerPop (Propriétés de vertex avec TinkerPop).

  • L’étape match() n’est actuellement pas disponible. Cette étape fournit des fonctions d’interrogation déclarative.

  • Les objets en tant que propriétés sur les sommets ou arêtes ne sont pas pris en charge. Les propriétés peuvent uniquement être des types primitifs ou des tableaux.

  • Le tri par propriétés de tableauorder().by(<array property>) n’est pas pris en charge. Seul est pris en charge le tri par types primitifs.

  • Les types JSON non primitifs ne sont pas pris en charge. Utilisez les types string, number ou true/false. Les valeurs null ne sont pas prises en charge.

  • Le sérialiseur GraphSONv3 n’est actuellement pas pris en charge. Utilisez les classes de sérialiseur, de lecteur et d’enregistreur GraphSONv2 dans la configuration de la connexion. Les résultats renvoyés par Azure Cosmos DB for Gremlin ne sont pas au format GraphSON.

  • Les fonctions et les expressions lambda ne sont pas prises en charge actuellement. Cela comprend les fonctions .map{<expression>}, .by{<expression>} et .filter{<expression>}. Pour plus d’informations et pour découvrir comment les réécrire à l’aide d’étapes Gremlin, consultez A Note on Lambdas (Remarque sur les lambdas).

  • Les transactions ne sont pas prises en charge en raison de la nature distribuée du système. Configurez un modèle d’accès concurrentiel optimiste approprié sur le compte Gremlin pour « lire vos propres écrits », et utilisez l’accès concurrentiel optimiste pour résoudre les conflits d’écritures.

Limitations connues

  • Utilisation de l’index pour les requêtes Gremlin avec des étapes .V() mi-parcours : Actuellement, seul le premier appel .V() d’une traversée utilisera l’index pour résoudre les filtres ou prédicats qui lui sont associés. Les appels suivants ne consultent pas l’index, ce qui peut augmenter la latence et le coût de la requête.

Dans l’hypothèse de l’indexation par défaut, une requête Gremlin de lecture classique commençant par l’étape .V() utiliserait des paramètres dans les étapes de filtrage associées, tels que .has() ou .where(), pour optimiser le coût et les performances de la requête. Par exemple :

g.V().has('category', 'A')

Toutefois, lorsque plusieurs étapes .V() sont incluses dans la requête Gremlin, la résolution des données pour la requête peut ne pas être optimale. Utilisez la requête suivante en guise d’exemple :

g.V().has('category', 'A').as('a').V().has('category', 'B').as('b').select('a', 'b')

Cette requête retourne deux groupes de sommets en fonction de leur propriété appelée category. Dans ce cas, seul le premier appel, g.V().has('category', 'A') utilise l’index pour résoudre les sommets en fonction des valeurs de leurs propriétés.

Une solution de contournement pour cette requête consiste à utiliser des étapes de sous-parcours, telles que .map() et union(). En voici quelques exemples :

// Query workaround using .map()
g.V().has('category', 'A').as('a').map(__.V().has('category', 'B')).as('b').select('a','b')

// Query workaround using .union()
g.V().has('category', 'A').fold().union(unfold(), __.V().has('category', 'B'))

Vous pouvez examiner les performances des requêtes à l’aide de l’étape Gremlin executionProfile().

Étapes suivantes