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

Spanner Graph-Algorithmen ausführen

HINWEIS:Wenn Sie Diagrammalgorithmen für eine Spanner-Instanz in der Region us-east1 ausführen, müssen Sie einen der folgenden Werte als zone in den Eingabeparametern Ihres Algorithmus angeben: us-east1-b, us-east1-c oder us-east1-d. Für alle anderen Regionen ist die Angabe einer Zone nicht erforderlich.

In diesem Dokument wird beschrieben, wie Sie Algorithmen für Spanner Graph ausführen.

Struktur von Spanner Graph-Algorithmusabfragen

Eine Spanner Graph-Algorithmusabfrage hat die folgende Struktur:

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>: Optionen, die definieren, wie die Ergebnisse von Algorithmusabfragen beibehalten werden. Weitere Informationen finden Sie unter Cloud Storage-Optionen und Spanner-Optionen.
graph_name: Der Name des Diagramms.
<match_clause>: Optionale MATCH-Anweisungen zum Definieren von Algorithmus-Eingabeelementen.
<call_statement>: Verwenden Sie CALL, wenn Sie <match_clause> weglassen und den gesamten Graphen bearbeiten möchten. Verwenden Sie CALL PER(), wenn <match_clause> vorhanden ist und Sie mit der Arbeitstabelle arbeiten möchten. Weitere Informationen finden Sie unter GQL CALL.
algorithm_name: Der Name des auszuführenden Algorithmus. Informationen zu den verfügbaren Algorithmen finden Sie unter Spanner-Graphenalgorithmen.
<common_input>: Benannte Eingabeparameter, die für alle Algorithmusabfragen gelten. Weitere Informationen finden Sie unter Häufige Eingabeparameter für Algorithmen.
<algorithm_specific_input>: Benannte Eingabeparameter für den Algorithmus. Weitere Informationen finden Sie unter Spanner Graph-Algorithmen.
<algorithm_specific_output>: Die Ausgabe des Algorithmusaufrufs. Weitere Informationen finden Sie in den Ausgaben, die in Spanner-Graphenalgorithmen und YIELD in der CALL-Anweisung definiert sind.
<results>: Definiert, was in den Abfrageergebnissen zurückgegeben werden soll.

Die Abfrage besteht aus einer EXPORT DATA-Anweisung, die definiert, wie Ergebnisse gespeichert werden, und einer GRAPH-KLAUSEL, die das Ergebnis der Algorithmusabfrage erzeugt.

In der einfachsten Form identifiziert die Graph-Klausel den Graphen, CALL ist ein Algorithmus, der eine vordefinierte Ausgabe liefert, und dann wird angegeben, was aus der Ausgabe des Algorithmus RETURN werden soll.

Optional kann in der Graph-Klausel eine unterstützte MATCH-Anweisung verwendet werden, um die gewünschten Elemente auszuwählen. Verwenden Sie in diesem Fall eine PER ()-Klausel, um alle von MATCH zurückgegebenen Zeilen als Eingabe für den Algorithmus zu gruppieren. Der Algorithmus wird auf einem logischen Teilgraphen ausgeführt, der aus der eindeutigen Menge der ausgewählten Knoten und Kanten besteht.

Die Abfrage gibt keine Daten zurück. Die Ergebnisse werden gemäß „export_option_list“ gespeichert.

Weitere Informationen zu Spanner Graph-Algorithmusabfragen finden Sie in den folgenden Abschnitten in diesem Dokument:

Häufig genutzte Eingabeparameter für Algorithmen
Algorithmusausgabe verarbeiten
Beispielabfragen für Algorithmen ausführen

Häufige Eingabeparameter für Algorithmen

Geben Sie diese benannten Eingabeparameter im folgenden Format an: NAME => VALUE, ....

Name	Werttyp	Erforderlich	Standardwert	Beschreibung
`node_labels`	`ARRAY`	Nein	(keine)	Wird nur unterstützt, wenn `CALL` verwendet wird. Eine Liste der Knotenlabels, die in die Algorithmus-Eingabe aufgenommen werden sollen. Falls angegeben, werden nur Knoten mit mindestens einem übereinstimmenden Label berücksichtigt.
`edge_labels`	`ARRAY`	Nein	(keine)	Wird nur unterstützt, wenn `CALL` verwendet wird. Eine Liste der Kantenlabels, die in die Algorithmus-Eingabe einbezogen werden sollen. Falls angegeben, werden nur Kanten mit mindestens einem übereinstimmenden Label berücksichtigt.
`edge_weight_property`	`STRING`	Nein	(keine)	Der Name der Edge-Property, die die Gewichte enthält. Wenn nicht definiert, weist das System allen Kanten ein Standardgewicht von 1 zu. Der Typ des Property-Werts muss numerisch sein.
`machine_category`	`STRING`	Nein	Standard	Die Maschinenkategorie, die für die Ausführung des Algorithmus verwendet werden soll. Unterstützte Werte: `default`, `large`
`zone`	`STRING`	Nein	(keine)	Die Zone, in der die Algorithmusausführung stattfindet. Muss eine der Zonen in der Region sein, in der die Anfrage empfangen wird.
`max_idle_time`	`STRING`	Nein	Lab-Dauer:	Gibt an, wie lange die Compute-Instanz nach Abschluss des Algorithmus für die Wiederverwendung aktiv bleiben soll. Das Format ist eine Folge von Dezimalzahlen, die jeweils ein Einheitensuffix haben, z. B. `4m`, `1.5h` oder `1h45m`. Gültige Zeiteinheiten sind `ns`, `us` (oder `µs`), `ms`, `s`, `m` und `h`.

Algorithmusausgabe verarbeiten

Sie müssen die Abfrageergebnisse des Algorithmus speichern, bevor Sie sie prüfen können. Verwenden Sie export_data_option, um zu beschreiben, wie die Ergebnisse gespeichert werden sollen. Sie können die Ergebnisse in Cloud Storage oder in derselben Spanner-Instanz speichern, aus der die Anfrage stammt.

Ergebnisse in Cloud Storage speichern

Wenn Sie diese Option verwenden möchten, muss dem von Google verwalteten Spanner-Dienstkonto service-PROJECT_NUMBER@gcp-sa-spanner.iam.gserviceaccount.com die Rolle Storage-Objekt-Administrator (roles/storage.objectAdmin) zugewiesen sein.

Die folgenden EXPORT DATA-Optionen werden unterstützt, wenn Ergebnisse in Cloud Storage gespeichert werden. Geben Sie die Optionen im folgenden Format an: NAME=VALUE, ....

Name	Werttyp	Erforderlich	Beschreibung
`uri`	`STRING`	Ja	Der Ziel-URI für den Export im Format `gs://bucket/path/file`. Wenn Sie eine große Datenmenge exportieren, verwenden Sie einen Platzhalter in `uri`, um Daten in mehrere Dateien zu exportieren. Beispiel: `gs://bucket/path/file_*.csv`
`format`	`STRING`	Ja	Das Format der exportierten Daten. Unterstützte Werte: `CSV`, `PARQUET`, `AVRO`.
`header`	`BOOL`	Nein	Beim Wert `true` werden Spaltenüberschriften für die erste Zeile jeder Datendatei ausgegeben. Der Standardwert ist `false`. Gilt nur für CSV.
`overwrite`	`BOOL`	Nein	Wenn `true`, werden alle vorhandenen Dateien mit demselben URI überschrieben. Andernfalls wird ein Fehler zurückgegeben, wenn Dateien mit demselben URI vorhanden sind. Der Standardwert ist `false`.
`field_delimiter`	`STRING`	Nein	Das Trennzeichen, das Felder trennt. Standard: `,` (Komma). Gilt nur für CSV.
`compression`	`STRING`	Nein	Gibt das Komprimierungsformat an. Wenn Sie kein Komprimierungsformat angeben, bleiben die Dateien unkomprimiert. Für `CSV` ist der unterstützte Wert `GZIP`. Für `PARQUET` werden die folgenden Werte unterstützt: `SNAPPY`, `GZIP`, `ZSTD`. Für `AVRO` werden die folgenden Werte unterstützt: `DEFLATE`, `SNAPPY`.

Die Spaltennamen in der RETURN-Klausel definieren die Spaltennamen in Cloud Storage-Ausgabedateien.

Daten in eine oder mehrere Dateien exportieren

Spanner Graph-Abfragen unterstützen einen einzelnen Platzhalteroperator (*) in der uri. Der Platzhalter kann im Dateinamen, aber nicht im Bucket-Namen, Ordnernamen oder in der Dateiendung verwendet werden. Durch Verwendung des Platzhalteroperators wird Spanner Graph angewiesen, mehrere fragmentierte Dateien gemäß dem bereitgestellten Muster zu erstellen, wenn die Ergebnismenge groß ist. Der Platzhalteroperator wird durch eine Zahl (beginnend mit 0) ersetzt und nach links auf 12 Stellen aufgefüllt. Durch den URI gs://my-bucket/file-*.csv werden beispielsweise Dateien wie gs://my-bucket/file-000000000000.csv, gs://my-bucket/file-000000000001.csv und ähnliche Dateien erstellt.

Wenn Sie uri ohne Platzhalter verwenden, ist das Ergebnis eine einzelne Datei, z. B. gs://my-bucket/file.csv.

Datentypen

Wenn Sie Daten exportieren, werden Spanner-Graphendatentypen je nach Format so konvertiert:

CSV

Alle Datentypen werden in ihre String-Darstellung konvertiert:

BOOL-Werte werden in true oder false umgewandelt.
BYTES-Werte werden mit Base64 codiert.
TIMESTAMP-Werte werden als YYYY-MM-DD HH:MM:SS.ffffff UTC formatiert.
NULL-Werte werden als leere Strings angezeigt.

Verschachtelte und wiederkehrende Daten können nicht im CSV-Format exportiert werden.

Avro

Spanner-Datentyp	Avro-Datentyp
`BOOL`	`BOOLEAN`
`INT64`	`LONG`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`BYTES` mit dem logischen Typ `DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTES`
`TIMESTAMP`	`LONG` (Mikrosekunden seit Epoche)
`NULL`	`null`

Parquet

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

Ergebnisse in Spanner speichern

Die folgenden EXPORT DATA-Optionen werden unterstützt, wenn Ergebnisse in Ihrer Quell-Spanner-Instanz gespeichert werden. Geben Sie die Optionen im folgenden Format an: NAME=VALUE, ....

Name	Werttyp	Erforderlich	Beschreibung
`format`	`STRING`	Ja	Das Format der exportierten Daten. Muss `CLOUD_SPANNER` lauten.
`table`	`STRING`	Ja	Der Name der Ziel-Spanner-Tabelle, in die Ergebnisse geschrieben werden sollen. Das kann eine beliebige Tabelle in der Spanner-Instanz sein.
`write_mode`	`STRING`	Ja	Der zu verwendende Schreibmodus. Unterstützte Werte: `update_ignore_all`: Aktualisiert vorhandene Zeilen in der Zieltabelle. `upsert_ignore_all`: Fügt neue Zeilen in die Zieltabelle ein oder aktualisiert vorhandene Zeilen. In beiden Modi werden in Spanner alle Datensätze übersprungen, die zu einem Verstoß gegen eine Einschränkung führen würden (z. B. fehlende Schlüssel bei einer Aktualisierung, Verstoß gegen einen eindeutigen Index, Verstoß gegen eine Fremdschlüsseleinschränkung). Der Schreibvorgang schlägt jedoch bei Fehlern fehl, die nicht auf eine Verletzung von Einschränkungen zurückzuführen sind, z. B. bei einer Abweichung des Spaltentyps oder bei fehlenden Werten für NOT NULL-Spalten.

Voraussetzungen

Wenn Sie Algorithmus-Ergebnisse in Spanner speichern, muss Ihre Algorithmus-Abfrage die folgenden Anforderungen erfüllen:

Die Zieltabelle muss vorhanden sein.
Spalten müssen mit einem passenden Typ vorhanden sein: Alle in der RETURN-Klausel angegebenen Spaltennamen müssen bereits in der Zieltabelle mit einem passenden Datentyp vorhanden sein. Verwenden Sie Aliasse, um die Spaltennamen der Zieltabellen bei Bedarf abzugleichen. Beispiel: RETURN node.id AS person_id.
Alle Primärschlüsselspalten einbeziehen: Die RETURN-Klausel muss alle Primärschlüsselspalten der Zieltabelle enthalten.

Schreibsemantik

Das Speichern von Ergebnissen in Spanner ist ein nicht transaktionaler Vorgang. Sie bietet Atomizität auf Zeilenebene. Das bedeutet, dass das System entweder alle Spalten aus derselben Zeile oder keine von ihnen erfolgreich schreibt. Es wird die „Mindestens einmal“-Semantik verwendet. Das bedeutet, dass eine Zeile mehrmals geschrieben werden kann. Wenn Sie während der Ausführung aus der Zieltabelle lesen, erhalten Sie möglicherweise unvollständige Ergebnisse.

Wenn die Gesamtausführung fehlschlägt, werden bereits ausgeführte Änderungen nicht zurückgesetzt. Der Schreibvorgang schlägt beim ersten nicht wiederholbaren Fehler fehl. Wenn ein Schreibfehler auftritt, gibt ERROR_MESSAGE in GRAPH_OPERATION_EXECUTION_STATUS den Primärschlüssel der fehlgeschlagenen Zeile sowie den spezifischen Grund für den Fehler an.

Die Algorithmus-Ergebnisse werden mit MEDIUM priority in Spanner Graph zurückgeschrieben.

Beispielabfragen für Algorithmen ausführen

In diesem Abschnitt finden Sie Beispielabfragen für Spanner Graph-Algorithmen, die Sie für eine Testinstanz ausführen können. Eine vollständige Liste der von Spanner Graph unterstützten Algorithmen finden Sie unter Spanner Graph-Algorithmen.

Hinweis

Damit Sie die Beispielabfragen für Spanner Graph-Algorithmen ausführen können, müssen Sie zuerst Folgendes tun:

Folgen Sie der Anleitung unter Cloud Spanner Graph einrichten und abfragen, um einen Spanner Graph zu erstellen.
Prüfen Sie, ob Sie die erforderlichen Berechtigungen haben.
Optional: Erweitern Sie das Spanner Graph-Schema, wenn Sie die Ausgabe in Spanner speichern.

Fügen Sie der Tabelle Account eine neue Spalte mit dem Namen page_rank hinzu. Spanner schreibt Algorithmus-Ergebnisse in diese neue Spalte. Aktualisieren Sie dann die Diagrammdefinition, damit Sie auf page_rank als Knotenattribut zugreifen können.

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

Algorithmus für den vollständigen Graphen mit Label-Filter ausführen und Ergebnisse in Cloud Storage speichern

In diesem Beispiel wird PageRank ausgeführt, um Accounts basierend auf den Transactions zu bewerten, an denen sie teilnehmen. Die Ergebnisse werden im CSV-Format als „my-bucket-name/my-output.csv“ in Cloud Storage gespeichert.

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

Wenn diese Abfrage erfolgreich abgeschlossen wird, sollte in Cloud Storage eine CSV-Datei mit zwei Spalten (id und page_rank) angezeigt werden.

Algorithmus für den durch `MATCH` definierten Teilgraphen ausführen und Ergebnisse im Graphen speichern

In diesem Beispiel wird das Muster MATCH verwendet, um dynamisch einen logischen Teilgraphen abzugleichen, der alle Account-Knoten und nur Transfer-Kanten mit einem Betrag von weniger als 500 enthält. Dieser logische Teilgraph ist die Eingabe für den PageRank-Algorithmus. Spanner speichert die Algorithmus-Ergebnisse in der Tabelle 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

Führen Sie nach erfolgreichem Abschluss der Abfrage die folgende Abfrage aus:

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

Die Ergebnisse sollten in etwa so aussehen:

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

Status der Algorithmusausführung prüfen

Wenn eine Abfrage für einen Diagrammalgorithmus erfolgreich abgeschlossen wird, werden keine Zeilen und der Status Success zurückgegeben. Abhängig von der Größe des Eingabediagramms und den spezifischen Algorithmuskonfigurationen kann die Ausführung des Algorithmus einige Zeit in Anspruch nehmen. Sie können den Fortschritt und den Ausführungsstatus einer Graphalgorithmusabfrage in der Tabelle SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS prüfen. In dieser Tabelle werden Informationen 30 Tage lang aufbewahrt.

`GRAPH_OPERATION_EXECUTION_STATUS` Schema

Spaltenname	Typ	Beschreibung
`QUERY_ID`	`STRING`	Die ID für die Abfrage des Diagrammalgorithmus.
`QUERY_TEXT`	`STRING`	Der Text der Abfrageanweisung.
`START_TIMESTAMP`	`TIMESTAMP`	Der Zeitpunkt, zu dem die Ausführung der Abfrage gestartet wurde.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	Der Zeitpunkt, zu dem der Status zuletzt aktualisiert wurde.
`PROGRESS`	`FLOAT`	Geschätzter Prozentsatz der Fertigstellung. Der Wert liegt zwischen `0` und `1`, wobei `0` „gestartet“ und `1` „abgeschlossen“ bedeutet.
`STATUS`	`STRING`	Aktueller Ausführungsstatus. Mögliche Werte sind `PENDING`, `IN_PROGRESS`, `OK`, `CANCELLED`, `DEADLINE_EXCEEDED`, `UNKNOWN`.
`ERROR_MESSAGE`	`STRING`	Fehlermeldung, wenn die Ausführung der Abfrage fehlgeschlagen ist.

In der folgenden Beispielabfrage werden Diagrammabfragen aufgeführt, die noch nicht erfolgreich abgeschlossen wurden:

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;

Algorithmusausführung abbrechen

Wenn Sie eine laufende Abfrage eines Diagrammalgorithmus abbrechen möchten, suchen Sie in der Tabelle query_id aus SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS nach dem entsprechenden query_id und rufen Sie dann cancel_query für dieses query_id auf.