コンテキストセットの概要

コンテキストセットは、QueryData などのツールが高精度なクエリを生成できるようにする、データベース固有の情報のコレクションです。コンテキストセットには、QueryData がデータベーススキーマとアプリケーションのビジネスロジックを理解するのに役立つテンプレート、ファセット、値検索が含まれます。

サポートされているデータベースは次のとおりです。

AlloyDB for PostgreSQL
Cloud SQL for MySQL
Cloud SQL for PostgreSQL
Spanner

コンテキストセットとは

効果的なエージェントアプリケーションを構築するには、QueryData などのツールがデータの編成とビジネスロジックを理解している必要があります。この情報は、コンテキストセットの形式で提供します。

コンテキストは、各コンテキストタイプの JSON オブジェクトを含むファイルで定義します。このようなコンテキストファイルは、Gemini CLI を使用して作成します。その後、コンソールで作成したコンテキストセットにコンテキストファイルをアップロードします。 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": "T.\"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": "T.\"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 形式のテンプレートとファセットをまとめたもので、自然言語の質問を特定のデータベースのクエリに変換する際に役立ちます。コンテキストを定義すると、一般的なクエリパターンに対して高精度の 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 クエリ（パラメータ化されたインテントに対応している）。

クエリファセットは、代表的な自然言語の条件と、対応する SQL 述語をまとめたものです。ファセットはフィルタリングと条件を管理し、クエリテンプレートでファセット検索を実行できるようにします。

クエリファセットオブジェクトは次のようになります。

{
...
"facets": [
    {
      "sql_snippet": "T.\"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": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

ファセット JSON オブジェクトの主なコンポーネントは次のとおりです。

sql_snippet: SQL スニペット。
intent: SQL 述語の説明。
manifest: 一般化された自動生成形式のインテント。
parameterized_intent: テンプレート化された自動生成形式のインテント（エンティティ値がパラメータによって置き換えられている）。
parameterized_sql_snippet: パラメータ化されたインテントに対応する、テンプレート化された自動生成形式の sql_snippet。

値検索クエリ

[値検索クエリ](/spanner/docs/build-context-gemini-cli#generate-value-searches)は、一致関数を使用してデータベース内の値とそのコンテキストを検索する、デベロッパー定義のクエリです。値のリンクでは、これらのクエリの結果を使用して、一致する値を含むテーブルと列を特定し、値のコンセプトタイプを理解し、スペルミスを修正します。

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"
    }
  ]
}

値検索 JSON オブジェクトの主なコンポーネントは次のとおりです。

query: データベース内のテーブルの列に保存されている値に対して値フレーズを照合するロジックを定義する、パラメータ化された SQL ステートメント。通常、結果セットは、一致した値、スキーマの場所、コンセプトタイプ、正規化された距離指標（0 ～ 1）を射影します。
concept_type: 値に割り当てられたセマンティックラベル（district や loan_status など）。このラベルは、値のリンクと最終的に QueryData API などのツールがスキーマ内の値フレーズの役割を理解するのに役立ちます。また、値のコンセプトをターゲットとする SQL ステートメントと、値フレーズが表示されるテーブルと列の生成にも役立ちます。
description: 検索ロジックの説明。

制限事項

コンテキストセットには次のような制限があります。

データベースのコンテキストセットは、テンプレート、ファセット、値検索のみをサポートします。
データベースのコンテキストセットは、Conversational Analytics API の QueryData エンドポイントでのみ使用されます。

次のステップ

Spanner Studio でコンテキストセットを作成または削除する方法を確認する。

コンテキスト セットの概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

コンテキスト セットとは

コンテキスト セット ファイルの形式

クエリ テンプレート

クエリ ファセット