コンテキスト セットは、QueryData などのツールが Spanner データベースのプロパティ グラフに対して正確な Graph Query Language(GQL)クエリを生成するのに役立つガイダンスのコレクションです。QueryData は、データベースからプロパティ グラフ スキーマを直接読み取ります。コンテキスト セットは、スキーマではキャプチャされない情報(ビジネス用語の意味、ユーザーがよく尋ねる質問に対する検証済みのクエリ、ユーザーがグラフに保存されている値を参照する方法など)を追加します。コンテキスト セットでグラフスキーマを再定義する必要はありません。
QueryData でサポートされているデータベースは次のとおりです。
- AlloyDB for PostgreSQL
- Cloud SQL for MySQL
- Cloud SQL for PostgreSQL
- Spanner(Spanner Graph を含む)
- MongoDB 互換の Firestore
Spanner Graph ではなくリレーショナル Spanner テーブルでコンテキスト セットを使用するには、Spanner のコンテキスト セットの概要をご覧ください。
コンテキストは、クエリ テンプレート、クエリ ファセット、値検索の 3 種類のオブジェクトを含む JSON ファイルで定義します。このファイルは、コンテキスト エンジニアリング エージェントを使用して作成し、Spanner Studio で作成したコンテキスト セットにアップロードできます。QueryData は、QueryData リクエストが agent_context_reference.context_set_id フィールドで参照するときにコンテキスト セットを使用します。
コンテキスト セットは、us-central1、us-east1、europe-west4、asia-southeast1 の各リージョンで作成できます。コンテキスト セットのリージョンは、QueryData リクエストで使用するロケーション(locations/global など)と一致する必要はありません。
このドキュメントの例では、FinGraph プロパティ グラフ スキーマ(Owns エッジと Transfers エッジで接続された Person ノードと Account ノード)を使用します。Spanner データベースに FinGraph プロパティ グラフを設定してサンプルデータを挿入するには、Spanner Graph を設定してクエリを実行するをご覧ください。
QueryData がコンテキスト セットを使用する方法
コンテキスト セットには、3 種類のコンテキストを含めることができます。各タイプは異なる問題を解決します。QueryData は、これらを個別に使用することも、組み合わせて使用することもできます。
| コンテキストの種類 | 設定する項目 | 使用する場面 | QueryData での使用方法 | FinGraph の例 |
|---|---|---|---|---|
| クエリ テンプレート | 1 種類の質問に対する完全で検証済みの GQL クエリ。変更される値には ? プレースホルダが使用されます。 |
ユーザーが異なるパラメータ値で同じ質問を繰り返し行う場合。特に、クエリの生成が複雑な場合(マルチホップ パス パターンなど)。 | 完全一致の場合は sql クエリを直接再利用し、質問がテンプレートと一致する場合はパラメータを parameterized_sql に置き換えます。 |
「口座 7 から送金されたお金が 60 日以内に戻ってきたことはありますか?」 |
| クエリ ファセット | ビジネス用語または条件を定義する、MATCH パターンや WHERE 条件などの再利用可能な GQL 句。 |
1 つの再利用可能な条件またはパターンが、さまざまな質問に現れる。 | 新しい GQL クエリを生成するときに、定義された GQL 句を組み込みます。 | リスクの高い送金とは、ブロック中の口座への 200 以上の送金です。 |
| 価値の検索 | ユーザーの質問の値フレーズに一致する、保存されたプロパティ値を見つけるクエリ。 | ユーザーが、グラフに保存されている名前やスペルとは異なる名前やスペルで値を参照している。 | GQL クエリを生成する前に、値フレーズを使用してルックアップ クエリを実行し、解決された保存値とプロパティでフィルタします。 | 「雨の日」は、Account.nick_name の Rainy Day Fund を指します。 |
次の図は、QueryData がコンテキスト セットを使用して質問を処理する方法を示しています。

図に示すように、QueryData は質問を受け取ると、次の順序でコンテキスト セットを使用します。
- 関連するコンテキストを取得する。QueryData は、質問に最も類似したテンプレート、ファセット、値検索を取得します。
- 値検索を実行する。QueryData は、質問内の各値フレーズ(名前やニックネームなど)に対して値検索を実行し、一致する保存済みの値を見つけます。値の検索は、数値、日付、時刻、通貨金額に対しては実行されません。
- クエリ テンプレートと照合する。質問がテンプレートと一致する場合、QueryData はテンプレートの検証済み GQL クエリを使用します。
nl_queryと完全一致する場合、QueryData はsqlクエリを直接実行します。パラメータ化されたテンプレートと一致する場合、QueryData はparameterized_sqlの?プレースホルダを質問の値に置き換え、結果のクエリを実行します。 - 新しい GQL クエリを生成する。それ以外の場合、QueryData はグラフスキーマから新しい GQL クエリを生成します。関連するファセットをビジネスルールとして適用し、関連するテンプレートを例として使用し、値検索で見つかった保存済みの値を使用します。
コンテキスト セットのファイル形式
コンテキスト セット ファイルは、以降のセクションで説明するコンテキスト アイテムの 3 つの配列フィールド(templates、facets、value_searches)を含む JSON オブジェクトです。空のコンテキスト セット ファイルの構造は次のとおりです。
{
"templates": [],
"facets": [],
"value_searches": []
}
これらのフィールドを自由に組み合わせて使用し、使用しないフィールドは省略します。Spanner Graph の出発点として、特定のクエリ構造を必要とするマルチホップまたは時間制限のある質問ごとにテンプレートを作成し、複数の質問にわたって出現するビジネス用語ごとにファセットを作成し、ユーザーが名前(名前、ニックネーム、国など)で参照するテキスト プロパティごとに値検索を作成することをおすすめします。
コンテキスト セット ファイルを編集する際は、次のルールに注意してください。
- 1 行のクエリ文字列。
sql、parameterized_sql、sql_snippet、parameterized_sql_snippet、query、nl_queryの値は JSON 文字列であるため、各クエリは 1 行に記述されます。クエリ内では、文字列リテラルに単一引用符(')を使用するか、二重引用符を\"としてエスケープします。 sqlフィールドの GQL。一部のフィールド名にsqlが含まれているのは、QueryData がサポートするすべてのデータベースで形式が共有されているためです。Spanner Graph の場合は、sql、parameterized_sql、sql_snippet、parameterized_sql_snippetに GQL クエリまたは句を指定します。- 正確なフィールド名。フィールド名は、このドキュメントの名前と完全に一致している必要があります。認識されない名前のフィールドは、エラーなしで無視されます。
クエリ テンプレート
テンプレートは、ユーザーが尋ねる質問と、その質問に回答する検証済みの GQL クエリをペアにします。ユーザーが繰り返し行う質問には、テンプレートを使用します。特に、クエリの生成が複雑な場合(時間条件付きのマルチホップ パス パターンなど)は、テンプレートを使用します。
テンプレートの例
コンテキスト セット ファイルに次のテンプレートがあると、QueryData は「口座 7 から送金されたお金が 60 日以内に戻ってきたか」や「口座 16 から送金されたお金が 30 日以内に戻ってきたか」など、同じ構造を共有する質問に回答できます。
{
"templates": [
{
"nl_query": "Did any money sent from account 7 come back to it within 60 days?",
"sql": "GRAPH FinGraph MATCH TRAIL (src:Account {id: 7})-[sent:Transfers]->(:Account)-[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src) WHERE returned.create_time > sent.create_time AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= 60 RETURN sent.amount AS amount_sent, returned.amount AS amount_returned, TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return",
"intent": "Find transfer loops of two to four transfers that start and end at account 7, where the last transfer happens within 60 days after the first transfer.",
"manifest": "Find transfer loops of two to four transfers that start and end at a given account, where the last transfer happens within a given number of days after the first transfer.",
"parameterized": {
"parameterized_intent": "Find transfer loops of two to four transfers that start and end at account ?, where the last transfer happens within ? days after the first transfer.",
"parameterized_sql": "GRAPH FinGraph MATCH TRAIL (src:Account {id: ?})-[sent:Transfers]->(:Account)-[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src) WHERE returned.create_time > sent.create_time AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= ? RETURN sent.amount AS amount_sent, returned.amount AS amount_returned, TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return"
}
}
]
}
ユーザーが「口座 7 から送金されたお金が 60 日以内に戻ってきたことはありますか?」と尋ねた場合、QueryData は、質問をテンプレートに一致させ(または、アカウント 16 や 30 日などの異なるパラメータ値を持つ質問の場合、parameterized_sql 内の 2 つの ? プレースホルダを置き換え)、次の GQL クエリを実行します。
GRAPH FinGraph
MATCH TRAIL
(src:Account {id: 7})-[sent:Transfers]->(:Account)
-[:Transfers]->{0,2}(:Account)-[returned:Transfers]->(src)
WHERE returned.create_time > sent.create_time
AND TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) <= 60
RETURN
sent.amount AS amount_sent,
returned.amount AS amount_returned,
TIMESTAMP_DIFF(returned.create_time, sent.create_time, DAY) AS days_to_return
FinGraph サンプルデータを使用すると、このクエリは次のような結果を返します。
+-------------+-----------------+----------------+
| amount_sent | amount_returned | days_to_return |
+-------------+-----------------+----------------+
| 300 | 500 | 36 |
+-------------+-----------------+----------------+
テンプレート フィールド
テンプレート オブジェクトには次のフィールドが含まれます。
| フィールド | 要件 | 説明 |
|---|---|---|
nl_query |
必須 | ユーザーが質問する形式で表現された質問の例(例: 「口座 7 から送金されたお金が 60 日以内に戻ってきましたか?」)。 |
sql |
必須 | nl_query に回答する完全な GQL クエリ。クエリを GRAPH で始め、その後に QueryData リクエストの graph_ids フィールドで指定したプロパティ グラフの名前(GRAPH FinGraph など)を続けます。 |
intent |
必須 | sql が返す結果の正確な説明。ユーザーの質問では条件が明示されていないことがよくありますが、intent は条件を明示します(たとえば、お金が「戻ってきた」ことを指定すると、「アカウント 7 で開始して終了する 2 ~ 4 回の送金のループで、最後の送金が最初の送金から 60 日以内に行われる」ことを意味します)。 |
manifest |
必須 | intent の一般化されたバージョン。テンプレートが回答する質問の種類を、具体的な値なしで記述します(たとえば、「アカウント 7」は「特定のアカウント」になり、「60 日」は「特定の日数」になります)。QueryData は、質問をマニフェストと比較してテンプレートを取得します。 |
parameterized.parameterized_intent |
省略可 | intent。各特定の値は ? プレースホルダに置き換えられます。 |
parameterized.parameterized_sql |
省略可 | sql クエリ。各特定の値は、parameterized_intent と同じ順序で ? プレースホルダに置き換えられます。質問がテンプレートと一致すると、QueryData はプレースホルダを質問の値に置き換えて、このクエリを実行します。 |
コンテキスト セット ファイルを手動で作成する場合は、4 つの必須フィールドをすべて入力します。いずれかが空の場合、アップロードは INVALID_ARGUMENT エラーで失敗します。コンテキスト エンジニアリング エージェントは、nl_query と sql のペアから intent、manifest、parameterized を生成します。生成された値を確認し、固定しておくべき値がプレースホルダに置き換えられている場合や、変更すべき値が置き換えられていない場合は、編集します。
クエリ ファセット
ファセットは、ビジネス用語または条件を定義する MATCH パターンや WHERE 条件などの再利用可能な GQL 句です。テンプレートとは異なり、ファセットは完全なクエリではなく部分的なクエリであるため、GRAPH 句で始まらず、1 つの質問に関連付けられていません。QueryData は、新しいクエリを生成するときに、質問に関連するファセットを適用します。
ファセットの例
次の facets 構成では、最初のファセットはブロックされたアカウントを含む送金のパターンをキャプチャし、2 番目のファセットは、ブロックされたアカウントへの 200 以上の送金を高リスク送金として定義します。
{
"facets": [
{
"sql_snippet": "MATCH (account:Account)-[transfer:Transfers]-(:Account {is_blocked: true})",
"intent": "transfers involving a blocked account, in either direction"
},
{
"sql_snippet": "MATCH (account:Account)-[transfer:Transfers]->(blocked_account:Account {is_blocked: true}) WHERE transfer.amount >= 200",
"intent": "high-risk transfers, which are transfers of 200 or more to a blocked account",
"manifest": "high-risk transfers, which are transfers of a given amount or more to a blocked account",
"parameterized": {
"parameterized_intent": "high-risk transfers, which are transfers of ? or more to a blocked account",
"parameterized_sql_snippet": "MATCH (account:Account)-[transfer:Transfers]->(blocked_account:Account {is_blocked: true}) WHERE transfer.amount >= ?"
}
}
]
}
ユーザーが「アレックスは高リスクの送金を何回行いましたか?」と質問した場合、この質問に一致するテンプレートはありません。QueryData は新しい GQL クエリを生成し、2 つ目のファセットを組み込んで、ブロックされたアカウントへの 200 以上の送金をカウントします。
GRAPH `FinGraph`
MATCH (p:`Person` {`name`: "Alex"})-[:`Owns`]->(src:`Account`)
-[t:`Transfers`]->(dst:`Account` {`is_blocked`: true})
FILTER t.`amount` >= 200.0
RETURN COUNT(*) AS high_risk_transfer_count
FinGraph サンプルデータを使用して、このクエリはアカウント 7 からブロックされたアカウント 16 への 300 転送をカウントし、次のような結果を返します。
+--------------------------+
| high_risk_transfer_count |
+--------------------------+
| 1 |
+--------------------------+
ファセット フィールド
ファセット オブジェクトはクエリ テンプレートと同じ構造を使用しますが、次の点が異なります。
nl_queryフィールドがない。ファセットにはnl_queryフィールドがありません。ファセットは、単一の質問ではなく、多くの質問に表示される条件を記述するためです。sqlではなくsql_snippet(必須)。GQL 句(MATCHパターンやWHERE条件など)。曖昧さを避けるため、(account:Account)などの明示的なノードラベル、エッジラベル、変数名を使用して、QueryData が GQL 句をクエリの残りの部分と結合できるようにします。intent(必須)、manifest(省略可)、parameterized(省略可)。ビジネス用語または条件をテンプレート フィールドと同じ方法で定義します。ただし、QueryData は質問をintentと照合するため、説明的なものにし、manifestは省略可能です。parameterizedにはparameterized_intentとparameterized_sql_snippetが含まれます。
値の検索クエリ
値検索はクエリであり、ルックアップ テーブルではありません。QueryData は、GQL クエリを生成する前に、質問内の各値フレーズ(名前、ニックネーム、国などのテキスト値)に対して値検索を 1 回実行し、フレーズを $value に置き換えます。次に、クエリが返す最も近い保存値と、それらの値の取得元のプロパティを使用して、GQL クエリを記述します。値の検索は、数値、日付、時刻、通貨金額に対しては実行されません。
値の検索の例
たとえば、FinGraph では、アカウント 20 のニックネームは Rainy Day Fund で、Person.country プロパティにはアンダースコア付きの Czech_Republic が格納されます。次の値検索では、「rainy day」などの値フレーズを Account.nick_name の Rainy Day Fund にマッピングし、「Czech Republic」を Person.country の Czech_Republic にマッピングします。
{
"value_searches": [
{
"query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (a:Account) WHERE STRPOS(LOWER(a.nick_name), LOWER($value)) > 0 RETURN DISTINCT a.nick_name AS value, 'FinGraph.Account.nick_name' AS columns, 'Account nickname' AS concept_type, 1 - LENGTH($value) / LENGTH(a.nick_name) AS distance, JSON '{}' AS context)",
"concept_type": "Account nickname",
"description": "Case-insensitive partial match on account nicknames. Distance is 0 for an exact match and grows as the phrase covers less of the nickname."
},
{
"query": "SELECT value, columns, concept_type, distance, context FROM GRAPH_TABLE(FinGraph MATCH (p:Person) WHERE LOWER(REPLACE(p.country, '_', ' ')) = LOWER(REPLACE($value, '_', ' ')) RETURN DISTINCT p.country AS value, 'FinGraph.Person.country' AS columns, 'Person country' AS concept_type, 0 AS distance, JSON '{}' AS context)",
"concept_type": "Person country",
"description": "Match for country names on Person nodes that ignores case and treats underscores as spaces"
}
]
}
読みやすくするためにフォーマットされた Account nickname クエリは次のとおりです。
SELECT value, columns, concept_type, distance, context
FROM GRAPH_TABLE(
FinGraph
MATCH (a:Account)
WHERE STRPOS(LOWER(a.nick_name), LOWER($value)) > 0
RETURN DISTINCT
a.nick_name AS value,
'FinGraph.Account.nick_name' AS columns,
'Account nickname' AS concept_type,
1 - LENGTH($value) / LENGTH(a.nick_name) AS distance,
JSON '{}' AS context
)
ユーザーが「緊急時用口座の所有者は誰ですか?」と尋ねると、QueryData は、$value を 'rainy day' に設定して値検索を実行します。Account nickname 検索では、保存されているニックネームの長さに対するフレーズの長さから distance が計算されます(「fund」のような広範なフレーズは Vacation Fund と約 0.69、Rainy Day Fund と約 0.71 で一致し、「rainy day fund」のような完全一致は 0 の距離になります)。次のような結果が返されます。
+----------------+----------------------------+------------------+--------------------+---------+
| value | columns | concept_type | distance | context |
+----------------+----------------------------+------------------+--------------------+---------+
| Rainy Day Fund | FinGraph.Account.nick_name | Account nickname | 0.3571428571428571 | {} |
+----------------+----------------------------+------------------+--------------------+---------+
QueryData は、{nick_name: 'rainy day'} ではなく {nick_name: 'Rainy Day Fund'} でフィルタする GQL クエリを生成します。
GRAPH `FinGraph`
MATCH (p:`Person`)-[:`Owns`]->(a:`Account` {`nick_name`: 'Rainy Day Fund'})
RETURN DISTINCT SAFE_TO_JSON(p) AS person
FinGraph サンプルデータを使用すると、このクエリは Dana の Person ノードを JSON 形式で返します。
{
"element_definition_name": "Person",
"identifier": "kQKRBA==",
"kind": "node",
"labels": ["Person"],
"properties": {
"birthday": "1980-10-31T08:00:00Z",
"city": "Moravia",
"country": "Czech_Republic",
"id": 2,
"name": "Dana"
}
}
値検索フィールドと必須の SELECT 列
値検索オブジェクトには次のフィールドが含まれます。
| フィールド | 要件 | 説明 |
|---|---|---|
query |
必須 | 値フレーズに一致する保存された値を見つける GoogleSQL クエリ。フレーズが入る場所に $value を使用します。QueryData は $value を引用符で囲まれた文字列リテラルとしてフレーズに置き換えるため、$value を引用符で囲まないでください。$value は複数回使用できます。ノードまたはエッジラベルに一致し、プロパティを $value と比較して、次の表の 5 つの列を返す GRAPH_TABLE 演算子に対する SELECT ステートメントとしてクエリを記述します。 |
concept_type |
必須 | 検索で見つかった値の種類を示すラベル(Account nickname、Person country など)。 |
description |
省略可 | 検索で値がどのように照合されるかについての説明。 |
すべての値検索 query は、次の 5 つの列をこの順序で返す必要があります。
| 出力列 | 説明 | FinGraph の例 |
|---|---|---|
value |
一致したプロパティ値。データベースに保存されているとおりに表示されます。 | a.nick_name AS value('Rainy Day Fund') |
columns |
プロパティの場所(GRAPH_NAME.LABEL.PROPERTY 形式)。QueryData は、この値を値の場所としてモデルに渡すため、一貫した形式を使用してください。 |
'FinGraph.Account.nick_name' AS columns |
concept_type |
値の種類のラベル。値検索の concept_type フィールドと同じ文字列を使用します。フィールドは検索にラベルを付け、列は各一致にラベルを付けます。 |
'Account nickname' AS concept_type |
distance |
保存された値がフレーズからどれだけ離れているかを、定義したスケールで表します。0 は完全一致です。慣例として、0~1 の値を使用します。QueryData は、すべての値検索の候補を distance で並べ替え、最も近い 10 個を保持します。しきい値は適用されないため、外側の SELECT ステートメントに WHERE distance < 1.0 を追加するなどして、クエリ自体で一致度の低いものを除外します。 |
1 - LENGTH($value) / LENGTH(a.nick_name) AS distance |
context |
JSON 値。QueryData はこの列を使用しませんが、すべての値検索で同じ型の列が存在する必要があります。JSON '{}' を返します。 |
JSON '{}' AS context |
QueryData が値検索を実行する方法
QueryData は値検索を 1 つずつ実行するわけではありません。質問内の値フレーズごとに、すべての値検索でフレーズを $value に置き換え、各クエリに ORDER BY distance LIMIT 10 を追加し、クエリを UNION ALL と結合して、結果を 1 つの GoogleSQL ステートメントとして実行し、最も近い 10 件の一致を保持します。結合クエリは、値検索がスタンドアロンの GQL ステートメントではなく、GRAPH_TABLE ではなく SELECT ステートメントとして記述される理由です。GRAPH_TABLE は GQL MATCH パターンをテーブルとして実行し、UNION ALL と共有 ORDER BY distance は SQL コンストラクトです。
この実行モデルは、作成するクエリに次のような影響を及ぼします。
- 外側の
ORDER BYまたはLIMITがない。外側のSELECTステートメントにORDER BYまたはLIMITを追加しないでください。QueryData がそれらを追加し、句が重複するとステートメントが失敗します。 - 互換性のある列の型。ファイル内のすべての値検索は、同じ 5 つの列を同じ順序で、互換性のある型で返す必要があります。たとえば、一部の
'{}'ではなく、すべてのcontextに対してJSON '{}'を返します。 - 必須の
$valueプレースホルダ。クエリには$valueが少なくとも 1 回含まれている必要があります。含まれていない場合、アップロードは失敗します。 - テキスト値のみ。値検索はテキスト値に対してのみ実行されます。QueryData は、数値、日付、時刻、通貨金額に対しては実行しません。
制限事項
Spanner Graph のコンテキスト セットには次の制限があります。
- データベースのコンテキスト セットは、クエリ テンプレート、クエリ ファセット、値検索のみをサポートします。
- データベースのコンテキスト セットは、Conversational Analytics API の
QueryDataエンドポイントでのみ使用されます。