Présentation des requêtes graphiques

Ce document présente le langage de requête de graphe (GQL) et explique comment écrire des requêtes de graphe pour BigQuery Graph. Vous pouvez exécuter des requêtes de graphe pour trouver des modèles, parcourir des relations et obtenir des insights à partir du graphe de vos propriétés. Les exemples de ce document font référence à un graphique appelé FinGraph, qui montre les relations entre les personnes, les comptes qu'elles possèdent et les transferts entre les comptes. Pour en savoir plus sur la définition du graphique, consultez l'exemple FinGraph.

Structure d'une requête

Une requête de graphique se compose du nom du graphique, suivi d'une ou plusieurs instructions de requête linéaire. Chaque requête linéaire contient une ou plusieurs instructions, qui vous permettent de travailler avec des données graphiques pour trouver des correspondances de modèles, définir des variables, filtrer et transformer des données intermédiaires, et renvoyer des résultats. Vous exécutez une requête de graphique de la même manière que vous exécutez une requête SQL dans BigQuery.

Correspondance de modèles de graphiques

La correspondance de modèles de graphiques permet de trouver des modèles spécifiques dans votre graphique. Les modèles les plus élémentaires sont les modèles d'éléments, tels que les modèles de nœuds qui correspondent aux nœuds et les modèles d'arêtes qui correspondent aux arêtes.

Modèles de nœuds

Un modèle de nœud correspond aux nœuds de votre graphique. Ce modèle contient des parenthèses correspondantes, qui peuvent éventuellement inclure une variable de modèle de graphique, une expression de libellé et des filtres de propriété.

Rechercher tous les nœuds

La requête suivante renvoie tous les nœuds du graphique. La variable n, une variable de modèle de graphique, est associée aux nœuds correspondants. Dans ce cas, le modèle de nœud correspond à tous les nœuds du graphique.

GRAPH graph_db.FinGraph
MATCH (n)
RETURN LABELS(n) AS label, n.id;

Cette requête renvoie label et id :

Rechercher tous les nœuds portant un libellé spécifique

La requête suivante correspond à tous les nœuds du graphique qui comportent le libellé Person. La requête renvoie le libellé et certaines propriétés des nœuds correspondants.

GRAPH graph_db.FinGraph
MATCH (p:Person)
RETURN LABELS(p) AS label, p.id, p.name;

Cette requête renvoie les propriétés suivantes des nœuds correspondants :

Trouver tous les nœuds correspondant à une expression de libellé

Vous pouvez créer une expression de libellé avec un ou plusieurs opérateurs logiques. Par exemple, la requête suivante correspond à tous les nœuds du graphique qui comportent le libellé Person ou Account. La variable de modèle de graphique n expose toutes les propriétés des nœuds portant le libellé Person ou Account.

GRAPH graph_db.FinGraph
MATCH (n:Person|Account)
RETURN LABELS(n) AS label, n.id, n.birthday, n.create_time;

Notez les points suivants dans les résultats de cette requête :

• Tous les nœuds ont la propriété id.
• Les nœuds correspondant au libellé Account possèdent la propriété create_time, mais pas la propriété birthday. La propriété birthday est NULL pour ces nœuds.
• Les nœuds correspondant au libellé Person possèdent la propriété birthday, mais pas la propriété create_time. La propriété create_time est NULL pour ces nœuds.

Rechercher tous les nœuds correspondant à l'expression de libellé et au filtre de propriété

La requête suivante correspond à tous les nœuds du graphique qui ont le libellé Person et la propriété id égale à 1 :

GRAPH graph_db.FinGraph
MATCH (p:Person {id: 1})
RETURN LABELS(p) AS label, p.id, p.name, p.birthday;

Le résultat ressemble à ce qui suit :

Vous pouvez utiliser la clause WHERE pour créer des conditions de filtrage plus complexes sur les libellés et les propriétés.

La requête suivante utilise la clause WHERE pour filtrer les nœuds pour lesquels la propriété birthday est antérieure à 1990-01-10 :

GRAPH graph_db.FinGraph
MATCH (p:Person WHERE p.birthday < '1990-01-10')
RETURN LABELS(p) AS label, p.name, p.birthday;

Le résultat ressemble à ce qui suit :

Modèles Edge

Un motif d'arête correspond aux arêtes ou aux relations entre les nœuds. Les motifs de bordure sont placés entre crochets ([]) et incluent des symboles tels que -, -> ou <- pour indiquer les directions. Un motif d'arête peut éventuellement inclure une variable de motif de graphique à lier aux arêtes correspondantes.

Trouver tous les nœuds avec des libellés correspondants

Cette requête renvoie tous les nœuds du graphique portant le libellé Transfers. La requête lie la variable de modèle de graphique e aux arêtes correspondantes.

GRAPH graph_db.FinGraph
MATCH -[e:Transfers]->
RETURN e.Id as src_account, e.order_number;

Le résultat ressemble à ce qui suit :

Rechercher tous les nœuds correspondant à l'expression de libellé et au filtre de propriété

Le modèle d'arête de la requête suivante utilise une expression de libellé et un filtre de propriété pour trouver toutes les arêtes libellées Transfers qui correspondent à un numéro de commande spécifié :

GRAPH graph_db.FinGraph
MATCH -[e:Transfers {order_number: "304120005529714"}]->
RETURN e.Id AS src_account, e.order_number;

Le résultat ressemble à ce qui suit :

Trouver tous les bords à l'aide d'un motif de bord de direction

Vous pouvez utiliser le modèle d'arête any direction (-[]-) dans une requête pour faire correspondre les arêtes dans les deux sens. La requête suivante recherche tous les transferts avec un compte bloqué :

GRAPH graph_db.FinGraph
MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked:true})
RETURN transfer.order_number, transfer.amount;

Le résultat ressemble à ce qui suit :

Formats de chemin

Un modèle de chemin est créé à partir de modèles de nœuds et d'arêtes alternés.

Trouver tous les chemins à partir d'un nœud spécifique à l'aide d'un modèle de chemin

La requête suivante recherche tous les transferts vers un compte initiés à partir d'un compte appartenant à Person avec id égal à 2.

Chaque résultat correspondant représente un chemin d'accès à partir d'un nœud Person lorsque id est égal à 2 via un nœud Account connecté à l'aide d'un bord Owns, dans un autre nœud Account à l'aide d'un bord Transfers.

GRAPH graph_db.FinGraph
MATCH
  (p:Person {id: 2})-[:Owns]->(account:Account)-[t:Transfers]->
  (to_account:Account)
RETURN
  p.id AS sender_id, account.id AS from_id, to_account.id AS to_id;

Le résultat ressemble à ce qui suit :

Formats de chemin quantifiés

Un motif quantifié répète un motif dans une plage spécifiée.

Faire correspondre un modèle d'arête quantifié

Pour trouver des chemins de longueur variable, vous pouvez appliquer un quantificateur à un modèle d'arête. La requête suivante illustre ce point en recherchant les comptes de destination qui se trouvent à un à trois transferts d'une source Account avec une valeur id de 7.

La requête applique le quantificateur {1, 3} au modèle d'arête -[e:Transfers]->. Cela indique à la requête de faire correspondre les chemins qui répètent le modèle d'arête Transfers une, deux ou trois fois. La clause WHERE permet d'exclure le compte source des résultats. La fonction ARRAY_LENGTH est utilisée pour accéder à e group variable.

GRAPH graph_db.FinGraph
MATCH (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account)
WHERE src != dst
RETURN src.id AS src_account_id, ARRAY_LENGTH(e) AS path_length, dst.id AS dst_account_id;

Le résultat ressemble à ce qui suit :

Certaines lignes des résultats sont répétées. En effet, plusieurs chemins d'accès correspondant au modèle peuvent exister entre les mêmes nœuds source et de destination, et la requête les renvoie tous.

Faire correspondre un format de chemin quantifié

La requête suivante recherche les chemins entre les nœuds Account avec un ou deux bords Transfers via des comptes intermédiaires bloqués.

Le format de chemin d'accès entre parenthèses est quantifié, et sa clause WHERE spécifie les conditions du format répété.

GRAPH graph_db.FinGraph
MATCH
  (src:Account)
  ((a:Account)-[:Transfers]->(b:Account {is_blocked:true}) WHERE a != b){1,2}
    -[:Transfers]->(dst:Account)
RETURN src.id AS src_account_id, dst.id AS dst_account_id;

Le résultat ressemble à ce qui suit :

Variables de groupe

Une variable de modèle de graphique déclarée dans un modèle quantifié devient une variable de groupe lorsqu'elle est consultée en dehors de ce modèle. Il se lie ensuite à un tableau d'éléments de graphique correspondants.

Vous pouvez accéder à une variable de groupe en tant que tableau. Ses éléments de graphique sont conservés dans l'ordre de leur apparition le long des chemins correspondants. Vous pouvez agréger une variable de groupe à l'aide de l'agrégation horizontale.

Variable de groupe d'accès

Dans l'exemple suivant, la variable e est accessible comme suit :

• En tant que variable de modèle de graphique liée à un seul bord dans la clause WHERE e.amount > 100 lorsqu'elle se trouve dans le modèle quantifié.
• En tant que variable de groupe liée à un tableau d'éléments d'arête dans ARRAY_LENGTH(e) dans l'instruction RETURN lorsqu'elle se trouve en dehors du modèle quantifié.
• En tant que variable de groupe liée à un tableau d'éléments de bord, qui est agrégée par SUM(e.amount) en dehors du modèle quantifié. Il s'agit d'un exemple d'agrégation horizontale.

GRAPH graph_db.FinGraph
MATCH
  (src:Account {id: 7})-[e:Transfers WHERE e.amount > 100]->{0,2}
  (dst:Account)
WHERE src.id != dst.id
LET total_amount = SUM(e.amount)
RETURN
  src.id AS src_account_id, ARRAY_LENGTH(e) AS path_length,
  total_amount, dst.id AS dst_account_id;

Le résultat ressemble à ce qui suit :

Préfixes de recherche de chemin

Pour limiter les chemins correspondants dans les groupes qui partagent des nœuds source et de destination, vous pouvez utiliser le préfixe de recherche de chemin ANY, ANY SHORTEST ou ANY CHEAPEST. Vous ne pouvez appliquer ces préfixes qu'avant un modèle de chemin d'accès entier, et non à l'intérieur de parenthèses.

Correspondance avec ANY

La requête suivante recherche tous les comptes uniques accessibles qui se trouvent à une ou deux Transfers d'un nœud Account donné.

Le préfixe de recherche de chemin ANY garantit que la requête ne renvoie qu'un seul chemin entre une paire unique de nœuds src et dst Account. Dans l'exemple suivant, bien que vous puissiez atteindre le nœud Account avec {id: 16} de deux manières différentes à partir du nœud source Account, la requête ne renvoie qu'un seul chemin d'accès.

GRAPH graph_db.FinGraph
MATCH ANY (src:Account {id: 7})-[e:Transfers]->{1,2}(dst:Account)
LET ids_in_path = ARRAY_CONCAT(ARRAY_AGG(e.Id), [dst.Id])
RETURN src.id AS src_account_id, dst.id AS dst_account_id, ids_in_path;

Le résultat ressemble à ce qui suit :

Correspondance avec ANY SHORTEST

Le préfixe de recherche de chemin ANY SHORTEST renvoie un seul chemin pour chaque paire de nœuds source et de destination, sélectionnés parmi ceux qui comportent le nombre minimal d'arêtes.

Par exemple, la requête suivante recherche l'un des chemins les plus courts entre un nœud Account avec une valeur id de 7 et un nœud Account avec une valeur id de 20. La requête prend en compte les chemins comportant une à trois arêtes Transfers.

GRAPH graph_db.FinGraph
MATCH ANY SHORTEST (src:Account {id: 7})-[e:Transfers]->{1, 3}(dst:Account {id: 20})
RETURN src.id AS src_account_id, dst.id AS dst_account_id, ARRAY_LENGTH(e) AS path_length;

Le résultat ressemble à ce qui suit :

Correspondance avec ANY CHEAPEST

Le préfixe de recherche de chemin ANY CHEAPEST garantit que, pour chaque paire de comptes source et de destination, la requête ne renvoie qu'un seul chemin avec le coût de calcul total minimal.

La requête suivante recherche un chemin d'accès avec le coût de calcul total minimal entre les nœuds Account. Ce coût est basé sur la somme de la propriété amount des arêtes Transfers. La recherche prend en compte les chemins comportant entre un et trois bords Transfers.

GRAPH graph_db.FinGraph
MATCH ANY CHEAPEST (src:Account)-[e:Transfers COST e.amount]->{1,3}(dst:Account)
LET total_cost = sum(e.amount)
RETURN src.id AS src_account_id, dst.id AS dst_account_id, total_cost;

Le résultat ressemble à ce qui suit :

Modèles de graphiques

Un modèle de graphique se compose d'un ou de plusieurs modèles de chemin d'accès, séparés par une virgule (,). Les modèles de graphique peuvent contenir une clause WHERE, qui vous permet d'accéder à toutes les variables de modèle de graphique dans les modèles de chemin d'accès pour former des conditions de filtrage. Chaque modèle de chemin d'accès génère une collection de chemins d'accès.

Faire correspondre à l'aide d'un modèle de graphique

La requête suivante identifie les comptes intermédiaires et leurs propriétaires impliqués dans des transactions dont le montant dépasse 200 €, par le biais desquels des fonds sont transférés d'un compte source vers un compte bloqué.

Les formats de chemin suivants forment le format de graphique :

• Le premier modèle trouve les chemins où le transfert a lieu d'un compte vers un compte bloqué à l'aide d'un compte intermédiaire.
• Le deuxième modèle trouve les chemins d'un compte à son propriétaire.

La variable interm sert de lien commun entre les deux modèles de chemin d'accès, ce qui nécessite que interm fasse référence au même nœud d'élément dans les deux modèles de chemin d'accès. Cela crée une opération d'équi-jointure basée sur la variable interm.

GRAPH graph_db.FinGraph
MATCH
  (src:Account)-[t1:Transfers]->(interm:Account)-[t2:Transfers]->(dst:Account),
  (interm)<-[:Owns]-(p:Person)
WHERE dst.is_blocked = TRUE AND t1.amount > 200 AND t2.amount > 200
RETURN
  src.id AS src_account_id, dst.id AS dst_account_id,
  interm.id AS interm_account_id, p.id AS owner_id;

Le résultat ressemble à ce qui suit :

Instructions de requête linéaires

Vous pouvez enchaîner plusieurs instructions de graphique pour former une instruction de requête linéaire. Les instructions sont exécutées dans l'ordre dans lequel elles apparaissent dans la requête.

• Chaque instruction prend en entrée la sortie de l'instruction précédente. L'entrée est vide pour la première instruction.

• Le résultat de la dernière instruction est le résultat final.

Par exemple, vous pouvez utiliser des instructions de requête linéaire pour trouver le transfert maximal vers un compte bloqué. La requête suivante permet de trouver le compte et son propriétaire ayant effectué le plus grand transfert sortant vers un compte bloqué.

GRAPH graph_db.FinGraph
MATCH (src_account:Account)-[transfer:Transfers]->(dst_account:Account {is_blocked:true})
ORDER BY transfer.amount DESC
LIMIT 1
MATCH (src_account:Account)<-[owns:Owns]-(owner:Person)
RETURN src_account.id AS account_id, owner.name AS owner_name;

Le tableau suivant illustre ce processus en montrant les résultats intermédiaires transmis entre chaque instruction. Par souci de concision, seules certaines propriétés sont affichées.

MATCH
  (src_account:Account)
    -[transfer:Transfers]->
  (dst_account:Account {is_blocked:true})

ORDER BY transfer.amount DESC

LIMIT 1

MATCH
  (src_account:Account)
    <-[owns:Owns]-
  (owner:Person)

RETURN
  src_account.id AS account_id,
  owner.name AS owner_name
        

Le résultat ressemble à ce qui suit :

Instruction return

L'instruction RETURN spécifie ce qui doit être renvoyé à partir des modèles correspondants. Elle peut accéder aux variables de modèle de graphique et inclure des expressions et d'autres clauses, telles que ORDER BY et GROUP BY.

BigQuery Graph n'est pas compatible avec le renvoi d'éléments de graphique en tant que résultats de requête. Pour renvoyer l'intégralité de l'élément de graphique, utilisez la fonction TO_JSON.

Renvoyer des éléments de graphique au format JSON

GRAPH graph_db.FinGraph
MATCH (n:Account {id: 7})
-- Returning a graph element in the final results is NOT allowed. Instead, use
-- the TO_JSON function or explicitly return the graph element's properties.
RETURN TO_JSON(n) AS n;

Le résultat ressemble à ce qui suit :

Composer des requêtes plus longues avec le mot clé NEXT

Vous pouvez enchaîner plusieurs instructions de requête linéaire de graphique à l'aide du mot clé NEXT. La première instruction reçoit une entrée vide, et la sortie de chaque instruction suivante devient l'entrée de la suivante.

L'exemple suivant permet de trouver le propriétaire du compte ayant reçu le plus de transferts entrants en enchaînant plusieurs instructions linéaires de graphique. Vous pouvez utiliser la même variable, par exemple account, pour faire référence au même élément de graphique dans plusieurs instructions linéaires.

GRAPH graph_db.FinGraph
MATCH (:Account)-[:Transfers]->(account:Account)
RETURN account, COUNT(*) AS num_incoming_transfers
GROUP BY account
ORDER BY num_incoming_transfers DESC
LIMIT 1

NEXT

MATCH (account:Account)<-[:Owns]-(owner:Person)
RETURN account.id AS account_id, owner.name AS owner_name, num_incoming_transfers;

Le résultat ressemble à ce qui suit :

Vous pouvez également combiner des instructions de requête linéaire avec des opérateurs d'ensemble.

Fonctions et expressions

Vous pouvez utiliser toutes les fonctions GoogleSQL (fonctions d'agrégation et scalaires), les opérateurs et les expressions conditionnelles dans les requêtes graphiques. BigQuery Graph est également compatible avec les fonctions GQL et les opérateurs GQL qui ne peuvent être utilisés que dans les requêtes graphiques.

La requête suivante inclut un mélange de fonctions et d'opérateurs GQL et SQL dans une requête de graphique :

GRAPH graph_db.FinGraph
MATCH (person:Person)-[o:Owns]->(account:Account)
WHERE person IS SOURCE OF o
RETURN person, ARRAY_AGG(account.nick_name) AS accounts
GROUP BY person

NEXT

RETURN
  LABELS(person) AS labels,
  accounts,
  CONCAT(person.city, ", ", person.country) AS location,
  TO_JSON(person) AS person
LIMIT 1;

Le résultat ressemble à ce qui suit :

Sous-requêtes

Une sous-requête est une requête imbriquée dans une autre requête. Les règles suivantes s'appliquent aux sous-requêtes dans les requêtes graphiques :

• Une sous-requête est placée entre accolades {}.
• Une sous-requête commence par une clause GRAPH pour spécifier le graphique dans le champ d'application. Le graphique spécifié ne doit pas nécessairement être identique à celui utilisé dans la requête externe.
• Une variable de modèle de graphique déclarée en dehors du champ d'application de la sous-requête ne peut pas être déclarée à nouveau à l'intérieur de la sous-requête, mais elle peut être référencée dans des expressions ou des fonctions à l'intérieur de la sous-requête.

Utiliser une sous-requête pour trouver le nombre total de transferts de chaque compte

La requête suivante illustre l'utilisation de la sous-requête VALUE. La sous-requête est placée entre accolades {} et précédée du mot clé VALUE. La requête renvoie le nombre total de transferts initiés à partir d'un compte.

GRAPH graph_db.FinGraph
MATCH (p:Person)-[:Owns]->(account:Account)
RETURN p.name, account.id AS account_id, VALUE {
  GRAPH graph_db.FinGraph
  MATCH (a:Account)-[transfer:Transfers]->(:Account)
  WHERE a = account
  RETURN COUNT(transfer) AS num_transfers
} AS num_transfers;

Le résultat ressemble à ce qui suit :

Pour obtenir la liste des expressions de sous-requête compatibles, consultez Sous-requêtes BigQuery Graph.

Paramètres de requête

Vous pouvez interroger BigQuery Graph avec des paramètres. Pour en savoir plus, consultez la syntaxe et découvrez comment exécuter des requêtes paramétrées.

La requête suivante correspond aux nœuds Person dont la valeur id correspond à un paramètre de requête :

GRAPH graph_db.FinGraph
MATCH (person:Person {id: @id})
RETURN person.name;

Interroger des graphiques et des tableaux ensemble

Vous pouvez combiner des requêtes de graphe et des requêtes SQL à l'aide de l'opérateur GRAPH_TABLE.

L'opérateur GRAPH_TABLE prend une requête de graphique linéaire et renvoie son résultat sous forme de tableau pouvant être intégré à une requête SQL. Cette interopérabilité vous permet d'enrichir les résultats des requêtes de graphiques avec du contenu non graphique et inversement.

Par exemple, vous pouvez créer une table CreditReports et insérer quelques rapports de crédit, comme illustré dans l'exemple suivant :

CREATE TABLE graph_db.CreditReports (
  person_id     INT64 NOT NULL,
  create_time   TIMESTAMP NOT NULL,
  score         INT64 NOT NULL,
  PRIMARY KEY (person_id, create_time) NOT ENFORCED
);

INSERT INTO graph_db.CreditReports (person_id, create_time, score)
VALUES
  (1,"2020-01-10 06:22:20.222", 700),
  (2,"2020-02-10 06:22:20.222", 800),
  (3,"2020-03-10 06:22:20.222", 750);

Vous pouvez ensuite identifier des personnes spécifiques grâce à la mise en correspondance des modèles de graphiques dans GRAPH_TABLE et joindre les résultats de la requête de graphique à la table CreditReports pour récupérer les scores de crédit.

SELECT
  gt.person.id,
  credit.score AS latest_credit_score
FROM GRAPH_TABLE(
  graph_db.FinGraph
  MATCH (person:Person)-[:Owns]->(:Account)-[:Transfers]->(account:Account {is_blocked:true})
  RETURN DISTINCT person
) AS gt
JOIN graph_db.CreditReports AS credit
  ON gt.person.id = credit.person_id
ORDER BY credit.create_time;

Le résultat ressemble à ce qui suit :

Étapes suivantes

• Découvrez comment créer et interroger un graphique.
• Découvrez comment concevoir un schéma de graphique.
• Découvrez comment visualiser les résultats de requête.