Panoramica dello schema

Questo documento spiega i componenti di uno schema del grafo e mostra come crearne e gestirne uno.

I grafi consentono di modellare dati connessi che rappresentano le informazioni come una rete di nodi e archi. Uno schema di grafo è costituito da nodi e archi, insieme a etichette che ne classificano il tipo e proprietà che li descrivono. Per definire uno schema del grafo, mappa le righe delle tabelle di input ai nodi e agli archi del grafo e definisci etichette e proprietà personalizzate. Per scoprire di più su BigQuery Graph, consulta la panoramica di BigQuery Graph.

Informazioni sul modello dei dati del grafo

Un grafo consente di modellare i dati connessi come una rete di nodi e archi. I nodi rappresentano le entità nei dati, come clienti, prodotti o località. Gli archi rappresentano le connessioni tra questi nodi e indicano relazioni come acquisti, follower o località.

I nodi e gli archi possono includere le seguenti informazioni:

  • Etichette: classificano i tipi di nodi e archi. Ad esempio, gli studenti di un corso potrebbero avere un'etichetta Student e un'etichetta Person. Se non definisci esplicitamente un'etichetta per un nodo o un arco, BigQuery Graph utilizza il nome della tabella di input come etichetta predefinita.

  • Proprietà: utilizzate per descrivere nodi e archi. Ad esempio, un nodo che rappresenta una persona potrebbe avere una proprietà name con il valore Alex e una proprietà id con il valore 1.

L'esempio nella Figura 1 mostra come progettare un grafo per modellare le attività finanziarie. Questo grafico include i seguenti tipi di entità modellate come nodi:

  • Persona: rappresenta un individuo coinvolto in transazioni finanziarie.
  • Account: rappresenta un conto bancario utilizzato per le transazioni.

Queste entità sono collegate da diversi tipi di relazioni, rappresentate dai seguenti archi diretti:

  • Proprietario: una persona possiede uno o più account.
  • Trasferimenti: il denaro viene spostato da un conto a un altro.

Ogni arco orientato indica una relazione unidirezionale che va da un nodo di origine a un nodo di destinazione. Ad esempio, un arco Transfers collega un'origine Account a una destinazione Account, indicando il flusso di denaro.

Nodi, archi, etichette e proprietà di un grafo finanziario.

Figura 1. Esempio di grafico con più nodi e archi diretti.

Nodi e archi includono informazioni aggiuntive nelle proprietà.

  • I nodi Person includono queste proprietà:

    • name (STRING)
    • id (INT64)

  • I bordi Transfers includono questa proprietà:

    • amount (FLOAT64)

Archi orientati e non orientati

Gli archi diretti indicano una direzione specifica nella relazione tra le entità. Ad esempio, una persona possiede un account, ma un account non possiede una persona. Tuttavia, alcune relazioni, come la relazione di amicizia in un social network, sono non orientate e rappresentano una connessione reciproca. In questo caso, puoi modellare gli archi non orientati come due archi orientati, uno per ogni direzione.

Progetta lo schema

BigQuery Graph consente di utilizzare l'istruzione CREATE PROPERTY GRAPH per creare un grafico dalle tabelle. Le tabelle che creano i grafici sono chiamate tabelle di input.

Definisci un nodo

I nodi sono definiti dalle righe nei seguenti tipi di tabelle o viste:

  • Tabelle standard
  • Tabelle esterne
  • Tabelle gestite Apache Iceberg
  • Tabelle del catalogo REST Iceberg di Lakehouse
  • Viste, incluse le viste autorizzate
  • Viste materializzate non incrementali

Per definire un nodo, aggiungi una definizione di nodo nella clausola NODE TABLES. La forma più semplice di una definizione di nodo contiene il nome di una tabella di input con una chiave primaria. BigQuery Graph mappa le righe della tabella di input ai nodi del grafico.

Nell'esempio seguente, utilizzi la clausola NODE TABLES per definire il nodo Account nel grafico FinGraph. La definizione del nodo contiene la tabella di input 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
  );

Per impostazione predefinita, BigQuery utilizza il nome della tabella come etichetta ed espone tutte le colonne della tabella di input come proprietà.

  • Ogni nodo dell'account utilizza l'etichetta Account.
  • Ogni nodo dell'account include le proprietà id e create_time delle colonne della tabella Account.

Chiave elemento

Una definizione di nodo definisce anche la chiave elemento, una raccolta di colonne che identifica in modo univoco un nodo del grafico. Per impostazione predefinita, la chiave dell'elemento è la chiave primaria della tabella di input. In alternativa, puoi utilizzare la clausola KEY per definire esplicitamente le chiavi degli elementi.

L'esempio seguente definisce un nodo Account e un nodo Person. Il nodo Account utilizza la chiave primaria della tabella Account come chiave dell'elemento. Il nodo Person specifica esplicitamente la colonna id come chiave dell'elemento utilizzando la clausola 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
  );
  • Ogni riga con una chiave elemento non null viene mappata a un nodo univoco nel grafo identificato dalla chiave elemento.
  • Le righe con una chiave elemento null vengono ignorate.

La stessa tabella di input può essere utilizzata in più definizioni di nodi. In questo caso, una determinata riga della tabella di input viene mappata a un nodo per ogni definizione di nodo.

Definisci un arco

Gli archi sono definiti dalle righe nei seguenti tipi di tabelle o viste:

  • Tabelle standard
  • Tabelle esterne
  • Tabelle gestite Apache Iceberg
  • Tabelle del catalogo REST Iceberg di Lakehouse
  • Viste, incluse le viste autorizzate
  • Viste materializzate non incrementali

Per definire un arco, aggiungi una definizione di arco alla clausola EDGE TABLES. La forma più semplice di definizione di un arco contiene il nome di una tabella di input e definisce i riferimenti ai nodi di origine e di destinazione. BigQuery Graph utilizza questa definizione per mappare le righe della tabella di input agli archi del grafico.

Per impostazione predefinita, BigQuery utilizza il nome della tabella come etichetta ed espone tutte le colonne della tabella di input come proprietà.

Riferimenti ai nodi di origine e di destinazione

Una definizione di arco definisce il riferimento al nodo di origine e di destinazione utilizzando le clausole SOURCE KEY, DESTINATION KEY e REFERENCES. Devi definire i nodi di origine e di destinazione prima di utilizzarli nella definizione dell'arco.

Nell'esempio seguente, crei un grafo denominato FinGraph con i seguenti elementi:

  • Person e Account nodi
  • PersonOwnAccount arco
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)
  );

Ogni arco PersonOwnAccount collega un nodo Person (origine) a un nodo Account (destinazione).

  • Il nodo di origine di un arco è un nodo Person in cui la proprietà id è uguale alla proprietà id dell'arco.
  • Il nodo di destinazione di un arco è un nodo Account in cui la proprietà id è uguale alla proprietà account_id dell'arco.
  • La chiave dell'elemento è la chiave primaria della tabella PersonOwnAccount, ovvero (id, account_id).
  • Ogni arco ha lo stesso insieme di proprietà delle colonne della tabella PersonOwnAccount.
  • Ogni arco ha l'etichetta predefinita PersonOwnAccount.

Mappa le righe agli archi

Ogni riga della tabella di input degli archi con una chiave elemento non null viene in genere mappata a un singolo arco nel grafico. Tuttavia, se il riferimento al nodo di origine o di destinazione corrisponde a zero o più nodi nella tabella dei nodi di origine o di destinazione, la riga nella tabella di input degli archi potrebbe generare zero o più archi nel grafico.

Definisci nodi e archi all'interno di una singola tabella

Puoi definire un nodo e i relativi archi in entrata o in uscita in una singola tabella se le colonne della tabella definiscono una relazione con un'altra tabella. Questo approccio riduce il numero di tabelle, semplifica la gestione dei dati e può migliorare le prestazioni delle query eliminando la necessità di un join a una tabella di archi separata.

Ad esempio, se la seguente tabella Account ha una chiave primaria composita (owner_id, account_id), la colonna owner_id può essere una chiave esterna che fa riferimento a una tabella Person. Questa struttura consente alla tabella Account di rappresentare sia il nodo Account sia l'arco in entrata dal nodo 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
);

Puoi utilizzare la tabella Account per definire sia il nodo Account sia l'arco Owns in entrata. Questo è mostrato nella seguente istruzione CREATE PROPERTY GRAPH. Nella clausola EDGE TABLES, assegni alla tabella Account l'alias Owns. Questo perché ogni elemento nello schema del grafo deve avere un nome univoco.

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
  );

Personalizza etichette e proprietà

Puoi utilizzare le clausole LABEL e PROPERTIES per personalizzare etichette e proprietà.

L'esempio seguente definisce un nodo Person con una proprietà personalizzata e un nodo Account con più etichette:

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')])
      )
  );

  • I nodi Person utilizzano l'etichetta Customer per esporre la proprietà address. La proprietà address è definita dall'espressione CONCAT(city, ", ", country), che fa riferimento alle colonne city e country della tabella di input Person.

  • Il nodo Account utilizza l'etichetta Account per esporre le proprietà id e create_time.

I nodi Person e Account hanno entrambi l'etichetta Entity con le proprietà id e name.

  • Nel nodo Person, le proprietà id e name provengono dalle colonne della tabella di input.
  • Nel nodo Account, la proprietà name fa riferimento alla colonna nick_name della tabella di input.
  • Nel nodo Account, la proprietà name utilizza la clausola OPTIONS per fornire una descrizione della proprietà, un elenco di sinonimi e un elenco di coppie chiave-valore di metadati.

Specifica le opzioni

Puoi specificare metadati personalizzati definiti dall'utente all'interno della clausola OPTIONS() di una definizione di etichetta o proprietà, inclusa una definizione di misura. Sono supportate le seguenti opzioni:

  • description: una descrizione della stringa leggibile dell'etichetta o della proprietà.
  • synonyms: un array di stringhe che rappresenta i sinonimi dell'etichetta o della proprietà.
  • extensions: un array di coppie di stringhe (ARRAY<STRUCT<STRING, STRING>>) che rappresenta metadati aggiuntivi. Puoi utilizzare le estensioni per fornire metadati, unità o regole di formattazione personalizzati, ad esempio [('currency', 'USD')].

Queste opzioni forniscono il contesto e migliorano la rilevabilità per le interfacce di query in linguaggio naturale. Non puoi accedere a questi campi direttamente nelle query del grafo e non modificano in alcun modo i risultati delle query GQL.

Coerenza di etichette e proprietà

In un grafo, le etichette e le proprietà sono identificate in modo univoco dai loro nomi. Puoi utilizzare etichette e proprietà con lo stesso nome in più definizioni di nodi o archi. Tuttavia, le etichette e le proprietà con lo stesso nome devono seguire queste regole:

  • Le proprietà con lo stesso nome devono utilizzare lo stesso tipo di valore.
  • Le etichette con lo stesso nome devono mostrare lo stesso elenco di proprietà.

Nell'esempio precedente, l'etichetta Entity è definita sia nel nodo Person sia nel nodo Account. Entrambe le definizioni includono lo stesso insieme di nomi di proprietà, id e name, con tipi di valore identici.

Gestisci le dipendenze dello schema

I grafi dipendono dallo schema delle tabelle di input per le definizioni dei nodi e degli archi e dalle colonne della tabella a cui fanno riferimento le proprietà. BigQuery Graph non controlla se l'eliminazione o la modifica di tabelle o colonne invalida uno schema di grafo esistente.

Sei responsabile di evitare modifiche allo schema che causano errori. Segui queste best practice:

  • Prima di eliminare una tabella utilizzata nella definizione di un nodo del grafico, rimuovi la definizione del nodo dal grafico.
  • Prima di rimuovere una colonna da una tabella esposta come proprietà in un grafico, rimuovi la proprietà dalla definizione del nodo o dell'arco corrispondente.

Visualizza gli schemi dei grafi

Per visualizzare l'istruzione CREATE PROPERTY GRAPH utilizzata per creare un grafico esistente, esegui una query sulla vista INFORMATION_SCHEMA.PROPERTY_GRAPHS:

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

Sostituisci REGION con la regione del set di dati che contiene il grafico.

In alternativa, puoi visualizzare lo schema del grafo in un notebook.

Aggiorna uno schema del grafo

Per apportare modifiche allo schema di un grafo esistente, devi ridefinire lo schema del grafo utilizzando l'istruzione CREATE PROPERTY GRAPH.

Elimina uno schema del grafo

Per eliminare un grafo, utilizza l'istruzione DROP PROPERTY GRAPH.

Best practice

Le sezioni seguenti descrivono le best practice per la definizione dello schema del grafo per migliorare le prestazioni delle query sul grafo.

Definisci l'ambito delle definizioni delle proprietà

Le proprietà sono coppie chiave-valore che forniscono informazioni aggiuntive associate a nodi o archi. Ti consigliamo di includere solo le proprietà necessarie nei nodi o negli archi ed evitare di utilizzare la sintassi PROPERTIES ALL COLUMNS o la sintassi predefinita che associa tutte le colonne delle tabelle dei nodi o degli archi all'elenco delle proprietà. La presenza di molte proprietà in nodi o archi potrebbe causare scansioni di colonne non necessarie nelle query del grafo, il che riduce le prestazioni.

Per limitare le proprietà che includi in una definizione di nodo o arco, utilizza la parola chiave PROPERTIES quando definisci le proprietà degli elementi nell'istruzione CREATE PROPERTY GRAPH.

La seguente definizione della tabella dei nodi limita le proprietà della tabella dei nodi Person a id e name:

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

Definisci i vincoli di chiave primaria ed esterna su nodi e archi del grafico

BigQuery può utilizzare i vincoli di chiave primaria e chiave esterna sulle tabelle di nodi e archi per ottimizzare le query sui grafi riducendo le scansioni delle tabelle non necessarie. Tuttavia, BigQuery non applica vincoli di chiave primaria o esterna alle tabelle. Se la tua applicazione non può garantire l'integrità referenziale o l'unicità delle chiavi primarie, l'utilizzo di chiavi primarie o chiavi esterne per l'ottimizzazione delle query potrebbe portare a risultati di query errati.

L'esempio seguente definisce i vincoli di chiave primaria e chiave esterna nelle tabelle dei nodi Person e Account e nella tabella degli archi 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
);

Passaggi successivi