內容集總覽

脈絡資料集內含一系列指引,可協助 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 如何先執行值搜尋,將值詞組解析為儲存的值,然後重複使用完全比對的範本、調整最接近的範本,或產生新的 GQL 查詢,並使用查詢範本和查詢面向做為指引。

如圖所示,QueryData 收到問題時,會按照下列順序使用脈絡資料集:

  1. 擷取相關背景資訊。QueryData 會擷取與問題最相似的範本、facet 和值搜尋。
  2. 執行價值搜尋。針對問題中的每個值詞組 (例如名稱或暱稱),QueryData 會執行值搜尋,找出相符的儲存值。值搜尋不適用於數字、日期、時間或貨幣金額。
  3. 比對查詢範本。如果問題與範本相符,QueryData 會使用範本中經過驗證的 GQL 查詢。如果與 nl_query 完全比對,QueryData 會直接執行 sql 查詢。如果與參數化範本相符,QueryData 會將 parameterized_sql 中的 ? 預留位置替換為問題中的值,並執行產生的查詢。
  4. 生成新的 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 端點使用。

後續步驟