Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Esegui gli algoritmi di Spanner Graph

Questo documento spiega come eseguire algoritmi su Spanner Graph.

Struttura della query con algoritmo Spanner Graph

Una query con algoritmo Spanner Graph ha la seguente struttura:

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: opzioni che definiscono come rendere persistenti i risultati delle query dell'algoritmo. Consulta Opzioni di Cloud Storage e Opzioni di Spanner.
graph_name: il nome del grafico.
match_clause: istruzioni MATCH facoltative per definire gli elementi di input dell'algoritmo.
call_statement: utilizza l'istruzione CALL quando ometti la variabile match_clause e vuoi operare sull'intero grafico. Utilizza l'istruzione CALL PER() quando la variabile match_clause è presente e vuoi operare sulla tabella di lavoro. Per saperne di più, consulta GQL CALL.
algorithm_name: il nome dell'algoritmo da eseguire. Per gli algoritmi disponibili, consulta Algoritmi di Spanner Graph.
common_input: Parametri di input denominati comuni a tutte le query dell'algoritmo. Per saperne di più, consulta la sezione Parametri di input comuni dell'algoritmo.
algorithm_specific_input: parametri di input denominati per l'algoritmo. Per saperne di più, consulta i parametri di input definiti negli algoritmi di Spanner Graph.
algorithm_specific_output: L'output della chiamata dell'algoritmo. Per saperne di più, consulta gli output definiti negli algoritmi di Spanner Graph e la clausola YIELD nell'istruzione CALL.
results: definisce cosa restituire nei risultati della query.

La query è composta da un'istruzione EXPORT DATA, che definisce come rendere persistenti i risultati, e da una CLAUSOLA GRAPH che produce il risultato della query dell'algoritmo.

Nella sua forma più semplice, la clausola graph identifica il grafico, utilizza un'istruzione CALL per richiamare un algoritmo che genera un output predefinito, quindi utilizza un'istruzione RETURN per specificare cosa restituire dall'output dell'algoritmo.

Facoltativamente, la clausola graph può utilizzare istruzioni MATCH supportate per selezionare gli elementi di interesse. In questo caso, utilizza una clausola PER () per raggruppare tutte le righe restituite dall'istruzione MATCH come input per l'algoritmo. L'algoritmo opera su un sottografo logico composto dall'insieme univoco di nodi e archi selezionati.

La query non restituisce dati. La variabile export_option_list determina la modalità di persistenza dei risultati.

Per saperne di più sulle query degli algoritmi di Spanner Graph, consulta le seguenti sezioni di questo documento:

Parametri di input comuni dell'algoritmo
Gestire l'output dell'algoritmo
Esegui query di esempio con algoritmo

Parametri di input degli algoritmi comuni

Specifica questi parametri di input denominati nel seguente formato: NAME => VALUE, ....

Nome	Tipo di valore	Obbligatorio	Valore predefinito	Descrizione
`node_labels`	`ARRAY`	No	(nessuno)	Supportato solo quando viene utilizzato `CALL`. Un elenco di etichette dei nodi da includere nell'input dell'algoritmo. Se specificato, vengono inclusi solo i nodi con almeno un'etichetta corrispondente.
`edge_labels`	`ARRAY`	No	(nessuno)	Supportato solo quando viene utilizzato `CALL`. Un elenco di etichette degli archi da includere nell'input dell'algoritmo. Se specificato, vengono inclusi solo gli archi con almeno un'etichetta corrispondente.
`edge_weight_property`	`STRING`	No	(nessuno)	Il nome della proprietà dell'arco che contiene i pesi. Se non definito, il sistema assegna un peso predefinito pari a 1 a tutti gli archi. Il tipo di valore della proprietà deve essere numerico.
`machine_category`	`STRING`	No	predefinito	La categoria di macchina da utilizzare per l'esecuzione dell'algoritmo. I valori supportati sono: `default`, `large`
`fallback_compute_region`	`STRING`	No	(nessuno)	La regione di fallback in cui viene eseguita l'esecuzione dell'algoritmo se la regione di origine presenta limiti di capacità. Deve trovarsi nella stessa giurisdizione della regione di origine dell'istanza Spanner (ad esempio, `us-central1` se la regione di origine è `us-east1`).
`max_idle_time`	`STRING`	No	30 min	Specifica per quanto tempo l'istanza di computing deve rimanere attiva per il riutilizzo dopo il completamento dell'algoritmo. Il formato è una sequenza di numeri decimali, ciascuno con un suffisso di unità, ad esempio `4m`, `1.5h` o `1h45m`. Le unità di tempo valide sono `ns`, `us` (o `µs`), `ms`, `s`, `m`, `h`.

Gestire l'output dell'algoritmo

Devi rendere persistenti i risultati delle query dell'algoritmo prima di poterli ispezionare. Utilizza export_data_option per descrivere come rendere persistenti i risultati. Puoi rendere persistenti i risultati in Cloud Storage o nella stessa istanza Spanner da cui ha avuto origine la query.

Persistenza dei risultati in Cloud Storage

Per utilizzare questa opzione, assicurati che al service account Spanner service-PROJECT_NUMBER@gcp-sa-spanner. gestito da Google sia concesso il ruolo Storage Object Admin (roles/storage.objectAdmin).

Quando i risultati vengono salvati in modo permanente in Cloud Storage, sono supportate le seguenti opzioni di EXPORT DATA. Specifica le opzioni nel seguente formato: NAME=VALUE, ....

Nome	Tipo di valore	Obbligatorio	Descrizione
`uri`	`STRING`	Sì	L'URI di destinazione per l'esportazione, in formato `gs://bucket/path/file`. Se esporti una grande quantità di dati, utilizza un carattere jolly in `uri` per esportare i dati in più file. Ad esempio: `gs://bucket/path/file_*.csv`.
`format`	`STRING`	Sì	Il formato dei dati esportati. Valori supportati: `CSV`, `PARQUET`, `AVRO`.
`header`	`BOOL`	No	Se `true`, il sistema stampa le intestazioni di colonna per la prima riga di ogni file di dati. Il valore predefinito è `false`. Si applica solo ai file CSV.
`overwrite`	`BOOL`	No	Se `true`, il sistema sovrascrive tutti i file esistenti con lo stesso URI. In caso contrario, se esistono file con lo stesso URI, l'istruzione restituisce un errore. Il valore predefinito è `false`.
`field_delimiter`	`STRING`	No	Il delimitatore che separa i campi. Valore predefinito: `,` (virgola). Si applica solo ai file CSV.
`compression`	`STRING`	No	Specifica il formato di compressione. Se non specifichi un formato di compressione, i file rimangono non compressi. Per `CSV`, il valore supportato è `GZIP`. Per `PARQUET`, i valori supportati sono: `SNAPPY`, `GZIP`, `ZSTD`. Per `AVRO`, i valori supportati sono: `DEFLATE`, `SNAPPY`.

I nomi delle colonne nella clausola RETURN definiscono i nomi delle colonne nei file di output di Cloud Storage.

Esporta i dati in uno o più file

Le query Spanner Graph supportano un singolo operatore con carattere jolly (*) in uri. Il carattere jolly può essere visualizzato nel componente del nome file, ma non nel nome del bucket, nel nome della cartella o nell'estensione del file. L'utilizzo dell'operatore jolly indica a Spanner Graph di creare più file suddivisi in shard in base al pattern fornito se il set di risultati è di grandi dimensioni. Il sistema sostituisce l'operatore con caratteri jolly con un numero, a partire da zero, con spaziatura interna a sinistra di 12 cifre. Ad esempio, un URI gs://my-bucket/file-*.csv crea file come gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv e simili.

Se utilizzi un uri senza carattere jolly, il risultato è un singolo file, ad esempio gs://my-bucket/file.csv.

Tipi di dati

Quando esporti i dati, i tipi di dati del grafico Spanner vengono convertiti come segue, a seconda del formato:

CSV

Tutti i tipi di dati vengono convertiti nella loro rappresentazione di stringa:

I valori BOOL vengono convertiti in true o false.
Valori BYTES codificati in Base64.
I valori TIMESTAMP vengono formattati come YYYY-MM-DD HH:MM:SS.ffffff UTC.
I valori NULL vengono visualizzati come stringhe vuote.

Non puoi esportare dati nidificati e ripetuti in formato CSV.

Avro

Tipo di dati Spanner	Tipo di dati Avro
`BOOL`	`BOOLEAN`
`INT64`	`LONG`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`BYTES` con tipo logico `DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTES`
`TIMESTAMP`	`LONG` (microsecondi dall'epoca)
`NULL`	`null`

Parquet

Tipo di dati Spanner	Tipo di dati Parquet
`BOOL`	`BOOLEAN`
`INT64`	`INT64`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTE_ARRAY`
`TIMESTAMP`	`TIMESTAMP_MICROS`
`NULL`	`null`

Rendere persistenti i risultati in Spanner

Le seguenti opzioni EXPORT DATA sono supportate quando i risultati vengono salvati nell'istanza Spanner di origine. Specifica le opzioni nel seguente formato: NAME=VALUE, ....

Nome	Tipo di valore	Obbligatorio	Descrizione
`format`	`STRING`	Sì	Il formato dei dati esportati. Deve essere `CLOUD_SPANNER`.
`table`	`STRING`	Sì	Il nome della tabella Spanner di destinazione in cui scrivere i risultati. Può essere qualsiasi tabella nell'istanza Spanner.
`write_mode`	`STRING`	Sì	La modalità di scrittura da utilizzare. I valori supportati sono: `update_ignore_all`: aggiorna le righe esistenti nella tabella di destinazione. `upsert_ignore_all`: inserisce nuove righe o aggiorna quelle esistenti nella tabella di destinazione. In entrambe le modalità, Spanner ignora qualsiasi record che introdurrebbe una violazione dei vincoli (ad esempio, chiavi mancanti in un aggiornamento, violazione dell'indice univoco, violazione del vincolo di chiave esterna). Tuttavia, la scrittura non riesce per errori di violazione dei vincoli (ad esempio, mancata corrispondenza del tipo di colonna, valori mancanti per le colonne NOT NULL).

Requisiti

Quando rendi persistenti i risultati dell'algoritmo in Spanner, la query dell'algoritmo deve soddisfare i seguenti requisiti:

La tabella di destinazione deve esistere.
Devono esistere colonne con un tipo corrispondente: tutti i nomi delle colonne specificati nella clausola RETURN devono già esistere nella tabella di destinazione con un tipo di dati corrispondente. Utilizza gli alias per far corrispondere i nomi delle colonne della tabella di destinazione, se necessario. Esempio: RETURN node.id AS person_id.
Includi tutte le colonne di chiave primaria: la clausola RETURN deve includere tutte le colonne di chiave primaria della tabella di destinazione.

Semantica di scrittura

Il salvataggio dei risultati in Spanner è un'operazione non transazionale. Offre l'atomicità a livello di riga. Ciò significa che il sistema scrive tutte le colonne della stessa riga o nessuna. Segue la semantica "at-least-once". Ciò significa che una riga può essere scritta più volte. La lettura dalla tabella di destinazione durante l'esecuzione potrebbe produrre risultati incompleti.

Se l'esecuzione complessiva non va a buon fine, il sistema non esegue il rollback delle modifiche di cui è già stato eseguito il commit. Il processo di scrittura non riesce al primo errore non riproducibile. Quando si verifica un errore di scrittura, ERROR_MESSAGE in GRAPH_OPERATION_EXECUTION_STATUS indica la chiave primaria della riga in cui si è verificato l'errore, nonché il motivo specifico dell'errore.

Il sistema scrive i risultati dell'algoritmo in Spanner Graph utilizzando la priorità MEDIUM.

Esegui query di esempio con algoritmo

Questa sezione mostra query di esempio dell'algoritmo Spanner Graph che puoi eseguire su un'istanza di test. Per un elenco completo degli algoritmi supportati da Spanner Graph, consulta Algoritmi di Spanner Graph.

Prima di iniziare

Per eseguire le query di esempio dell'algoritmo Spanner Graph, devi prima completare le seguenti operazioni:

Segui la procedura descritta in Configura ed esegui query su Spanner Graph per creare un grafico di Spanner Graph.
Assicurati di disporre delle autorizzazioni richieste.
(Facoltativo) Se stai salvando l'output in Spanner, aumenta lo schema di Spanner Graph.

Aggiungi una nuova colonna denominata page_rank alla tabella Account. Spanner scrive i risultati dell'algoritmo in questa nuova colonna. Quindi, aggiorna la definizione del grafico in modo da poter accedere a page_rank come proprietà del nodo.

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

Esegui l'algoritmo sul grafo completo con il filtro delle etichette e mantieni i risultati in Cloud Storage

Questo esempio esegue l'istruzione PageRank per classificare gli account in base ai trasferimenti a cui partecipano. I risultati della query vengono salvati in un bucket Cloud Storage in formato CSV come 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

In Cloud Storage, dovresti vedere un file CSV con due colonne (id e page_rank) quando questa query viene completata correttamente.

Esegui l'algoritmo sul sottografo definito da `MATCH` e mantieni i risultati nel grafo

Questo esempio utilizza il pattern MATCH per trovare dinamicamente una corrispondenza con un sottografo logico contenente tutti i nodi Account e solo gli archi Transfer con un importo inferiore a 500. Questo sottografo logico è l'input dell'algoritmo PageRank. Spanner salva i risultati dell'algoritmo nella tabella 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

Al termine della query, esegui questa query:

GRAPH FinGraph
MATCH (n:Account)
RETURN n.id, ROUND(n.page_rank, 2) AS page_rank
ORDER BY page_rank DESC, id ASC

Dovresti vedere risultati simili ai seguenti:

id	page_rank
20	0,49
16	0,46
7	0,05

Controllare lo stato di esecuzione dell'algoritmo

Quando una query di algoritmo grafico viene completata correttamente, restituisce zero righe e lo stato Success. A seconda delle dimensioni del grafico di input e delle configurazioni specifiche dell'algoritmo, l'esecuzione dell'algoritmo potrebbe richiedere un po' di tempo. Puoi controllare l'avanzamento e lo stato di esecuzione di una query dell'algoritmo del grafico nella tabella SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS. Questa tabella conserva le informazioni per 30 giorni.

`GRAPH_OPERATION_EXECUTION_STATUS` schema

Nome colonna	Tipo	Descrizione
`QUERY_ID`	`STRING`	L'ID della query con algoritmo grafico.
`QUERY_TEXT`	`STRING`	Il testo dell'istruzione della query.
`START_TIMESTAMP`	`TIMESTAMP`	L'ora in cui è iniziata l'esecuzione della query.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	L'ora dell'ultimo aggiornamento dello stato.
`PROGRESS`	`FLOAT64`	Percentuale di completamento stimata. Il valore è compreso tra `0` e `1`, dove `0` indica l'avvio e `1` il completamento.
`STATUS`	`STRING`	Stato attuale dell'esecuzione. I valori possibili includono `PENDING`, `IN_PROGRESS`, `OK` o un codice di stato di errore come `CANCELLED`, `DEADLINE_EXCEEDED`, `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `RESOURCE_EXHAUSTED`, `UNAVAILABLE` o `UNKNOWN`.
`ERROR_MESSAGE`	`STRING`	Messaggio di errore se l'esecuzione della query non è riuscita.

La seguente query di esempio elenca le query del grafico che non sono ancora state completate correttamente:

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;

Annulla l'esecuzione dell'algoritmo

Per annullare una query di algoritmo grafico in corso, individua query_id dalla tabella SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS, quindi chiama cancel_query per quel query_id.