Présentation du schéma

Ce document explique les composants d'un schéma de graphe et vous montre comment créer et gérer un schéma de graphe.

Les graphes vous permettent de modéliser des données connectées qui représentent des informations sous la forme d'un réseau de nœuds et d'arêtes. Un schéma de graphique se compose de nœuds et d'arêtes, ainsi que d'étiquettes qui classent leur type et de propriétés qui les décrivent. Vous définissez un schéma de graphe en mappant les lignes des tables d'entrée aux nœuds et aux arêtes du graphe, et en définissant des étiquettes et des propriétés personnalisées. Pour en savoir plus sur BigQuery Graph, consultez la présentation de BigQuery Graph.

Comprendre le modèle de données de graphe

Un graphe vous permet de modéliser des données connectées sous la forme d'un réseau de nœuds et d'arêtes. Les nœuds représentent des entités dans vos données, comme des clients, des produits ou des lieux. Les arêtes représentent les connexions entre ces nœuds, capturant des relations telles que les achats, les abonnements ou les emplacements.

Les nœuds et les arêtes peuvent inclure les informations suivantes :

  • Étiquettes : classent les types de nœuds et d'arêtes. Par exemple, les élèves d'une classe peuvent avoir une étiquette Student et une étiquette Person. Si vous ne définissez pas explicitement d'étiquette pour un nœud ou une arête, BigQuery Graph utilise le nom de la table d'entrée comme étiquette par défaut.

  • Propriétés : utilisées pour décrire les nœuds et les arêtes. Par exemple, un nœud représentant une personne peut avoir une propriété name avec la valeur Alex et une propriété id avec la valeur 1.

L'exemple de la figure 1 montre comment concevoir un graphe pour modéliser des activités financières. Ce graphique inclut les types d'entités suivants modélisés en tant que nœuds :

  • Person : représente une personne impliquée dans des transactions financières.
  • Account : représente un compte bancaire utilisé pour les transactions.

Ces entités sont connectées par différents types de relations, qui sont représentées par les arêtes orientées suivantes :

  • Propriétaire : une personne possède un ou plusieurs comptes.
  • Transferts : l'argent est transféré d'un compte à un autre.

Chaque arête orientée indique une relation unidirectionnelle qui va d'un nœud source à un nœud de destination. Par exemple, une arête Transfers connecte une source Account à une destination Account, indiquant le flux d'argent.

Nœuds, arêtes, étiquettes et propriétés d'un graphique financier.

Figure 1 : Exemple de graphique avec plusieurs nœuds et arêtes orientées.

Les nœuds et les arêtes incluent des informations supplémentaires dans les propriétés.

  • Les nœuds Person incluent les propriétés suivantes :

    • name (STRING)
    • id (INT64)

  • Les bords Transfers incluent cette propriété :

    • amount (FLOAT64)

Arêtes orientées et non orientées

Les arêtes dirigées indiquent une direction spécifique dans la relation entre les entités. Par exemple, une personne possède un compte, mais un compte ne possède pas une personne. Cependant, certaines relations, comme la relation d'amitié dans un réseau social, sont non orientées et représentent une connexion réciproque. Dans ce cas, vous pouvez modéliser les arêtes non orientées comme deux arêtes orientées, une dans chaque direction.

Concevoir votre schéma

BigQuery Graph vous permet d'utiliser l'instruction CREATE PROPERTY GRAPH pour créer un graphique à partir de tables. Les tables qui créent des graphiques sont appelées tables d'entrée.

Définir un nœud

Les nœuds sont définis par des lignes dans les types de tables ou de vues suivants :

  • Tables standards
  • Tables externes
  • Tables gérées Apache Iceberg
  • Tables du catalogue REST Iceberg Lakehouse
  • Vues, y compris les vues autorisées
  • Vues matérialisées non incrémentielles

Pour définir un nœud, ajoutez une définition de nœud dans la clause NODE TABLES. La forme la plus simple d'une définition de nœud contient le nom d'une table d'entrée avec une clé primaire. BigQuery Graph mappe les lignes de la table d'entrée avec les nœuds du graphe.

Dans l'exemple suivant, vous utilisez la clause NODE TABLES pour définir le nœud Account dans le graphique FinGraph. La définition du nœud contient la table d'entrée Account.

-- Create an Account table.
CREATE TABLE graph_db.Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

-- Use the Account table as the input table for the Account node definition.
CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Account
  );

Par défaut, BigQuery utilise le nom de la table comme étiquette et expose toutes les colonnes de la table d'entrée en tant que propriétés.

  • Chaque nœud de compte utilise l'étiquette Account.
  • Chaque nœud de compte inclut les propriétés id et create_time des colonnes de la table Account.

Clé d'élément

Une définition de nœud définit également la clé d'élément, une collection de colonnes qui identifie de manière unique un nœud de graphique. Par défaut, la clé d'élément est la clé primaire de la table d'entrée. Vous pouvez également utiliser la clause KEY pour définir explicitement les clés d'élément.

L'exemple suivant définit un nœud Account et un nœud Person. Le nœud Account utilise la clé primaire de la table Account comme clé d'élément. Le nœud Person spécifie explicitement la colonne id comme clé d'élément à l'aide de la clause KEY.

CREATE TABLE graph_db.Person (
  id           INT64 NOT NULL,
  name         STRING
);

CREATE TABLE graph_db.Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id),
    graph_db.Account
  );
  • Chaque ligne avec une clé d'élément non nulle correspond à un nœud unique dans le graphique identifié par la clé d'élément.
  • Les lignes avec une clé d'élément nulle sont ignorées.

La même table d'entrée peut être utilisée dans plusieurs définitions de nœuds. Dans ce cas, une ligne donnée de la table d'entrée correspond à un nœud pour chaque définition de nœud.

Définir une arête

Les arêtes sont définies par des lignes dans les types de tables ou de vues suivants :

  • Tables standards
  • Tables externes
  • Tables gérées Apache Iceberg
  • Tables du catalogue REST Iceberg Lakehouse
  • Vues, y compris les vues autorisées
  • Vues matérialisées non incrémentielles

Pour définir une arête, ajoutez une définition d'arête à la clause EDGE TABLES. La forme la plus simple de définition d'arête contient le nom d'une table d'entrée et définit les références des nœuds source et de destination. BigQuery Graph utilise cette définition pour mapper les lignes de la table d'entrée aux arêtes du graphe.

Par défaut, BigQuery utilise le nom de la table comme étiquette et expose toutes les colonnes de la table d'entrée en tant que propriétés.

Références des nœuds source et de destination

Une définition d'arête définit la référence du nœud source et du nœud de destination à l'aide des clauses SOURCE KEY, DESTINATION KEY et REFERENCES. Vous devez définir les nœuds source et de destination avant de les utiliser dans la définition de l'arête.

Dans l'exemple suivant, vous allez créer un graphique nommé FinGraph avec les éléments suivants :

  • Person nœud et Account nœud
  • PersonOwnAccount bord
CREATE TABLE graph_db.Person (
  id            INT64 NOT NULL,
  name          STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.Account (
  id            INT64 NOT NULL,
  create_time   TIMESTAMP,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.PersonOwnAccount (
  id            INT64 NOT NULL,
  account_id    INT64 NOT NULL,
  create_time   TIMESTAMP,
  FOREIGN KEY (account_id) REFERENCES graph_db.Account (id) NOT ENFORCED,
  PRIMARY KEY (id, account_id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person,
    graph_db.Account
  )
  EDGE TABLES (
    PersonOwnAccount
      SOURCE KEY (id) REFERENCES Person (id)
      DESTINATION KEY (account_id) REFERENCES Account (id)
  );

Chaque périphérie PersonOwnAccount connecte un nœud Person (source) à un nœud Account (destination).

  • Le nœud source d'un bord est un nœud Person dont la propriété id est identique à la propriété id du bord.
  • Le nœud de destination d'un bord est un nœud Account dont la propriété id est identique à la propriété account_id du bord.
  • La clé d'élément est la clé primaire de la table PersonOwnAccount, à savoir (id, account_id).
  • Chaque arête possède le même ensemble de propriétés que les colonnes de la table PersonOwnAccount.
  • Chaque périphérie possède l'étiquette par défaut PersonOwnAccount.

Mapper des lignes sur des arêtes

Chaque ligne de la table d'entrée d'arête avec une clé d'élément non nulle correspond généralement à une seule arête de votre graphique. Toutefois, si la référence de nœud source ou de destination correspond à zéro ou plusieurs nœuds dans la table de nœuds source ou de destination, la ligne de la table d'entrée d'arête peut générer zéro ou plusieurs arêtes dans votre graphique.

Définir des nœuds et des arêtes dans une seule table

Vous pouvez définir un nœud et ses arêtes entrantes ou sortantes dans une seule table si les colonnes de votre table définissent une relation avec une autre table. Cette approche réduit le nombre de tables, simplifie la gestion des données et peut améliorer les performances des requêtes en éliminant le besoin d'une jointure à une table d'arêtes distincte.

Par exemple, si la table Account suivante possède une clé primaire composite (owner_id, account_id), la colonne owner_id peut être une clé étrangère qui fait référence à une table Person. Cette structure permet à la table Account de représenter à la fois le nœud Account et l'arête entrante du nœud Person.

CREATE TABLE graph_db.Person (
  id INT64 NOT NULL,
  PRIMARY KEY (id) NOT ENFORCED
);

-- Assume each account has exactly one owner.
CREATE TABLE graph_db.Account (
  owner_id INT64 NOT NULL,
  account_id INT64 NOT NULL,
  FOREIGN KEY (owner_id) REFERENCES graph_db.Person(id) NOT ENFORCED,
  PRIMARY KEY (owner_id, account_id) NOT ENFORCED
);

Vous pouvez utiliser la table Account pour définir à la fois le nœud Account et son bord Owns entrant. comme illustré dans l'instruction CREATE PROPERTY GRAPH suivante. Dans la clause EDGE TABLES, vous attribuez l'alias Owns à la table Account. En effet, chaque élément du schéma de graphique doit avoir un nom unique.

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person,
    graph_db.Account
  )
  EDGE TABLES (
    graph_db.Account AS Owns
      SOURCE KEY (owner_id) REFERENCES Person
      DESTINATION KEY (owner_id, account_id) REFERENCES Account
  );

Personnaliser les étiquettes et les propriétés

Vous pouvez utiliser les clauses LABEL et PROPERTIES pour personnaliser les étiquettes et les propriétés.

L'exemple suivant définit un nœud Person avec une propriété personnalisée et un nœud Account avec plusieurs étiquettes :

CREATE TABLE graph_db.Person (
  id               INT64 NOT NULL,
  name             STRING,
  birthday         TIMESTAMP,
  country          STRING,
  city             STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE TABLE graph_db.Account (
  id               INT64 NOT NULL,
  create_time      TIMESTAMP,
  is_blocked       BOOL,
  nick_name        STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE PROPERTY GRAPH graph_db.FinGraph
  NODE TABLES (
    graph_db.Person KEY (id)
      LABEL Customer
      PROPERTIES (CONCAT(city, ", ", country) AS address)
      LABEL Entity PROPERTIES (id, name),
    graph_db.Account KEY (id)
      DEFAULT LABEL OPTIONS(description = 'A checking or savings account')
      PROPERTIES (id, create_time)
      LABEL Entity
      PROPERTIES (
        id,
        nick_name AS name OPTIONS(description = 'A user-defined account name',
                                  synonyms = ['friendly name', 'display name'],
                                  extensions = [('data_classification', 'user'), ('currency', 'USD')])
      )
  );

  • Les nœuds Person utilisent l'étiquette Customer pour exposer la propriété address. La propriété address est définie par l'expression CONCAT(city, ", ", country), qui fait référence aux colonnes city et country de la table d'entrée Person.

  • Le nœud Account utilise l'étiquette Account pour exposer les propriétés id et create_time.

Les nœuds Person et Account ont tous deux l'étiquette Entity avec les propriétés id et name.

  • Dans le nœud Person, les propriétés id et name proviennent des colonnes de la table d'entrée.
  • Dans le nœud Account, la propriété name fait référence à la colonne nick_name de la table d'entrée.
  • Dans le nœud Account, la propriété name utilise la clause OPTIONS pour fournir une description de la propriété, une liste de synonymes et une liste de paires clé/valeur de métadonnées.

Spécifier des options

Vous pouvez spécifier des métadonnées personnalisées définies par l'utilisateur dans la clause OPTIONS() d'une définition d'étiquette ou de propriété, y compris une définition de mesure. Les options suivantes sont compatibles :

  • description : description de l'étiquette ou de la propriété sous forme de chaîne lisible par l'humain.
  • synonyms : tableau de chaînes représentant les synonymes du libellé ou de la propriété.
  • extensions : tableau de paires de chaînes (ARRAY<STRUCT<STRING, STRING>>) représentant des métadonnées supplémentaires. Vous pouvez utiliser des extensions pour fournir des métadonnées, des unités ou des règles de mise en forme personnalisées, telles que [('currency', 'USD')].

Ces options fournissent du contexte et améliorent la visibilité des interfaces de requêtes en langage naturel. Vous ne pouvez pas accéder directement à ces champs dans vos requêtes de graphe, et ils ne modifient en rien les résultats des requêtes GQL.

Cohérence des étiquettes et des propriétés

Dans un graphique, les étiquettes et les propriétés sont identifiées de manière unique par leur nom. Vous pouvez utiliser des étiquettes et des propriétés portant le même nom dans plusieurs définitions de nœuds ou d'arêtes. Toutefois, les étiquettes et les propriétés portant le même nom doivent respecter les règles suivantes :

  • Les propriétés portant le même nom doivent utiliser le même type de valeur.
  • Les libellés portant le même nom doivent exposer la même liste de propriétés.

Dans l'exemple précédent, l'étiquette Entity est définie à la fois dans les nœuds Person et Account. Les deux définitions incluent le même ensemble de noms de propriétés, id et name, avec des types de valeurs identiques.

Gérer les dépendances de schéma

Les graphiques dépendent du schéma des tables d'entrée pour les définitions de nœuds et d'arêtes, ainsi que des colonnes de table référencées par les propriétés. BigQuery Graph ne vérifie pas si la suppression ou la modification de tables ou de colonnes invalide un schéma de graphe existant.

Vous devez éviter d'apporter des modifications destructives au schéma. Suivez ces bonnes pratiques :

  • Avant de supprimer une table utilisée dans une définition de nœud de graphique, supprimez d'abord cette définition de nœud du graphique.
  • Avant de supprimer une colonne d'une table exposée en tant que propriété dans un graphe, supprimez la propriété de la définition de nœud ou d'arête correspondante.

Afficher les schémas de graphe

Pour afficher l'instruction CREATE PROPERTY GRAPH utilisée pour créer un graphique existant, interrogez la vue INFORMATION_SCHEMA.PROPERTY_GRAPHS :

SELECT
  property_graph_name,
  ddl
FROM
  `region-REGION`.INFORMATION_SCHEMA.PROPERTY_GRAPHS;

Remplacez REGION par la région de l'ensemble de données contenant le graphe.

Vous pouvez également visualiser le schéma de votre graphe dans un notebook.

Mettre à jour un schéma de graphe

Pour modifier le schéma d'un graphe existant, vous devez le redéfinir à l'aide de l'instruction CREATE PROPERTY GRAPH.

Supprimer un schéma de graphe

Pour supprimer un graphique, utilisez l'instruction DROP PROPERTY GRAPH.

Bonnes pratiques

Les sections suivantes décrivent les bonnes pratiques pour définir votre schéma de graphe afin d'améliorer les performances de vos requêtes de graphe.

Définir le champ d'application de vos définitions de propriétés

Les propriétés sont des paires clé/valeur qui fournissent des informations supplémentaires associées aux nœuds ou aux arêtes. Nous vous recommandons de n'inclure que les propriétés nécessaires dans les nœuds ou les arêtes, et d'éviter d'utiliser la syntaxe PROPERTIES ALL COLUMNS ou la syntaxe par défaut qui associe toutes les colonnes des tables de nœuds ou d'arêtes à la liste des propriétés. La présence de nombreuses propriétés dans les nœuds ou les arêtes peut entraîner des analyses de colonnes inutiles dans les requêtes de graphe, ce qui dégrade les performances.

Pour limiter les propriétés que vous incluez dans une définition de nœud ou d'arête, utilisez le mot clé PROPERTIES lorsque vous définissez des propriétés d'élément dans votre instruction CREATE PROPERTY GRAPH.

La définition de table de nœuds suivante limite les propriétés de la table de nœuds Person à id et name :

NODE TABLES (
  graph_db.Person PROPERTIES (id, name)
)

Définir des contraintes de clé primaire et de clé étrangère sur les nœuds et les arêtes du graphe

BigQuery peut utiliser des contraintes de clé primaire et étrangère sur vos tables de nœuds et d'arêtes pour optimiser vos requêtes de graphe en réduisant les analyses de table inutiles. Toutefois, BigQuery n'applique pas de contraintes de clé primaire ou étrangère aux tables. Si votre application ne peut pas garantir l'intégrité référentielle ou l'unicité des clés primaires, l'utilisation de clés primaires ou étrangères pour l'optimisation des requêtes peut entraîner des résultats de requête incorrects.

L'exemple suivant définit des contraintes de clé primaire et de clé étrangère sur les tables de nœuds Person et Account, ainsi que sur la table d'arêtes PersonOwnAccount :

CREATE OR REPLACE TABLE graph_db.Person (
  id               INT64,
  name             STRING,
  birthday         TIMESTAMP,
  country          STRING,
  city             STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_db.Account (
  id               INT64,
  create_time      TIMESTAMP,
  is_blocked       BOOL,
  nick_name        STRING,
  PRIMARY KEY (id) NOT ENFORCED
);

CREATE OR REPLACE TABLE graph_db.PersonOwnAccount (
  id               INT64 NOT NULL,
  account_id       INT64 NOT NULL,
  create_time      TIMESTAMP,
  PRIMARY KEY (id, account_id) NOT ENFORCED,
  FOREIGN KEY (id) references graph_db.Person(id) NOT ENFORCED,
  FOREIGN KEY (account_id) references graph_db.Account(id) NOT ENFORCED
);

Étapes suivantes