Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Esegui gli algoritmi di Spanner Graph

NOTA:se esegui algoritmi grafici su un'istanza Spanner nella regione us-east1, devi specificare uno di questi come zone nei parametri di input dell'algoritmo: us-east1-b, us-east1-c o us-east1-d. Per tutte le altre regioni, non è necessario specificare una zona.

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. Vedi Opzioni per Cloud Storage e Opzioni per Spanner.
graph_name: il nome del grafico.
<match_clause>: istruzioni MATCH facoltative per definire gli elementi di input dell'algoritmo.
<call_statement>: utilizza CALL quando ometti <match_clause> e vuoi operare sull'intero grafico. Utilizza CALL PER() quando è presente <match_clause> e vuoi operare sulla tabella di lavoro. Per ulteriori informazioni, vedi GQL CALL.
algorithm_name: il nome dell'algoritmo da eseguire. Per gli algoritmi disponibili, vedi Algoritmi di Spanner Graph.
<common_input>: parametri di input denominati comuni a tutte le query dell'algoritmo. Per ulteriori informazioni, consulta la sezione Parametri di input comuni dell'algoritmo.
<algorithm_specific_input>: parametri di input denominati per l'algoritmo. Per ulteriori informazioni, consulta i parametri di input definiti in Algoritmi di grafi di Spanner.
<algorithm_specific_output>: l'output della chiamata dell'algoritmo. Per saperne di più, consulta gli output definiti in Algoritmi del grafico Spanner e 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 del grafo identifica il grafo, CALL un algoritmo che produce un output predefinito e poi specifica cosa RETURN dall'output dell'algoritmo.

Facoltativamente, la clausola del grafico può utilizzare le istruzioni MATCH supportate per selezionare gli elementi di interesse. In questo caso, utilizza una clausola PER () per raggruppare tutte le righe restituite da 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. I risultati vengono salvati in modo permanente in base a export_option_list.

Per saperne di più sulle query dell'algoritmo 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 dell'algoritmo comune

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 specificati, 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 dei lati da includere nell'input dell'algoritmo. Se specificato, vengono inclusi solo i bordi con almeno un'etichetta corrispondente.
`edge_weight_property`	`STRING`	No	(nessuno)	Il nome della proprietà del bordo 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`
`zone`	`STRING`	No	(nessuno)	La zona in cui viene eseguito l'algoritmo. Deve essere una delle zone della regione in cui viene ricevuta la query.
`max_idle_time`	`STRING`	No	30 min	Specifica per quanto tempo l'istanza di calcolo 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 della query dell'algoritmo prima di poterli esaminare. 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 è stata eseguita la query.

Persistenza dei risultati in Cloud Storage

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

Le seguenti opzioni di EXPORT DATA sono supportate durante il salvataggio permanente dei risultati in Cloud Storage. 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.

Esportare i dati in uno o più file

Le query Spanner Graph supportano un singolo operatore 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 jolly con un numero, a partire da zero, con riempimento a sinistra fino a 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 relativa rappresentazione di stringa:

I valori BOOL vengono convertiti in true o false.
Codifica in Base64 dei valori BYTES.
TIMESTAMP valori nel formato YYYY-MM-DD HH:MM:SS.ffffff UTC.
I valori di 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`

Persistere i risultati in Spanner

Le seguenti opzioni di EXPORT DATA sono supportate quando i risultati vengono salvati di nuovo 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.
Le colonne devono esistere 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. Se necessario, utilizza gli alias per far corrispondere i nomi delle colonne della tabella di destinazione. 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.

Scrittura semantica

Il salvataggio dei risultati in Spanner è un'operazione non transazionale. Fornisce l'atomicità a livello di riga. Ciò significa che il sistema scrive correttamente tutte le colonne della stessa riga o non ne scrive 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 già eseguite. 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 riscrive i risultati dell'algoritmo in Spanner Graph utilizzando la MEDIUM priorità.

Esegui query con algoritmo di esempio

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 necessarie.
(Facoltativo) Aumenta lo schema di Spanner Graph se stai rendendo persistente l'output in Spanner.

Aggiungi una nuova colonna denominata page_rank alla tabella Account. Spanner scrive i risultati dell'algoritmo in questa nuova colonna. Poi, aggiorna la definizione del grafico per 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 grafico completo con il filtro delle etichette e salva i risultati in Cloud Storage

Questo esempio esegue PageRank per classificare i Account in base ai Transactions a cui partecipano e salva i risultati in un file 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, al termine della query dovresti visualizzare un file CSV con due colonne (id e page_rank).

Esegui l'algoritmo sul sottografo definito da `MATCH` e salva i risultati nel grafico

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

Una volta completata la query, esegui la seguente:

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 dell'algoritmo del 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 dell'algoritmo del grafico.
`QUERY_TEXT`	`STRING`	Il testo dell'istruzione query.
`START_TIMESTAMP`	`TIMESTAMP`	L'ora in cui è iniziata l'esecuzione della query.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	L'ora in cui è stato aggiornato lo stato.
`PROGRESS`	`FLOAT`	Percentuale di completamento stimata. Il valore è compreso tra `0` e `1`, dove `0` indica l'inizio e `1` il completamento.
`STATUS`	`STRING`	Stato attuale dell'esecuzione. I valori possibili sono `PENDING`, `IN_PROGRESS`, `OK`, `CANCELLED`, `DEADLINE_EXCEEDED`, `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 dell'algoritmo del grafico in volo, individua query_id dalla tabella SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS, quindi chiama cancel_query per query_id.