Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Spanner Graph-Algorithmen ausführen

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

Struktur der Algorithmusabfrage in Spanner Graph

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 Abfrageergebnisse des Algorithmus beibehalten werden. Weitere Informationen finden Sie unter Cloud Storage-Optionen und Spanner-Optionen.
graph_name: Der Name des Graphen.
match_clause: Optionale MATCH-Anweisungen zum Definieren von Algorithmus-Eingabeelementen.
call_statement: Verwenden Sie die CALL-Anweisung, wenn Sie die Variable match_clause weglassen und den gesamten Graphen bearbeiten möchten. Verwenden Sie die Anweisung CALL PER(), wenn die Variable match_clause vorhanden ist und Sie die Arbeitstabelle bearbeiten 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 Graph-Algorithmen.
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 den Eingabeparametern, die in Spanner Graph-Algorithmen definiert sind.
algorithm_specific_output: Die Ausgabe des Algorithmusaufrufs. Weitere Informationen finden Sie in den Ausgaben, die unter Spanner Graph-Algorithmen definiert sind, und in der YIELD-Klausel in der CALL-Anweisung.
results: Definiert, was in den Abfrageergebnissen zurückgegeben werden soll.

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

In ihrer einfachsten Form identifiziert die Graph-Klausel den Graphen, verwendet eine CALL-Anweisung, um einen Algorithmus aufzurufen, der eine vordefinierte Ausgabe liefert, und verwendet dann eine RETURN-Anweisung, um anzugeben, was aus der Ausgabe des Algorithmus zurückgegeben werden soll.

Optional kann die Graph-Klausel unterstützte MATCH-Anweisungen verwenden, um die gewünschten Elemente auszuwählen. Verwenden Sie in diesem Fall eine PER ()-Klausel, um alle Zeilen, die von der MATCH-Anweisung zurückgegeben werden, als Eingabe für den Algorithmus zu gruppieren. Der Algorithmus arbeitet mit einem logischen Untergraphen, der aus der eindeutigen Gruppe von ausgewählten Knoten und Kanten besteht.

Die Abfrage gibt keine Daten zurück. Die Variable export_option_list bestimmt, wie Ergebnisse gespeichert werden.

Weitere Informationen zu Abfragen mit Spanner Graph-Algorithmen finden Sie in den folgenden Abschnitten dieses Dokuments:

Häufig verwendete 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. Wenn angegeben, werden nur Knoten mit mindestens einem übereinstimmenden Label einbezogen.
`edge_labels`	`ARRAY`	Nein	(keine)	Wird nur unterstützt, wenn `CALL` verwendet wird. Eine Liste der Kantenlabels, die in die Algorithmuseingabe aufgenommen werden sollen. Wenn angegeben, werden nur Kanten mit mindestens einem übereinstimmenden Label berücksichtigt.
`edge_weight_property`	`STRING`	Nein	(keine)	Der Name des Kantenattributs, das die Gewichtungen enthält. Wenn nicht definiert, weist das System allen Kanten eine Standardgewichtung von 1 zu. Der Typ des Attributwerts 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`
`fallback_compute_region`	`STRING`	Nein	(keine)	Die Fallback-Region, in der die Algorithmusausführung stattfindet, wenn in der Heimatregion Kapazitätsengpässe auftreten. Muss sich in derselben Gerichtsbarkeit wie die Heimatregion der Spanner-Instanz befinden (z. B. `us-central1`, wenn die Heimatregion `us-east1` ist).
`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 mit jeweils einem Suffix für die Einheit, z. B. `4m`, `1.5h` oder `1h45m`. Gültige Zeiteinheiten sind `ns`, `us` (oder `µs`), `ms`, `s`, `m`, `h`.

Algorithmusausgabe verarbeiten

Sie müssen die Abfrageergebnisse des Algorithmus persistent speichern, bevor Sie sie prüfen können. Verwenden Sie export_data_option, um zu beschreiben, wie die Ergebnisse persistent gespeichert werden. Sie können die Ergebnisse in Cloud Storage oder in derselben Spanner-Instanz speichern, aus der die Abfrage 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. die Rolle Storage-Objekt-Administrator (roles/storage.objectAdmin) zugewiesen sein.

Die folgenden EXPORT DATA-Optionen werden beim Speichern von Ergebnissen in Cloud Storage unterstützt. 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 `gs://bucket/path/file`-Format. Wenn Sie eine große Datenmenge exportieren, verwenden Sie einen Platzhalter in `uri`, um die 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	Wenn `true`, gibt das System Spaltenüberschriften für die erste Zeile jeder Datendatei aus. 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` wird der unterstützte Wert `GZIP` unterstützt. Für `PARQUET` werden folgende Werte unterstützt: `SNAPPY`, `GZIP`, `ZSTD`. Für `AVRO` sind die folgenden Werte zulässig: `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 enthalten sein. Wenn Sie den Platzhalteroperator verwenden, wird Spanner Graph angewiesen, mehrere fragmentierte Dateien basierend auf dem von Ihnen angegebenen Muster zu erstellen, wenn die Ergebnismenge groß ist. Das System ersetzt den Platzhalteroperator durch eine Zahl, die bei null beginnt und links mit Nullen auf 12 Ziffern aufgefüllt wird. Mit dem 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 einen uri ohne Platzhalter verwenden, ist das Ergebnis eine einzelne Datei, z. B. gs://my-bucket/file.csv.

Datentypen

Wenn Sie Daten exportieren, werden die Spanner Graph-Datentypen 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 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 logischem 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 Cloud Spanner-Zieltabelle, in die Ergebnisse geschrieben werden sollen. Dies 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 Datensätze, die eine Einschränkungsverletzung verursachen würden (z. B. fehlende Schlüssel bei einer Aktualisierung, Verletzung eines eindeutigen Index, Verletzung einer Fremdschlüsseleinschränkung), von Spanner übersprungen. Der Schreibvorgang schlägt jedoch bei Fehlern fehl, die nicht auf eine Verletzung von Einschränkungen zurückzuführen sind, z. B. bei einem Spaltentypkonflikt oder 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 bei Bedarf Aliase, um die Spaltennamen der Zieltabelle abzugleichen. Beispiel: RETURN node.id AS person_id.
Alle Primärschlüsselspalten einbeziehen: Die RETURN-Klausel muss alle Primärschlüsselspalten der Zieltabelle enthalten.

Semantik schreiben

Das Speichern von Ergebnissen in Spanner ist ein nicht transaktionaler Vorgang. Er bietet Atomarität auf Zeilenebene. Das bedeutet, dass das System entweder alle Spalten aus derselben Zeile erfolgreich schreibt oder keine davon. Es folgt der „Mindestens einmal“-Semantik. 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 übernommene Änderungen nicht rückgängig gemacht. Der Schreibvorgang schlägt beim ersten nicht wiederholbaren Fehler fehl. Wenn ein Schreibfehler auftritt, gibt der ERROR_MESSAGE in GRAPH_OPERATION_EXECUTION_STATUS den Primärschlüssel der Zeile an, die fehlgeschlagen ist, sowie den genauen Grund für den Fehler.

Das System schreibt die Algorithmus-Ergebnisse mit der MEDIUM-Priorität zurück in Spanner Graph.

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 ausführen:

Folgen Sie der Anleitung unter 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 die Algorithmus-Ergebnisse in diese neue Spalte. Aktualisieren Sie dann die Diagrammdefinition, damit Sie als Knotenattribut auf page_rank 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 Labelfilter ausführen und Ergebnisse in Cloud Storage speichern

In diesem Beispiel wird die Anweisung PageRank ausgeführt, um die Konten anhand der Überweisungen, an denen sie beteiligt sind, in eine Rangfolge zu bringen. Die Abfrageergebnisse werden im CSV-Format als my-bucket-name/my-output.csv in einem Cloud Storage-Bucket 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

In Cloud Storage sollte eine CSV-Datei mit zwei Spalten (id und page_rank) angezeigt werden, wenn diese Abfrage erfolgreich abgeschlossen wurde.

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

In diesem Beispiel wird das Muster MATCH verwendet, um dynamisch einen logischen Untergraphen 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 Graphalgorithmus-Abfrage erfolgreich abgeschlossen wurde, gibt sie null Zeilen und den Status Success zurück. Je nach Größe des Eingabediagramms und den spezifischen Algorithmuskonfigurationen kann die Ausführung des Algorithmus einige Zeit dauern. Sie können den Fortschritt und den Ausführungsstatus einer Graphalgorithmus-Abfrage 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 Graph-Algorithmus-Abfrage.
`QUERY_TEXT`	`STRING`	Der Text der Abfrageanweisung.
`START_TIMESTAMP`	`TIMESTAMP`	Der Zeitpunkt, zu dem die Ausführung der Abfrage begonnen hat.
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	Der Zeitpunkt, zu dem der Status zuletzt aktualisiert wurde.
`PROGRESS`	`FLOAT64`	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` oder ein Fehlerstatuscode wie `CANCELLED`, `DEADLINE_EXCEEDED`, `INVALID_ARGUMENT`, `FAILED_PRECONDITION`, `RESOURCE_EXHAUSTED`, `UNAVAILABLE` oder `UNKNOWN`.
`ERROR_MESSAGE`	`STRING`	Fehlermeldung, wenn die Abfrageausführung fehlgeschlagen ist.

In der folgenden Beispielabfrage werden Graphabfragen aufgelistet, 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 SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS nach der query_id und rufen Sie dann cancel_query für diese query_id auf.