Panoramica dello schema

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Nota: per richiedere assistenza o fornire un feedback su questa funzionalità, invia un'email all'indirizzo [e-mail].

Questo documento spiega i componenti di uno schema del grafico delle proprietà e mostra come creare e gestire uno schema del grafico.

I grafici ti consentono di modellare i dati connessi che rappresentano le informazioni come una rete di nodi e archi. Uno schema del grafico è costituito da nodi e archi, nonché da etichette che classificano il loro tipo e da proprietà che li descrivono. Definisci uno schema di grafo delle proprietà mappando le righe delle tabelle di input ai nodi e agli archi del grafo e definendo etichette e proprietà personalizzate. Per scoprire di più su BigQuery Graph, consulta la panoramica di BigQuery Graph.

Informazioni sul modello dei dati del grafico delle proprietà

Un grafo delle proprietà 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, acquisendo relazioni come acquisti, follower o località.

Nodi e archi possono includere le seguenti informazioni:

• Etichette: classifica i nodi e i tipi di 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 potresti progettare un grafico per modellare le attività finanziarie. Questo grafico include i seguenti tipi di entità modellate come nodi:

• Persona: rappresenta una persona coinvolta 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 account 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.

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

Nodi e archi includono informazioni aggiuntive nelle proprietà.

• I nodi Person includono le seguenti proprietà:

  • name (STRING)
  • id (INT64)

• I bordi Transfers includono questa proprietà:

  • amount (FLOAT64)

Archi diretti e non diretti

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 l'amicizia in un social network, sono non dirette e rappresentano una connessione reciproca. In questo caso, puoi modellare gli archi non orientati come due archi orientati, uno in ogni direzione.

Progettare lo schema

BigQuery Graph ti 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 delle tabelle. 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 delle proprietà 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 account utilizza l'etichetta Account.
• Ogni nodo account include le proprietà id e create_time dalle 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 elemento è la chiave primaria della tabella di input. In alternativa, puoi utilizzare la clausola KEY per definire esplicitamente le chiavi elemento.

Avviso: le chiavi degli elementi devono essere univoche, ma BigQuery non esegue alcun controllo di unicità. È tua responsabilità assicurarti che le chiavi degli elementi siano uniche. In caso contrario, le query del grafico potrebbero restituire risultati errati.

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 in modo esplicito 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 nulla viene mappata a un nodo univoco nel grafico identificato dalla chiave elemento.
• Le righe con una chiave dell'elemento nulla 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 bordo

I bordi sono definiti dalle righe delle tabelle. Per definire un bordo, aggiungi una definizione di bordo alla clausola EDGE TABLES. La forma più semplice di definizione del bordo 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 ai bordi del grafico.

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

• La chiave dell'elemento di ogni bordo è definita nello stesso modo dei nodi.

Riferimenti ai nodi di origine e 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 di arco.

Nell'esempio seguente, crei un grafico delle proprietà FinGraph con quanto segue:

• Person e Account nodi
• PersonOwnAccount bordo

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 PersonOwnAccount predefinita.

Mappare le righe ai bordi

Ogni riga della tabella di input degli archi con una chiave elemento non nulla in genere viene mappata a un singolo arco nel grafico. Tuttavia, se il riferimento al nodo di origine o di destinazionecorrisponde a zero o più nodi nella tabella dei nodi di origine o di destinazione, la riga della 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 unire una tabella edge 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 il relativo arco Owns in entrata. Ciò è mostrato nella seguente dichiarazione CREATE PROPERTY GRAPH. Nella clausola EDGE TABLES, assegni alla tabella Account l'alias Owns. Questo perché ogni elemento nello schema del grafico 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
  );

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

• 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à e un elenco di sinonimi. Questi campi forniscono contesto e migliorano la rilevabilità per le interfacce di query in linguaggio naturale. Non puoi accedere direttamente a questi campi nelle query del grafico e non modificano in alcun modo i risultati della query.

Coerenza di etichette e proprietà

In un grafico, 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 rispettare le seguenti regole:

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

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

Gestire le dipendenze dello schema

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

È tua responsabilità evitare modifiche allo schema che potrebbero causare problemi. Segui queste best practice:

• Prima di eliminare una tabella utilizzata in una definizione di nodo del grafico, rimuovi prima la definizione di 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 del bordo corrispondente.

Visualizza gli schemi del grafico

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 grafico in un blocco note.

Aggiorna uno schema del grafico

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

Elimina uno schema del grafico

Per eliminare un grafico delle proprietà, utilizza l'istruzione DROP PROPERTY GRAPH.

Best practice

Le sezioni seguenti descrivono le best practice per definire lo schema del grafico al fine di migliorare le prestazioni delle query del grafico.

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 collega 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 inutili delle colonne nelle query grafiche, il che peggiora 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 vincoli di chiave primaria e chiave esterna nelle tabelle dei nodi e degli archi per ottimizzare le query del grafico riducendo le scansioni non necessarie delle tabelle. Tuttavia, BigQuery non applica vincoli di chiave primaria o chiave 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 errati.

Il seguente esempio 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

• Scopri di più su BigQuery Graph.
• Scopri come creare ed eseguire query su un grafico delle proprietà.
• Scopri come scrivere query del grafico.
• Scopri di più sulla creazione di grafici con le metriche.