內容集總覽

脈絡資料集內含特定資料庫的資訊，助 QueryData 等工具生成高精確度的查詢。情境集可包含範本、面向和值搜尋，協助 QueryData 瞭解資料庫結構定義和應用程式的商業邏輯。

支援的資料庫如下：

  • AlloyDB for PostgreSQL
  • MySQL 適用的 Cloud SQL
  • PostgreSQL 適用的 Cloud SQL
  • Spanner
  • 與 MongoDB 相容的 Firestore

什麼是脈絡資料集

如要建構有效的代理應用程式，QueryData 等工具必須瞭解您的資料組織和商業邏輯。您需要以情境組合的形式提供這項資訊。

您可以在檔案中定義情境，其中包含每種情境類型的 JSON 物件。您可以透過脈絡工程代理製作這些脈絡檔案。接著，將脈絡資料檔案上傳至您在 Google Cloud控制台中建立的脈絡資料集。這個程序可讓 QueryData 等工具瞭解資料庫的特定結構定義和應用程式的商業邏輯。

內容檔案類似下列範例：

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

脈絡資料集檔案格式

脈絡資料集檔案包含 JSON 格式的精選範本、商情項目和值搜尋，可引導 QueryData 等工具將自然語言問題翻譯成特定資料庫的查詢。定義情境可確保常見查詢模式的 SQL 生成準確度。

為盡量提高準確度，請確保內容設定準確且涵蓋預期應用程式查詢。

您可以在 us-central1、us-east1、europe-west4 和 asia-southeast1 區域建立情境集。

查詢範本

查詢範本是一組精選的代表性自然語言問題，以及對應的 SQL 查詢。此外，這些範例也包含說明，提供將自然語言轉換為 SQL 的宣告式依據。

查詢範本物件類似於下列項目：

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  ...
}

查詢範本 JSON 物件的主要元件如下：

  • nl_query：QueryData 等工具處理的自然語言查詢範例。
  • sql：自然語言查詢的 SQL 查詢。
  • intent：自然語言查詢的目標或用途。如未設定，這個值會預設為自然語言查詢。
  • manifest：自動生成的通用意圖。
  • parameterized_intent：意圖的範本，會自動生成，並將實體值替換為參數。
  • parameterized_sql：系統根據參數化意圖自動生成的 SQL 查詢範本。

查詢 facet

查詢 facet 是一組精選的代表性自然語言條件，具有對應的 SQL 述詞。Facet 可管理篩選條件，讓查詢範本執行多面向搜尋。

查詢篩選器物件大致如下：

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

分面 JSON 物件的主要元件如下：

  • sql_snippet：SQL 程式碼片段。為避免模稜兩可，請使用資料表名稱限定資料欄名稱 (例如 table_name.column_name)。
  • intent：SQL 述詞的說明。
  • manifest：意圖的自動生成一般形式。
  • parameterized_intent：意圖的範本化自動生成形式，實體值會替換為參數。
  • parameterized_sql_snippet：sql_snippet 的範本化自動生成形式，對應於參數化意圖。

搜尋值查詢

值搜尋查詢 是開發人員定義的查詢，會使用比對函式在資料庫中尋找值及其內容。值連結功能會使用這些查詢的結果，找出哪些資料表和資料欄包含相符的值、瞭解值的概念類型，以及修正拼寫錯誤。

QueryData API 會使用值連結，更準確地將自然語言轉換為 SQL。使用值搜尋查詢時，API 可根據資料庫值修正錯別字並解析值類型，進而提高轉換準確度。

連結值可提高自然語言到 SQL 轉換的準確度。舉例來說，如果使用者詢問「希斯洛機場有任何航班嗎？」，資料庫可能會將機場名稱儲存為「倫敦希斯洛機場」。如果沒有值連結，產生的 SQL 可能會依 WHERE name = 'Heathrow' 篩選，且不會傳回任何結果。價值搜尋查詢會引導代理程式將「希斯洛」對應至正確的資料庫值「倫敦希斯洛」，以及其結構定義位置 (airports.name)，確保生成的 SQL 查詢正確無誤。

值搜尋查詢範例如下：

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

值搜尋 JSON 物件的主要元件如下：

  • query：參數化 SQL 陳述式，用於定義將值片語與資料庫中儲存的值進行比對的邏輯。結果集通常會顯示相符的值、結構定義位置、概念類型，以及正規化距離指標 (介於 0 和 1 之間)。
  • concept_type：指派給值的語意標籤，例如 district 或 loan_status。這個標籤有助於連結值，並最終讓 QueryData API 等工具瞭解值詞組在結構定義中的角色。此外，這項功能還能產生 SQL 陳述式，指定值的概念，以及值詞組所在的資料表和資料欄。
  • description：搜尋邏輯的說明。

限制

情境組合有下列限制：

  • 不支援 SQL Server 適用的 Cloud SQL。
  • 資料庫的情境組合僅支援範本、切面和值搜尋。
  • 資料庫的情境集僅供 Conversational Analytics API 中的 QueryData 端點使用。

後續步驟