脈絡資料集內含一系列指引,可協助 QueryData 等工具,為 Spanner 資料庫中的屬性圖譜生成準確的 Graph Query Language (GQL) 查詢。QueryData 會直接從資料庫讀取屬性圖譜結構定義。情境組合會加入結構定義未擷取的內容:業務術語的含義、使用者常問問題的已驗證查詢,以及使用者如何參照圖表中儲存的值。您不需要在情境集中重新定義圖表結構定義。
QueryData 支援下列資料庫:
- AlloyDB for PostgreSQL
- MySQL 適用的 Cloud SQL
- PostgreSQL 適用的 Cloud SQL
- Spanner (包括 Spanner Graph)
- 與 MongoDB 相容的 Firestore
如要搭配使用情境組合與關聯式 Spanner 資料表 (而非 Spanner Graph),請參閱「Spanner 情境組合總覽」。
您可以在 JSON 檔案中定義情境,其中包含三種物件:查詢範本、查詢 facet 和值搜尋。您可以透過內容比對引擎代理編寫這個檔案,然後上傳到在 Spanner Studio 建立的內容比對資料集。當 QueryData 要求在 agent_context_reference.context_set_id 欄位中參照脈絡資料集時,QueryData 就會使用該資料集。
您可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 區域建立情境集。情境集的區域不一定要與 QueryData 要求中使用的位置 (例如 locations/global) 相符。
本文件中的範例使用 FinGraph 屬性圖表結構定義 (Person 和 Account 節點由 Owns 和 Transfers 邊緣連結)。如要在 Spanner 資料庫中設定 FinGraph 屬性圖,並插入範例資料,請參閱「設定及查詢 Spanner Graph」。
QueryData 如何使用脈絡資料集
情境集可包含三種情境。每種類型都能解決不同問題,QueryData 可以單獨使用或搭配使用:
| 結構定義類型 | 您提供的資訊 | 適用情況 | QueryData 的使用方式 | FinGraph 範例 |
|---|---|---|---|---|
| 查詢範本 | 針對某種問題類型,提供完整且經過驗證的 GQL 查詢,並使用 ? 預留位置代表會變動的值。 |
使用者會以不同的參數值重複詢問相同的問題,尤其是當查詢難以生成時 (例如多躍點路徑模式)。 | 直接重複使用 sql 查詢來尋找完全比對的項目,或在問題與範本相符時將參數代入 parameterized_sql。 |
「從帳戶 7 匯出的款項是否在 60 天內退回?」 |
| 查詢 facet | 可重複使用的 GQL 子句,例如 MATCH 模式或 WHERE 條件,用於定義業務條款或條件。 |
一個可重複使用的條件或模式會出現在許多不同的問題中。 | 生成新的 GQL 查詢時,納入定義的 GQL 子句。 | 高風險轉帳是指轉帳金額達 200以上,且收款帳戶已遭封鎖。 |
| 搜尋值 | 這項查詢會找出與使用者問題中的值詞組相符的儲存屬性值。 | 使用者參照值時,使用的名稱或拼寫方式與圖表中儲存的方式不同。 | 在產生 GQL 查詢前,使用值詞組執行查詢,然後根據解析的儲存值和屬性進行篩選。 | 「雨天」是指Account.nick_name的Rainy Day Fund。 |
下圖說明 QueryData 如何使用脈絡資料集處理問題:

如圖所示,QueryData 收到問題時,會按照下列順序使用脈絡資料集:
- 擷取相關背景資訊。QueryData 會擷取與問題最相似的範本、facet 和值搜尋。
- 執行價值搜尋。針對問題中的每個值詞組 (例如名稱或暱稱),QueryData 會執行值搜尋,找出相符的儲存值。值搜尋不適用於數字、日期、時間或貨幣金額。
- 比對查詢範本。如果問題與範本相符,QueryData 會使用範本中經過驗證的 GQL 查詢。如果與
nl_query完全比對,QueryData 會直接執行sql查詢。如果與參數化範本相符,QueryData 會將parameterized_sql中的?預留位置替換為問題中的值,並執行產生的查詢。 - 生成新的 GQL 查詢。否則,QueryData 會根據圖表結構定義生成新的 GQL 查詢。系統會將相關 facet 套用為業務規則、使用相關範本做為範例,並使用值搜尋找到的儲存值。
脈絡資料集檔案格式
情境集檔案是 JSON 物件,包含三個陣列欄位 (templates、facets 和 value_searches),用於描述下列各節的情境項目。空白的內容集檔案結構如下:
{
"templates": [],
"facets": [],
"value_searches": []
}
您可以任意組合這些欄位,並省略不使用的欄位。如要開始使用 Spanner Graph,建議您為每個需要特定查詢結構的多躍點或時間限制問題建立範本、為出現在多個問題中的每個業務術語建立一個面向,並為使用者依名稱參照的每個文字屬性 (例如名稱、暱稱或國家/地區) 建立值搜尋。
編輯情境組合檔案時,請注意下列規則:
- 單行查詢字串。
sql、parameterized_sql、sql_snippet、parameterized_sql_snippet、query和nl_query的值是 JSON 字串,因此每個查詢都寫在同一行。在查詢中,請使用單引號 (') 表示字串常值,或將雙引號逸出為\"。 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 中的兩個 ? 預留位置),並執行下列 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 開始和結束的兩到四次轉帳循環,其中最後一次轉帳發生在第一次轉帳後的 60 天內」)。 |
manifest |
必填 | intent 的一般化版本,說明範本回答的問題類型,不含特定值 (例如「帳戶 7」變成「指定帳戶」,「60 天」變成「指定天數」)。QueryData 會比較問題與資訊清單,藉此擷取範本。 |
parameterized.parameterized_intent |
選用 | intent,每個特定值都會替換為 ? 預留位置。 |
parameterized.parameterized_sql |
選用 | sql 查詢,每個特定值都會以 ? 預留位置取代,順序與 parameterized_intent 相同。當問題與範本相符時,QueryData 會將預留位置替換為問題中的值,並執行這項查詢。 |
如果您手動編寫情境集檔案,請填寫所有四個必填欄位;如果其中任何一個欄位留空,上傳作業會失敗,並顯示 INVALID_ARGUMENT 錯誤。脈絡工程代理會根據 nl_query 和 sql 配對,生成 intent、manifest 和 parameterized。查看產生的值,如果應保持固定的值被預留位置取代,或應變動的值未被取代,請加以編輯。
查詢 facet
Facet 是可重複使用的 GQL 子句,例如 MATCH 模式或 WHERE 條件,用於定義業務術語或條件。與範本不同,facet 是部分查詢,而非完整查詢,因此不會以 GRAPH 子句開頭,也不會與單一問題繫結。QueryData 生成新查詢時,會套用與問題相關的 facet。
Facet 範例
在下列 facets 設定中,第一個面向會擷取涉及封鎖帳戶的轉帳模式,第二個面向則將「高風險轉帳」定義為轉帳金額達 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 >= ?"
}
}
]
}
當使用者詢問「Alex 進行了多少次高風險轉帳?」時,沒有任何範本符合這個問題。QueryData 會產生新的 GQL 查詢,並納入第二個面向,計算轉帳金額為 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 |
+--------------------------+
Facet 欄位
Facet 物件的結構與查詢範本相同,但有以下差異:
- 沒有
nl_query欄位。面向沒有nl_query欄位,因為面向描述的是多個問題中出現的條件,而非單一問題。 sql_snippet而非sql(必要)。GQL 子句,例如MATCH模式或WHERE條件。為避免混淆,請使用明確的節點和邊緣標籤及變數名稱 (例如(account:Account)),讓 QueryData 能將 GQL 子句與查詢的其他部分結合。intent(必填)、manifest(選填) 和parameterized(選填)。定義業務術語或條件的方式與範本欄位相同,但 QueryData 會比對問題與intent(因此請提供描述性內容,manifest為選填),且parameterized包含parameterized_intent和parameterized_sql_snippet。
搜尋查詢
值搜尋是查詢,而非對照表。QueryData 會先針對問題中的每個值詞組 (例如姓名、暱稱或國家/地區等文字值) 執行一次值搜尋,並將詞組替換為 $value,然後才會生成 GQL 查詢。接著,系統會使用查詢傳回的最接近儲存值,以及這些值的來源屬性,編寫 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
)
當使用者詢問「誰擁有 rainy day 帳戶?」時,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 接著會產生 GQL 查詢,篩選 {nick_name: 'Rainy Day Fund'} 而非 {nick_name: 'rainy day'}:
GRAPH `FinGraph`
MATCH (p:`Person`)-[:`Owns`]->(a:`Account` {`nick_name`: 'Rainy Day Fund'})
RETURN DISTINCT SAFE_TO_JSON(p) AS person
使用 FinGraph 樣本資料,這項查詢會以 JSON 格式傳回 Dana 的 Person 節點,類似下列內容:
{
"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 可重複使用。將查詢編寫為 SELECT 陳述式,並使用 GRAPH_TABLE 運算子比對節點或邊緣標籤、比較屬性與 $value,然後傳回下表中的五個資料欄。 |
concept_type |
必填 | 搜尋結果的值類型標籤,例如 Account nickname 或 Person country。 |
description |
選用 | 說明搜尋如何比對值。 |
每個值搜尋 query 都必須依序傳回下列五個資料欄:
| 輸出資料欄 | 說明 | 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 不會一次執行一項值搜尋,針對問題中的每個值詞組,系統會在每個值搜尋中將詞組替換為 $value,在每個查詢中附加 ORDER BY distance LIMIT 10,使用 UNION ALL 結合查詢,並將結果做為單一 GoogleSQL 陳述式執行,保留 10 個最接近的相符項目。由於查詢會合併,因此值搜尋會寫成 GRAPH_TABLE 上的 SELECT 陳述式,而非獨立的 GQL 陳述式:GRAPH_TABLE 會將 GQL MATCH 模式做為資料表執行,而 UNION ALL 和共用的 ORDER BY distance 則是 SQL 建構。
這種執行模式會對您編寫的查詢產生下列影響:
- 沒有外部
ORDER BY或LIMIT。請勿將ORDER BY或LIMIT新增至外部SELECT陳述式。QueryData 會附加這些子句,而重複的子句會導致陳述式失敗。 - 相容的資料欄類型。檔案中的每個值搜尋都必須傳回相同的五個資料欄,順序和類型也必須相容。舉例來說,在所有網頁中,
context都應傳回JSON '{}',而不是在部分網頁中傳回'{}'。 - 必要
$value預留位置。查詢必須至少包含$value一次,否則上傳作業會失敗。 - 僅限文字值。值搜尋只會針對文字值執行。QueryData 不會對數字、日期、時間或貨幣金額執行這些函式。
限制
Spanner Graph 的背景資訊集有下列限制:
- 資料庫的情境集僅支援查詢範本、查詢 facet 和值搜尋。
- 資料庫的情境集僅供 Conversational Analytics API 中的
QueryData端點使用。
後續步驟
- 瞭解如何在 Spanner Studio 建立或刪除情境集。
- 瞭解如何使用脈絡工程代理建立脈絡資料集。