Panoramica dello schema di Spanner Graph

Nota: questa funzionalità è disponibile con le versioni Enterprise ed Enterprise Plus di Spanner. Per saperne di più, consulta la Panoramica delle versioni di Spanner.

Spanner Graph consente di modellare i dati connessi come un grafico delle proprietà che rappresenta le informazioni come una rete di nodi e archi. I nodi simboleggiano le entità e gli archi mostrano le connessioni tra di essi. I nodi e gli archi includono etichette che classificano i tipi di nodi e archi. I nodi e gli archi includono anche proprietà che li descrivono.

Questo documento descrive come definire uno schema di Spanner Graph mappando le righe delle tabelle ai nodi e agli archi del grafico. Scoprirai anche come personalizzare le etichette e le proprietà di nodi e archi e come lavorare con le dipendenze degli oggetti di grafici e schemi.

Se vuoi definizioni di grafici più flessibili, consulta Gestire i dati senza schema. Se vuoi scoprire come utilizzare le viste SQL anziché le tabelle per definire nodi e archi, consulta Panoramica dei grafici creati da viste SQL. Per saperne di più su Spanner Graph, consulta la panoramica di Spanner Graph.

Informazioni sul modello dei dati del grafico delle proprietà

Un grafico delle proprietà consente di modellare i dati connessi. Rappresenta le informazioni come una rete di nodi e archi. I nodi simboleggiano le entità nel panorama dei dati, come clienti, prodotti o località. Gli archi mostrano le connessioni tra questi nodi e indicano relazioni come acquistato, segue o situato in.

Sia i nodi sia gli archi possono includere le seguenti informazioni:

• Etichette: classificano i tipi di nodi e archi. Se non definisci esplicitamente un'etichetta per un nodo o un arco, Spanner Graph utilizza il nome della tabella di input come etichetta predefinita. Ad esempio, Account potrebbe essere un'etichetta.

• Proprietà: utilizzate per descrivere nodi e archi. Ad esempio, un nodo Person 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:

• Person: 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:

• Owns: una persona possiede uno o più account.
• Transfers: il denaro si sposta da un conto all'altro.

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

Figura 1. Grafico di esempio con più nodi e archi diretti.

I nodi e gli archi includono informazioni aggiuntive nelle proprietà.

• I nodi Person includono queste proprietà:
  • name (STRING)
  • id (INT64)
• Gli archi Transfers includono questa proprietà:
  • amount (FLOAT64)

Archi diretti e non diretti

Il grafico di esempio utilizza archi diretti che indicano una direzione specifica nella relazione tra le entità. Tuttavia, alcune relazioni, come la relazione amico in un social network, non sono dirette e rappresentano una connessione reciproca senza un'origine o un endpoint distinti. In questo caso, puoi modellare gli archi non diretti come due archi diretti, uno in ogni direzione.

Progettazione dello schema di Spanner Graph

In Spanner Graph utilizzi l' istruzione CREATE PROPERTY GRAPH per creare un grafico da tabelle o viste SQL. Le tabelle utilizzate per creare i grafici sono chiamate tabelle di input. Questo documento mostra come utilizzare le tabelle per creare un grafico. Per informazioni sull'utilizzo delle viste SQL, consulta Creare un grafico di Spanner Graph da una vista SQL.

Nota: Spanner Graph utilizza SQL/PGQ (Property Graph Queries), che fa parte degli standard SQL:2023.

Definire un nodo da una tabella

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 che ha riferimenti ai nodi di origine e di destinazione definiti. Spanner 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.

-- First, create an Account table.
CREATE TABLE Account (
  id           INT64 NOT NULL,
  create_time  TIMESTAMP,
) PRIMARY KEY (id);

-- Next, use the Account table as input table of Account node definition.
CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Account
  );

Etichette e proprietà predefinite

Oltre a utilizzare il nome della tabella di input come etichetta predefinita, Spanner Graph espone tutte le colonne della tabella di input come proprietà dei nodi.

Nell'esempio precedente,

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

Chiave dell'elemento

Una definizione di nodo definisce anche la chiave dell'elemento che identifica in modo univoco un nodo del grafico.

• Per impostazione predefinita, la chiave dell'elemento è la chiave primaria della tabella di input.
• Puoi utilizzare la clausola KEY per definire esplicitamente le chiavi degli elementi.
• Puoi utilizzare le colonne con un vincolo di indice univoco come chiavi degli elementi.

L'esempio seguente definisce il nodo Account e il nodo Person.

• Per impostazione predefinita, il nodo Account utilizza la chiave primaria della tabella Account come chiave dell'elemento.
• Il nodo Person, d'altra parte, specifica esplicitamente id come chiave dell'elemento con la clausola KEY.

CREATE TABLE Person (
  id           INT64 NOT NULL,
  name         STRING(MAX),
) PRIMARY KEY (id);

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

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Person KEY (id),
    Account
  );

Mappare una riga della tabella di input a un nodo nel grafico

• Ogni riga con una chiave dell'elemento non nulla viene mappata a un nodo univoco nel grafico, identificato dalla chiave dell'elemento.
• Le righe con una chiave dell'elemento nulla vengono ignorate.

Nota: la stessa tabella di input può essere utilizzata in più definizioni di nodi. In questo caso, una determinata riga della tabella viene mappata a nodi univoci (un nodo per ciascuna di queste definizioni di nodi).

Definire un arco da una tabella

Per definire un arco, aggiungi una definizione di arco nella clausola EDGE TABLES. La forma più semplice di definizione di arco contiene solo il nome di una tabella di input. Spanner Graph mappa le righe della tabella di input agli archi del grafico.

• L'etichetta e le proprietà predefinite degli archi vengono definite nello stesso modo dei nodi.

• La chiave dell'elemento di ogni arco viene definita nello stesso modo dei nodi.

Riferimenti ai nodi di origine e di destinazione

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

• Nodi Person e Account
• Arco PersonOwnAccount

CREATE TABLE Person (
  id            INT64 NOT NULL,
  name          STRING(MAX),
) PRIMARY KEY (id);

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

CREATE TABLE PersonOwnAccount (
  id            INT64 NOT NULL,
  account_id    INT64 NOT NULL,
  create_time   TIMESTAMP,
  FOREIGN KEY (account_id) REFERENCES Account (id)
) PRIMARY KEY (id, account_id),
  INTERLEAVE IN PARENT Person;

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

Nota: nel DDL precedente, la tabella degli archi PersonOwnAccount utilizza la INTERLEAVE IN PARENT clausola. L'interleaving delle tabelle è un'ottimizzazione dell'archiviazione in Spanner che colloca le righe della tabella figlio (archi) con le righe padre (nodi di origine). Questa collocazione è fondamentale per il rendimento delle query sui grafici durante l'attraversamento degli archi. Per saperne di più, consulta Ottimizzare l'attraversamento degli archi.

Una definizione di arco definisce il riferimento al nodo di origine e di destinazione utilizzando le clausole SOURCE KEY, DESTINATION KEY e REFERENCES. L'esempio seguente utilizza la definizione dell'arco PersonOwnAccount per illustrare questo concetto:

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 id è uguale a id dell'arco.
• Il nodo di destinazione di un arco è un nodo Account in cui id è uguale a account_id dell'arco.

Nota: devi definire i nodi di origine e di destinazione prima di utilizzarli nella definizione dell'arco.

Inoltre, per l'arco PersonOwnAccount vale quanto segue:

• 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.

Mappare una riga di una tabella di input degli archi agli archi nel grafico

• Ogni riga della tabella di input degli archi, in cui la chiave dell'elemento non è nulla, viene in genere mappata a un arco univoco nel grafico.
• Una riga potrebbe corrispondere a zero o più archi nel grafico. Ad esempio, questo si verifica quando il riferimento al nodo di origine corrisponde a zero o più nodi nella tabella dei nodi di origine.

Definire 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 il rendimento delle query eliminando la necessità di un join a una tabella degli archi separata.

Ad esempio, se la seguente tabella Account ha una chiave primaria composta (owner_id, account_id), la parte 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 Person (
    id INT64 NOT NULL,
  ) PRIMARY KEY (id);

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

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

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

Personalizzare etichette e proprietà

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

L'esempio seguente definisce due nodi: Person e Account.

• 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 dalla tabella di input Person.
• Per Account, il nodo Account utilizza l'etichetta Account per esporre le proprietà id e create_time.
• Person e Account hanno l'etichetta Entity con le proprietà [id, name].
  • Per Person, le proprietà id e name provengono dalle colonne della tabella di input.
  • Per Account, la proprietà name fa riferimento alla colonna nick_name della tabella di input.

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

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

CREATE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Person KEY (id)
      LABEL Customer
        PROPERTIES (CONCAT(city, ", ", country) AS address)
      LABEL Entity PROPERTIES (id, name),
    Account KEY (id)
      LABEL Account PROPERTIES (id, create_time)
      LABEL Entity PROPERTIES (id, nick_name AS name)
  );

Coerenza di etichette e proprietà

In un grafico, le etichette e le proprietà sono identificate in modo univoco dai relativi 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 queste regole:

• Le proprietà con lo stesso nome utilizzano lo stesso tipo di valore.
• Le etichette con lo stesso nome espongono lo stesso elenco di proprietà.

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

Dipendenze tra grafici e altri oggetti dello schema

Il grafico creato da CREATE PROPERTY GRAPH dipende da altri oggetti dello schema, come le tabelle di input delle definizioni di nodi e archi e le colonne delle tabelle a cui fanno riferimento le proprietà. Spanner Graph non consente una modifica dello schema che interrompa una di queste dipendenze.

L'istruzione seguente rende FinGraph dipendente dalla tabella Account e dalle colonne id e create_time.

CREATE OR REPLACE PROPERTY GRAPH FinGraph
  NODE TABLES (
    Account PROPERTIES (id, create_time)
  );

In questo esempio, Spanner Graph non consente le seguenti modifiche dello schema:

• Non puoi eliminare la tabella Account. Per farlo, devi rimuovere la definizione del nodo Account. Per saperne di più, consulta Rimuovere le definizioni di nodi o archi esistenti.
• Non puoi eliminare le colonne create_time dalla tabella Account. Per farlo, devi rimuovere la proprietà create_time dalla definizione del nodo Account. Per saperne di più, consulta Aggiornare le definizioni di nodi o archi esistenti.

Tuttavia, puoi apportare le seguenti modifiche allo schema:

• Modifica lo schema della tabella Account e delle colonne id e create_time se altri requisiti dello schema lo consentono. Per saperne di più, consulta Apportare aggiornamenti dello schema.

Visualizzare una visualizzazione dello schema

Puoi visualizzare una visualizzazione dello schema in Spanner Studio dopo aver eseguito una query Spanner Graph. Per saperne di più, consulta Utilizzare le visualizzazioni di Spanner Graph.

Gestire i dati senza schema

Spanner Graph supporta anche la gestione dei dati senza schema, utile quando hai bisogno di una definizione di grafico più flessibile. Per saperne di più, consulta Gestire i dati senza schema in Spanner Graph.

Passaggi successivi

• Crea uno schema di Spanner Graph.
• Aggiorna o elimina uno schema di Spanner Graph.
• Gestisci i dati senza schema con Spanner Graph.
• Scopri le best practice per la progettazione dello schema di Spanner Graph.
• Scopri le best practice per l'ottimizzazione delle query Spanner Graph.