Exécuter des algorithmes Spanner Graph

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 comment 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 CALL lorsque vous omettez <match_clause> et que vous souhaitez opérer sur l'ensemble du graphique. Utilisez CALL PER() lorsque <match_clause> est présent et que vous souhaitez effectuer des opérations 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 de l'algorithme.

  • <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 de graphiques Spanner.

  • <algorithm_specific_output> : résultat de l'appel d'algorithme. Pour en savoir plus, consultez les sorties définies dans Algorithmes Spanner Graph et 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 la manière de conserver les résultats, et d'une CLAUSE GRAPH qui produit le résultat de la requête d'algorithme.

Dans sa forme la plus simple, la clause graph identifie le graphique, CALL est un algorithme qui génère une sortie prédéfinie, puis spécifie ce qu'il faut RETURN à partir de la sortie de l'algorithme.

La clause graph 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 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. Les résultats sont conservés en fonction de export_option_list.

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

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) Disponible uniquement 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) Disponible uniquement lorsque CALL est utilisé. Liste des libellés d'arêtes à inclure dans l'entrée de l'algorithme. Si cette option est spécifiée, seules les arêtes comportant au moins un libellé correspondant 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. Le type de valeur de la propriété doit être numérique.
machine_category STRING Non par défaut Catégorie de machine à utiliser pour l'exécution de l'algorithme. Les valeurs acceptées sont default et large.
zone STRING Non (aucun) Zone dans laquelle l'algorithme est exécuté. Elle doit être l'une des zones de la région dans laquelle la requête est reçue.
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 la sortie de l'algorithme

Vous devez conserver les résultats des requêtes d'algorithme avant de pouvoir les examiner. 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 à partir de laquelle la requête a été lancée.

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 service-PROJECT_NUMBER@gcp-sa-spanner.iam.gserviceaccount.com.

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 autorisées : CSV, PARQUET, AVRO.
header BOOL Non Si le format vaut true, le système imprime des en-têtes de colonnes 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 avec 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. Valeur 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 les suivantes : 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 acceptent un seul opérateur générique (*) dans uri. Le caractère générique peut apparaître dans le nom de fichier, mais pas dans le nom du bucket, du dossier ni dans l'extension du 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 nombre (en commençant à zéro), 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 fichier unique, comme 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.
  • Les valeurs BYTES sont encodées en base64.
  • Les valeurs TIMESTAMP sont au format YYYY-MM-DD HH:MM:SS.ffffff UTC.
  • Les valeurs NULL apparaissent 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 en cas d'erreurs autres que celles liées à la violation de contraintes (par exemple, incompatibilité du type de colonne, valeurs manquantes pour les colonnes NOT NULL).

Conditions requises

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

  • La table de destination doit exister.
  • Les colonnes doivent exister avec un type correspondant : tous les noms de colonnes spécifiés dans la clause RETURN doivent déjà exister dans la table de destination avec un type de données correspondant. Si nécessaire, utilisez des alias pour faire correspondre les noms de colonnes de la table de destination. Exemple : RETURN node.id AS person_id.
  • Incluez 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 l'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. Elle suit la sémantique de type "au moins une fois". Cela signifie qu'une ligne peut être écrite plusieurs fois. La lecture à partir de la table de destination pendant l'exécution peut générer des résultats incomplets.

Si l'exécution globale échoue, le système n'effectue pas de rollback sur 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 ayant échoué, ainsi que la raison spécifique de l'échec.

Le système réécrit les résultats de l'algorithme dans Spanner Graph à l'aide de MEDIUM priority.

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. Actualisez ensuite 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 PageRank pour classer les Account en fonction des Transactions auxquels ils participent et conserve les résultats dans un fichier CSV Cloud Storage 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, vous devriez voir un fichier CSV avec deux colonnes (id et page_rank) une fois cette 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 dynamiquement un sous-graphe logique contenant tous les nœuds Account et uniquement les arêtes Transfer avec un montant 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 graphique aboutit, elle renvoie zéro ligne et l'état Success. Selon la taille du graphique d'entrée et les configurations d'algorithme spécifiques, 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 graphique.
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 à laquelle l'état a été mis à jour pour la dernière fois.
PROGRESS FLOAT 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 sont PENDING, IN_PROGRESS, OK, CANCELLED, DEADLINE_EXCEEDED et 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 graphiques qui n'ont pas encore été exécutées correctement :

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 graphique en cours, localisez le query_id dans le tableau SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS, puis appelez cancel_query pour ce query_id.

Étapes suivantes