Exécuter des algorithmes Spanner Graph

Aperçu — Algorithmes Spanner Graph

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Cette fonctionnalité est disponible dans les éditions Spanner Enterprise et Enterprise Plus. Pour en savoir plus, consultez la présentation des éditions Spanner.

Ce document explique comment exécuter des algorithmes sur Spanner Graph.

Structure des requêtes d'algorithme Spanner Graph

Une requête d'algorithme Spanner Graph présente la structure suivante :

EXPORT DATA OPTIONS (export_option_list) AS
GRAPH graph_name
match_clause
call_statement algorithm_name(common_input, algorithm_specific_input)
  YIELD algorithm_specific_output
RETURN results

• export_option_list : options qui définissent la manière de conserver les résultats des requêtes d'algorithme. Consultez les options Cloud Storage et les options Spanner.

• graph_name : nom du graphique.

• match_clause : instructions MATCH facultatives pour définir les éléments d'entrée de l'algorithme.

• call_statement : utilisez l'instruction CALL lorsque vous omettez la variable match_clause et que vous souhaitez opérer sur l'ensemble du graphique. Utilisez l'instruction CALL PER() lorsque la variable match_clause est présente et que vous souhaitez effectuer une opération sur la table de travail. Pour en savoir plus, consultez GQL CALL.

• algorithm_name : nom de l'algorithme à exécuter. Pour connaître les algorithmes disponibles, consultez Algorithmes Spanner Graph.

• common_input : paramètres d'entrée nommés communs à toutes les requêtes d'algorithme. Pour en savoir plus, consultez Paramètres d'entrée courants des algorithmes.

• algorithm_specific_input : paramètres d'entrée nommés pour l'algorithme. Pour en savoir plus, consultez les paramètres d'entrée définis dans Algorithmes Spanner Graph.

• algorithm_specific_output : résultat de l'appel de l'algorithme. Pour en savoir plus, consultez les sorties définies dans Algorithmes Spanner Graph et la clause YIELD dans l'instruction CALL.

• results : définit ce qui doit être renvoyé dans les résultats de la requête.

La requête est composée d'une instruction EXPORT DATA, qui définit comment conserver les résultats, et d'une CLAUSE GRAPH qui produit le résultat de la requête de l'algorithme.

Dans sa forme la plus simple, la clause graph identifie le graphe, utilise une instruction CALL pour appeler un algorithme qui génère une sortie prédéfinie, puis utilise une instruction RETURN pour spécifier ce qu'il faut renvoyer à partir de la sortie de l'algorithme.

La clause de graphique peut éventuellement utiliser des instructions MATCH compatibles pour sélectionner les éléments qui vous intéressent. Dans ce cas, utilisez une clause PER () pour regrouper toutes les lignes renvoyées par l'instruction MATCH en tant qu'entrée de l'algorithme. L'algorithme fonctionne sur un sous-graphe logique composé de l'ensemble unique de nœuds et d'arêtes sélectionnés.

La requête ne renvoie aucune donnée. La variable export_option_list détermine la manière dont les résultats sont conservés.

Pour en savoir plus sur les requêtes d'algorithme Spanner Graph, consultez les sections suivantes de ce document :

• Paramètres d'entrée d'algorithme courants
• Gérer la sortie de l'algorithme
• Exécuter des exemples de requêtes d'algorithme

Paramètres d'entrée d'algorithme courants

Spécifiez ces paramètres d'entrée nommés au format suivant : NAME => VALUE, ....

Nom	Type de valeur	Obligatoire	Valeur par défaut	Description
node_labels	ARRAY	Non	(aucun)	Uniquement compatible lorsque CALL est utilisé. Liste des libellés de nœuds à inclure dans l'entrée de l'algorithme. Si cette option est spécifiée, seuls les nœuds comportant au moins un libellé correspondant sont inclus.
edge_labels	ARRAY	Non	(aucun)	N'est compatible qu'avec CALL. Liste des libellés d'arêtes à inclure dans l'entrée de l'algorithme. Si ce paramètre est spécifié, seules les arêtes comportant au moins une étiquette correspondante sont incluses.
edge_weight_property	STRING	Non	(aucun)	Nom de la propriété d'arête contenant les pondérations. Si elle n'est pas définie, le système attribue une pondération par défaut de 1 à toutes les arêtes. La valeur de la propriété doit être de type numérique.
machine_category	STRING	Non	par défaut	Catégorie de machine à utiliser pour l'exécution de l'algorithme. Valeurs acceptées : default, large
fallback_compute_region	STRING	Non	(aucun)	Région de secours dans laquelle l'exécution de l'algorithme a lieu si la région d'origine est confrontée à des contraintes de capacité. Doit se trouver dans la même juridiction que la région d'origine de l'instance Spanner (par exemple, us-central1 si la région d'origine est us-east1).
max_idle_time	STRING	Non	30 min	Spécifie la durée pendant laquelle l'instance de calcul doit rester active pour être réutilisée une fois l'algorithme terminé. Le format est une séquence de nombres décimaux, chacun avec un suffixe d'unité, tel que 4m, 1.5h ou 1h45m. Les unités de temps valides sont ns, us (ou µs), ms, s, m et h.

Gérer le résultat de l'algorithme

Vous devez conserver les résultats de la requête d'algorithme avant de pouvoir les inspecter. Utilisez export_data_option pour décrire comment conserver les résultats. Vous pouvez conserver les résultats dans Cloud Storage ou les renvoyer vers la même instance Spanner d'où provient la requête.

Conserver les résultats dans Cloud Storage

Pour utiliser cette option, assurez-vous que le rôle Administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) est attribué au compte de service Spanner géré par Google [e-mail].

Les options EXPORT DATA suivantes sont compatibles lorsque vous conservez les résultats dans Cloud Storage. Spécifiez les options au format suivant : NAME=VALUE, ....

Nom	Type de valeur	Obligatoire	Description
uri	STRING	Oui	URI de destination pour l'exportation, au format gs://bucket/path/file. Si vous exportez une grande quantité de données, utilisez un caractère générique dans uri pour exporter les données dans plusieurs fichiers. Par exemple, gs://bucket/path/file_*.csv.
format	STRING	Oui	Format des données exportées. Valeurs acceptées : CSV, PARQUET, AVRO.
header	BOOL	Non	Si la valeur est true, le système imprime les en-têtes de colonne pour la première ligne de chaque fichier de données. La valeur par défaut est false. S'applique uniquement au format CSV.
overwrite	BOOL	Non	Si true, le système écrase tous les fichiers existants portant le même URI. Sinon, si des fichiers portant le même URI existent, l'instruction renvoie une erreur. La valeur par défaut est false.
field_delimiter	STRING	Non	Délimiteur qui sépare les champs. Par défaut : , (virgule). Ne s'applique qu'au format CSV.
compression	STRING	Non	Spécifie le format de compression. Si vous ne spécifiez pas de format de compression, les fichiers ne sont pas compressés. Pour CSV, la valeur acceptée est GZIP. Pour PARQUET, les valeurs acceptées sont : SNAPPY, GZIP, ZSTD. Pour AVRO, les valeurs acceptées sont DEFLATE et SNAPPY.

Les noms de colonnes de la clause RETURN définissent les noms de colonnes dans les fichiers de sortie Cloud Storage.

Exporter des données dans un ou plusieurs fichiers

Les requêtes Spanner Graph n'acceptent qu'un seul opérateur générique (*) dans uri. Le caractère générique peut apparaître dans le composant du nom de fichier, mais pas dans le nom du bucket, le nom du dossier ni l'extension de fichier. L'opérateur générique permet d'indiquer à Spanner Graph qu'il doit créer plusieurs fichiers segmentés en fonction du modèle que vous fournissez si l'ensemble de résultats est volumineux. Le système remplace l'opérateur générique par un numéro (en commençant à zéro) et il est complété à gauche de façon à obtenir 12 chiffres. Par exemple, un URI gs://my-bucket/file-*.csv crée des fichiers tels que gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv et d'autres fichiers similaires.

Si vous utilisez un uri sans caractère générique, le résultat est un seul fichier, tel que gs://my-bucket/file.csv.

Types de données

Lorsque vous exportez des données, les types de données graphiques Spanner sont convertis comme suit, selon le format :

CSV

Tous les types de données sont convertis en leur représentation sous forme de chaîne :

• Les valeurs BOOL sont converties en true ou false.
• Valeurs BYTES encodées en base64.
• Les valeurs TIMESTAMP sont au format YYYY-MM-DD HH:MM:SS.ffffff UTC.
• Les valeurs NULL s'affichent sous forme de chaînes vides.

Vous ne pouvez pas exporter des données imbriquées et répétées au format CSV.

Avro

Type de données Spanner	Type de données Avro
BOOL	BOOLEAN
INT64	LONG
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	BYTES avec le type logique DECIMAL(38,9)
STRING	STRING
BYTES	BYTES
TIMESTAMP	LONG (microsecondes depuis l'epoch)
NULL	null

Parquet

Type de données Spanner	Type de données Parquet
BOOL	BOOLEAN
INT64	INT64
FLOAT	FLOAT
DOUBLE	DOUBLE
NUMERIC	DECIMAL(38,9)
STRING	STRING
BYTES	BYTE_ARRAY
TIMESTAMP	TIMESTAMP_MICROS
NULL	null

Conserver les résultats dans Spanner

Les options EXPORT DATA suivantes sont compatibles lorsque vous conservez les résultats dans votre instance Spanner source. Spécifiez les options au format suivant : NAME=VALUE, ....

Nom	Type de valeur	Obligatoire	Description
format	STRING	Oui	Format des données exportées. doit être CLOUD_SPANNER
table	STRING	Oui	Nom de la table Spanner de destination dans laquelle écrire les résultats. Il peut s'agir de n'importe quelle table de l'instance Spanner.
write_mode	STRING	Oui	Mode d'écriture à utiliser. Les valeurs acceptées sont les suivantes : update_ignore_all : met à jour les lignes existantes dans la table de destination. upsert_ignore_all : insère de nouvelles lignes ou met à jour les lignes existantes dans la table de destination. Dans les deux modes, Spanner ignore tout enregistrement qui entraînerait une violation de contrainte (par exemple, des clés manquantes lors d'une mise à jour, une violation d'index unique ou une violation de contrainte de clé étrangère). Toutefois, l'écriture échoue pour les erreurs de non-respect des contraintes (par exemple, incompatibilité de type de colonne, valeurs manquantes pour les colonnes NOT NULL).

Conditions requises

Lorsque vous conservez les résultats de l'algorithme dans Spanner, votre requête d'algorithme doit répondre aux exigences suivantes :

• La table de destination doit exister.
• RETURN Si nécessaire, utilisez des alias pour faire correspondre les noms des colonnes de la table de destination. Exemple : RETURN node.id AS person_id.
• Inclure toutes les colonnes de clé primaire : la clause RETURN doit inclure toutes les colonnes de clé primaire de la table de destination.

Sémantique d'écriture

La persistance des résultats dans Spanner est une opération non transactionnelle. Il fournit une atomicité au niveau des lignes. Cela signifie que le système écrit toutes les colonnes de la même ligne ou n'en écrit aucune. Il suit la sémantique de type "au moins une fois". Cela signifie qu'une ligne peut être écrite plusieurs fois. La lecture de la table de destination pendant l'exécution peut donner des résultats incomplets.

Si l'exécution globale échoue, le système n'annule pas les modifications qui ont déjà été validées. Le processus d'écriture échoue lors de la première erreur non réessayable. En cas d'échec d'écriture, le ERROR_MESSAGE dans GRAPH_OPERATION_EXECUTION_STATUS indique la clé primaire de la ligne qui a échoué, ainsi que la raison spécifique de l'échec.

Le système réécrit les résultats de l'algorithme dans Spanner Graph en utilisant la priorité MEDIUM.

Exécuter des exemples de requêtes d'algorithme

Cette section présente des exemples de requêtes d'algorithme Spanner Graph que vous pouvez exécuter sur une instance de test. Pour obtenir la liste complète des algorithmes compatibles avec Spanner Graph, consultez Algorithmes Spanner Graph.

Avant de commencer

Pour exécuter les exemples de requêtes d'algorithme Spanner Graph, vous devez d'abord effectuer les opérations suivantes :

1. Suivez Configurer et interroger Spanner Graph pour créer un graphique Spanner.
2. Assurez-vous de disposer des autorisations requises.
3. Facultatif : Augmentez le schéma Spanner Graph si vous conservez la sortie dans Spanner.

Ajoutez une colonne nommée page_rank à la table Account. Spanner écrit les résultats de l'algorithme dans cette nouvelle colonne. Ensuite, actualisez la définition du graphique pour pouvoir accéder à page_rank en tant que propriété de nœud.

-- Add `page_rank` as a column. Data type of this column matches the data type defined in `PageRank` output signature.
ALTER TABLE Account ADD COLUMN page_rank FLOAT64;

-- Rerun the graph definition DDL to pickup `page_rank` as a new property.
CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (`Account`, `Person`)
  EDGE TABLES (
    `PersonOwnAccount`
      SOURCE KEY (id) REFERENCES `Person` (id)
      DESTINATION KEY (account_id) REFERENCES `Account` (id)
      LABEL `Owns`,
    `AccountTransferAccount`
      SOURCE KEY (id) REFERENCES `Account` (id)
      DESTINATION KEY (to_id) REFERENCES `Account` (id)
      LABEL `Transfers`
  );

Exécuter un algorithme sur un graphique complet avec un filtre de libellé et conserver les résultats dans Cloud Storage

Cet exemple exécute l'instruction PageRank pour classer les comptes en fonction des transferts auxquels ils participent. Les résultats de la requête sont conservés dans un bucket Cloud Storage au format CSV sous le nom my-bucket-name/my-output.csv.

EXPORT DATA OPTIONS (
  uri = "gs://my-bucket-name/my-output.csv",
  format = "csv"
) AS
GRAPH FinGraph
CALL PageRank(node_labels => ['Account'], edge_labels => ['Transfers']) YIELD node, score
RETURN node.id, score AS page_rank

Dans Cloud Storage, un fichier CSV avec deux colonnes (id et page_rank) doit s'afficher une fois la requête exécutée.

Exécuter l'algorithme sur le sous-graphe défini par MATCH et conserver les résultats dans le graphique

Cet exemple utilise le modèle MATCH pour faire correspondre de manière dynamique un sous-graphe logique contenant tous les nœuds Account et uniquement les arêtes Transfer dont le montant est inférieur à 500. Ce sous-graphe logique est l'entrée de l'algorithme PageRank. Spanner conserve les résultats de l'algorithme dans la table Account.

EXPORT DATA OPTIONS (
  format = "CLOUD_SPANNER",
  table = "Account",
  write_mode = 'update_ignore_all'
) AS
GRAPH FinGraph
MATCH (n:Account)
RETURN n
FULL UNION ALL
MATCH -[e:Transfers WHERE e.amount < 500]->
RETURN e
NEXT
CALL PER () PageRank() YIELD node, score
RETURN node.id, score AS page_rank

Une fois la requête exécutée, exécutez la requête suivante :

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

Un résultat semblable aux lignes suivantes doit s'afficher :

id	page_rank
20	0,49
16	0,46
7	0,05

Vérifier l'état d'exécution de l'algorithme

Lorsqu'une requête d'algorithme de graphe aboutit, elle ne renvoie aucune ligne et l'état Success. Selon la taille du graphique d'entrée et les configurations spécifiques de l'algorithme, l'exécution de l'algorithme peut prendre un certain temps. Vous pouvez vérifier la progression et l'état d'exécution d'une requête d'algorithme de graphique dans le tableau SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS. Les informations de ce tableau sont conservées pendant 30 jours.

GRAPH_OPERATION_EXECUTION_STATUS schéma

Nom de la colonne	Type	Description
QUERY_ID	STRING	ID de la requête d'algorithme de graphe.
QUERY_TEXT	STRING	Texte de l'instruction de requête.
START_TIMESTAMP	TIMESTAMP	Heure à laquelle l'exécution de la requête a commencé.
LAST_UPDATE_TIMESTAMP	TIMESTAMP	Heure de la dernière mise à jour de l'état.
PROGRESS	FLOAT64	Pourcentage de progression estimé. La valeur est comprise entre 0 et 1, où 0 signifie "démarré" et 1 signifie "terminé".
STATUS	STRING	État actuel de l'exécution. Les valeurs possibles incluent PENDING, IN_PROGRESS, OK ou un code d'état d'erreur tel que CANCELLED, DEADLINE_EXCEEDED, INVALID_ARGUMENT, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, UNAVAILABLE ou UNKNOWN.
ERROR_MESSAGE	STRING	Message d'erreur si l'exécution de la requête a échoué.

L'exemple de requête suivant liste les requêtes de graphe qui n'ont pas encore abouti :

SELECT
  query_id,
  query_text,
  start_timestamp,
  last_update_timestamp,
  progress,
  status,
  error_message
FROM
  SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS
WHERE
  status != "OK"
ORDER BY
  start_timestamp DESC;

Annuler l'exécution de l'algorithme

Pour annuler une requête d'algorithme de graphe en cours, recherchez l'query_id dans la table SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS, puis appelez cancel_query pour cet query_id.

Étapes suivantes

• Catalogue des algorithmes Spanner Graph
• Exigences de schéma et compatibilité des fonctionnalités de l'algorithme Spanner Graph.

• Bonnes pratiques concernant les algorithmes Spanner Graph