Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Spanner Graph アルゴリズムを実行する

このドキュメントでは、Spanner Graph でアルゴリズムを実行する方法について説明します。

Spanner Graph アルゴリズムクエリの構造

Spanner Graph アルゴリズムクエリの構造は次のとおりです。

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: アルゴリズムのクエリ結果を永続化する方法を定義するオプション。Cloud Storage のオプションと Spanner のオプションをご覧ください。
graph_name: グラフの名前。
match_clause: アルゴリズムの入力要素を定義するオプションの MATCH ステートメント。
call_statement: match_clause 変数を省略し、グラフ全体を操作する場合は、CALL ステートメントを使用します。match_clause 変数が存在し、作業テーブルを操作する場合は、CALL PER() ステートメントを使用します。詳細については、GQL CALL をご覧ください。
algorithm_name: 実行するアルゴリズムの名前。使用可能なアルゴリズムについては、Spanner Graph アルゴリズムをご覧ください。
common_input: すべてのアルゴリズムクエリに共通する名前付き入力パラメータ。詳細については、一般的なアルゴリズム入力パラメータをご覧ください。
algorithm_specific_input: : アルゴリズムの名前付き入力パラメータ。詳細については、Spanner Graph アルゴリズムで定義されている入力パラメータをご覧ください。
algorithm_specific_output: アルゴリズム呼び出しの出力。詳細については、Spanner Graph アルゴリズムで定義されている出力と、CALL ステートメントの YIELD 句をご覧ください。
results: クエリ結果で返す内容を定義します。

クエリは、結果を保持する方法を定義する EXPORT DATA ステートメントと、アルゴリズムクエリの結果を生成する GRAPH 句で構成されています。

最も単純な形式では、グラフ句はグラフを識別し、CALL ステートメントを使用して事前定義された出力を生成するアルゴリズムを呼び出し、RETURN ステートメントを使用してアルゴリズムの出力から何を返すかを指定します。

必要に応じて、グラフ句でサポートされている MATCH ステートメントを使用して、対象の要素を選択できます。この場合は、PER () 句を使用して、MATCH ステートメントによって返されたすべての行をアルゴリズムへの入力としてグループ化します。このアルゴリズムは、選択された一意のノードとエッジのセットで構成される論理サブグラフで動作します。

クエリはデータを返しません。export_option_list 変数は、結果の永続化方法を決定します。

Spanner Graph アルゴリズムクエリの詳細については、このドキュメントの次のセクションをご覧ください。

一般的なアルゴリズムの入力パラメータ
アルゴリズムの出力を処理する
サンプルアルゴリズムクエリを実行する

一般的なアルゴリズムの入力パラメータ

これらの名前付き入力パラメータは、NAME => VALUE, ... の形式で指定します。

名前	値の型	必須	デフォルト値	説明
`node_labels`	`ARRAY`	いいえ	（なし）	`CALL` が使用されている場合にのみサポートされます。アルゴリズムの入力に含めるノードラベルのリスト。指定すると、一致するラベルが少なくとも 1 つあるノードのみが含まれます。
`edge_labels`	`ARRAY`	いいえ	（なし）	`CALL` が使用されている場合にのみサポートされます。アルゴリズムの入力に含めるエッジラベルのリスト。指定すると、一致するラベルが 1 つ以上あるエッジのみが含まれます。
`edge_weight_property`	`STRING`	いいえ	（なし）	重みを含むエッジプロパティの名前。未定義の場合、システムはすべてのエッジにデフォルトの重み 1 を割り当てます。プロパティ値の型は数値にする必要があります。
`machine_category`	`STRING`	いいえ	デフォルト	アルゴリズムの実行に使用するマシンカテゴリ。指定できる値は `default`、`large` です。
`fallback_compute_region`	`STRING`	いいえ	（なし）	ホームリージョンで容量の制約が発生した場合に、アルゴリズムの実行が行われるフォールバックリージョン。Spanner インスタンスのホームリージョンと同じ管轄区域に存在する必要があります（たとえば、ホームリージョンが `us-east1` の場合は `us-central1`）。
`max_idle_time`	`STRING`	いいえ	30 分	アルゴリズムの完了後に、コンピューティングインスタンスを再利用のためにアクティブな状態に維持する期間を指定します。形式は、10 進数のシーケンスで、それぞれに単位接尾辞が付いています（`4m`、`1.5h`、`1h45m` など）。有効な時間単位は、`ns`、`us`（または `µs`）、`ms`、`s`、`m`、`h` です。

アルゴリズムの出力を処理する

アルゴリズムのクエリ結果を検査する前に、結果を永続化する必要があります。export_data_option を使用して、結果を保持する方法を記述します。結果は Cloud Storage に保持することも、クエリの送信元と同じ Spanner インスタンスに保持することもできます。

結果を Cloud Storage に保持する

このオプションを使用するには、Google が管理する Spanner サービスアカウント service-PROJECT_NUMBER@gcp-sa-spanner. にストレージオブジェクト管理者（roles/storage.objectAdmin）ロールが付与されていることを確認します。

結果を Cloud Storage に永続化する場合、次の EXPORT DATA オプションがサポートされています。NAME=VALUE, ... の形式でオプションを指定します。

名前	値の型	必須	説明
`uri`	`STRING`	○	エクスポート先の URI（`gs://bucket/path/file` 形式）。大量のデータをエクスポートする場合は、`uri` でワイルドカードを使用して、データを複数のファイルにエクスポートします。例: `gs://bucket/path/file_*.csv`
`format`	`STRING`	○	エクスポートされるデータの形式。サポートされる値: `CSV`、`PARQUET`、`AVRO`。
`header`	`BOOL`	いいえ	`true` の場合、システムは各データファイルの最初の行の列ヘッダーを出力します。デフォルトは `false` です。CSV にのみ適用されます。
`overwrite`	`BOOL`	いいえ	`true` の場合、システムは同じ URI を持つ既存のファイルを上書きします。それ以外の場合、同じ URI のファイルが存在すると、ステートメントはエラーを返します。デフォルトは `false` です。
`field_delimiter`	`STRING`	いいえ	フィールドを区切る区切り文字。デフォルト: `,`（カンマ）。CSV にのみ適用されます。
`compression`	`STRING`	いいえ	圧縮形式を指定します。圧縮形式を指定しない場合、ファイルは圧縮されません。 `CSV` の場合、サポートされている値は `GZIP` です。 `PARQUET` のサポートされている値は、`SNAPPY`、`GZIP`、`ZSTD` です。 `AVRO` の場合、サポートされている値は `DEFLATE`、`SNAPPY` です。

RETURN 句の列名は、Cloud Storage 出力ファイルの列名を定義します。

1 つまたは複数のファイルにデータをエクスポートする

Spanner Graph クエリは、uri で 1 つのワイルドカード演算子（*）をサポートしています。ワイルドカードはファイル名コンポーネントで使用できますが、バケット名、フォルダ名、ファイル拡張子では使用できません。ワイルドカード演算子を使用すると、Spanner Graph は、結果セットが大きい場合に、指定したパターンに基づいて複数のシャードファイルを作成します。システムは、ワイルドカード演算子を、左側に 0 が埋められた 12 桁の数値（0 から始まるシーケンス番号）に置き換えます。たとえば、URI gs://my-bucket/file-*.csv は、gs://my-bucket/file-000000000000.csv や gs://my-bucket/file-000000000001.csv などのファイルを作成します。

ワイルドカードなしで uri を使用すると、結果は gs://my-bucket/file.csv などの単一のファイルになります。

データ型

データをエクスポートすると、Spanner Graph のデータ型は、形式に応じて次のように変換されます。

CSV

すべてのデータ型は、文字列形式に変換されます。

BOOL 値は true または false に変換されます。
BYTES 値は base64 でエンコードされます。
TIMESTAMP 値は YYYY-MM-DD HH:MM:SS.ffffff UTC としてフォーマットされます。
NULL の値は空の文字列として表示されます。

ネストや繰り返しのあるデータを CSV 形式でエクスポートすることはできません。

Avro

Spanner のデータ型	Avro のデータ型
`BOOL`	`BOOLEAN`
`INT64`	`LONG`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	論理型 `DECIMAL(38,9)` を持つ `BYTES`
`STRING`	`STRING`
`BYTES`	`BYTES`
`TIMESTAMP`	`LONG`（エポックからのマイクロ秒数）
`NULL`	`null`

Parquet

Spanner のデータ型	Parquet のデータ型
`BOOL`	`BOOLEAN`
`INT64`	`INT64`
`FLOAT`	`FLOAT`
`DOUBLE`	`DOUBLE`
`NUMERIC`	`DECIMAL(38,9)`
`STRING`	`STRING`
`BYTES`	`BYTE_ARRAY`
`TIMESTAMP`	`TIMESTAMP_MICROS`
`NULL`	`null`

結果を Spanner に保持する

結果をソース Spanner インスタンスに永続化する場合、次の EXPORT DATA オプションがサポートされます。NAME=VALUE, ... の形式でオプションを指定します。

名前	値の型	必須	説明
`format`	`STRING`	○	エクスポートされるデータの形式。`CLOUD_SPANNER` を指定します。
`table`	`STRING`	○	結果を書き込む宛先 Spanner テーブルの名前。これは、Spanner インスタンス内の任意のテーブルにできます。
`write_mode`	`STRING`	○	使用する書き込みモード。サポートされている値は次のとおりです。 `update_ignore_all`: 宛先テーブルの既存の行を更新します。 `upsert_ignore_all`: 宛先テーブルに新しい行を挿入するか、既存の行を更新します。どちらのモードでも、Spanner は制約違反（更新時のキーの欠落、一意のインデックス違反、外部キー制約違反など）を引き起こすレコードをスキップします。ただし、制約違反以外のエラー（列の型の不一致、NOT NULL 列の値の欠落など）の場合、書き込みは失敗します。

要件

アルゴリズムの結果を Spanner に保持する場合、アルゴリズムクエリは次の条件を満たす必要があります。

宛先テーブルが存在している必要があります。
一致する型の列が存在する必要がある: RETURN 句で指定されたすべての列名が、一致するデータ型で宛先テーブルにすでに存在している必要があります。必要に応じて、エイリアスを使用して宛先テーブルの列名を照合します。例: RETURN node.id AS person_id
すべての主キー列を含める: RETURN 句には、宛先テーブルのすべての主キー列を含める必要があります。

書き込みセマンティクス

結果を Spanner に永続化する操作は、トランザクション処理ではありません。行レベルのアトミック性を提供します。つまり、システムは同じ行のすべての列を正常に書き込むか、まったく書き込まないかのどちらかです。at-least-once セマンティクスに従います。つまり、1 つの行に複数回書き込むことができます。実行中に宛先テーブルから読み取ると、結果が不完全になる可能性があります。

全体的な実行が失敗した場合、システムはすでに commit された変更をロールバックしません。書き込みプロセスは、最初の再試行不可能なエラーで失敗します。書き込みエラーが発生すると、GRAPH_OPERATION_EXECUTION_STATUS の ERROR_MESSAGE に、失敗した行の主キーと、失敗の具体的な理由が表示されます。

システムは、MEDIUM 優先度を使用して、アルゴリズムの結果を Spanner Graph に書き戻します。

サンプルアルゴリズムクエリを実行する

このセクションでは、テストインスタンスで実行できる Spanner Graph アルゴリズムクエリの例を示します。Spanner Graph でサポートされているアルゴリズムの一覧については、Spanner Graph アルゴリズムをご覧ください。

始める前に

Spanner Graph アルゴリズムのクエリ例を実行するには、まず次の操作を完了する必要があります。

Spanner Graph を設定してクエリを実行するに沿って、Spanner Graph を作成します。
必要な権限があることを確認します。
省略可: 出力を Spanner に永続化する場合は、Spanner Graph スキーマを拡張します。

Account テーブルに page_rank という名前の新しい列を追加します。Spanner は、アルゴリズムの結果をこの新しい列に書き込みます。次に、グラフ定義を更新して、page_rank にノードプロパティとしてアクセスできるようにします。

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

ラベルフィルタを使用してグラフ全体でアルゴリズムを実行し、結果を Cloud Storage に保存する

この例では、PageRank ステートメントを実行して、参加している転送に基づいてアカウントをランク付けします。クエリ結果は、CSV 形式で my-bucket-name/my-output.csv として Cloud Storage バケットに保存されます。

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

このクエリが正常に完了すると、Cloud Storage に 2 つの列（id と page_rank）を含む CSV ファイルが表示されます。

`MATCH` で定義されたサブグラフでアルゴリズムを実行し、結果をグラフに保存する

この例では、MATCH パターンを使用して、すべての Account ノードと、金額が 500 未満の Transfer エッジのみを含む論理サブグラフを動的に照合します。この論理サブグラフは、PageRank アルゴリズムへの入力です。Spanner は、アルゴリズムの結果を 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

クエリが正常に完了したら、次のクエリを実行します。

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

次のような結果が表示されます。

id	page_rank
20	0.49
16	0.46
7	0.05

アルゴリズムの実行ステータスを確認する

グラフアルゴリズムクエリが正常に完了すると、ゼロ行と Success ステータスが返されます。入力グラフのサイズと特定のアルゴリズム構成によっては、アルゴリズムの実行が完了するまでに時間がかかることがあります。グラフアルゴリズムクエリの進行状況と実行ステータスは、SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS テーブルで確認できます。このテーブルには、30 日間情報が保持されます。

`GRAPH_OPERATION_EXECUTION_STATUS` 個のスキーマ

列名	タイプ	説明
`QUERY_ID`	`STRING`	グラフアルゴリズムクエリの ID。
`QUERY_TEXT`	`STRING`	クエリステートメントのテキスト。
`START_TIMESTAMP`	`TIMESTAMP`	クエリの実行が開始された時刻。
`LAST_UPDATE_TIMESTAMP`	`TIMESTAMP`	ステータスが最後に更新された時刻。
`PROGRESS`	`FLOAT64`	完了率の推定値。値は `0`～`1` の範囲で、`0` は開始、`1` は完了を意味します。
`STATUS`	`STRING`	現在の実行状態。有効な値は、`PENDING`、`IN_PROGRESS`、`OK`、または `CANCELLED`、`DEADLINE_EXCEEDED`、`INVALID_ARGUMENT`、`FAILED_PRECONDITION`、`RESOURCE_EXHAUSTED`、`UNAVAILABLE`、`UNKNOWN` などのエラーステータスコードです。
`ERROR_MESSAGE`	`STRING`	クエリの実行が失敗した場合のエラーメッセージ。

次のサンプルクエリは、まだ正常に完了していないグラフクエリを一覧表示します。

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;

アルゴリズムの実行をキャンセルする

実行中のグラフアルゴリズムクエリをキャンセルするには、SPANNER_SYS.GRAPH_OPERATION_EXECUTION_STATUS テーブルから query_id を見つけて、その query_id に対して cancel_query を呼び出します。