コンテキスト セットは、QueryData などのツールが高精度なクエリを生成するために必要なデータベース固有の情報のコレクションです。コンテキスト セットには、QueryData がデータベース スキーマとアプリケーションのビジネス ロジックを理解するために役立つテンプレート、ファセット、値検索を含めることができます。
サポートされているデータベースは次のとおりです。
- AlloyDB for PostgreSQL
- Cloud SQL for MySQL
- Cloud SQL for PostgreSQL
- Spanner
- MongoDB 互換の Firestore
- Bigtable
コンテキスト セットとは
効果的なエージェント アプリケーションを構築するには、QueryData などのツールがデータの編成とビジネス ロジックを理解している必要があります。この情報は、コンテキスト セットの形式で提供します。
コンテキストは、コンテキスト タイプごとに JSON オブジェクトを含むファイルで定義します。これらのコンテキスト ファイルは、コンテキスト エンジニアリング エージェントを使用して作成できます。その後、 Google Cloudコンソールで作成したコンテキスト セットにコンテキスト ファイルをアップロードします。このプロセスにより、QueryData などのツールはデータベースの特定のスキーマとアプリケーションのビジネス ロジックを学習できます。
コンテキスト ファイルは次のようになります。
{
"templates": [
{
"nl_query": "List all luxury hotels",
"sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
"intent": "hotels in Luxury tier",
"manifest": "hotels in a given product tier",
"parameterized": {
"parameterized_intent": "hotels in ? tier",
"parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
}
}
],
"facets": [
{
"sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
"intent": "hotels with rating at least 4.5",
"manifest": "hotels with rating at least a given number",
"parameterized": {
"parameterized_intent": "hotels with rating at least ?",
"parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
}
}
],
"value_searches": [
{
"query": "SELECT CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
"concept_type": "City",
"description": "Exact match for hotel city in hotels table"
}
]
}
コンテキスト セットのファイル形式
コンテキスト セット ファイルは、JSON 形式のテンプレート、ファセット、値検索をまとめたもので、QueryData などのツールが自然言語の質問を特定のデータベースのクエリに変換する際に役立ちます。コンテキストを定義すると、一般的なクエリパターンに対して高精度の SQL を確実に生成できます。
精度を最大限に高めるには、コンテキスト セットが正確で、想定されるアプリケーション クエリを包括的にカバーしていることを確認します。
コンテキスト セットは、us-central1、us-east1、europe-west4、asia-southeast1 リージョンで作成できます。プロジェクトで最初のコンテキスト セットを作成するときに、リージョンを選択する必要があります。後続のコンテキスト セットでは同じリージョンが使用されます。
クエリ テンプレート
クエリ テンプレートは、代表的な自然言語の質問とそれに対応する SQL クエリをまとめたものです。また、自然言語から SQL への生成の宣言的な根拠を提供する説明も含まれています。
クエリ テンプレート オブジェクトは次のようになります。
{
"templates": [
{
"nl_query": "List all luxury hotels",
"sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = 'Luxury' ORDER BY _key ASC",
"intent": "hotels in Luxury tier",
"manifest": "hotels in a given product tier",
"parameterized": {
"parameterized_intent": "hotels in ? tier",
"parameterized_sql": "SELECT CAST(_key AS STRING) AS hotel_id, CAST(cf['name'] AS STRING) AS name, CAST(cf['location'] AS STRING) AS location FROM `hotels` WHERE CAST(cf['price_tier'] AS STRING) = ? ORDER BY _key ASC"
}
}
],
...
}
クエリ テンプレートの JSON オブジェクトの主なコンポーネントは次のとおりです。
nl_query: QueryData などのツールが処理する自然言語クエリの例。sql: 自然言語クエリの SQL クエリ。intent: 自然言語クエリの目標または目的。設定されていない場合、この値はデフォルトで自然言語クエリになります。manifest: 一般化された自動生成形式のインテント。parameterized_intent: テンプレート化された自動生成形式のインテント（エンティティ値がパラメータによって置き換えられている）。parameterized_sql: テンプレート化された自動生成形式の SQL クエリ（パラメータ化されたインテントに対応している）。
クエリ ファセット
クエリ ファセットは、代表的な自然言語の条件と、対応する SQL 述語をまとめたものです。ファセットはフィルタリングと条件を管理し、クエリ テンプレートでファセット検索を実行できるようにします。
クエリ ファセット オブジェクトは次のようになります。
{
...
"facets": [
{
"sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= 4.5",
"intent": "hotels with rating at least 4.5",
"manifest": "hotels with rating at least a given number",
"parameterized": {
"parameterized_intent": "hotels with rating at least ?",
"parameterized_sql_snippet": "CAST(CAST(hotels.cf['rating'] AS STRING) AS FLOAT64) >= ?"
}
}
]
}
ファセット 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' でフィルタリングされ、結果が返されない可能性があります。値検索クエリは、エージェントが「Heathrow」を正しいデータベース値「London Heathrow」とそのスキーマの場所（airports.name）にマッピングするようにガイドし、生成された SQL が正確であることを確認します。
値の検索クエリの例を次に示します。
{
...
"value_searches": [
{
"query": "SELECT CAST(T.cf['location'] AS STRING) AS value, 'hotels.location' AS `columns`, 'City' AS concept_type, 0 AS distance, '' AS context FROM `hotels` AS T WHERE CAST(T.cf['location'] AS STRING) = CAST($value AS STRING)",
"concept_type": "City",
"description": "Exact match for hotel city in hotels table"
}
]
}
値検索 JSON オブジェクトの主なコンポーネントは次のとおりです。
query: 値フレーズをデータベースに格納されている値と照合するロジックを定義する、パラメータ化された SQL ステートメント。結果セットには通常、一致した値、スキーマの場所、コンセプト タイプ、正規化された距離指標（0 ～ 1）が投影されます。concept_type: 値に割り当てられたセマンティック ラベル（districtやloan_statusなど）。このラベルは、値のリンクを容易にし、最終的には QueryData API などのツールがスキーマ内の値フレーズの役割を理解するのに役立ちます。また、値のコンセプトをターゲットとする SQL ステートメントや、値フレーズが表示されるテーブルと列を生成するのにも役立ちます。description: 検索ロジックの説明。
制限事項
コンテキスト セットには次の制限があります。
- データベースのコンテキスト セットは、テンプレート、ファセット、値検索のみをサポートします。
- Bigtable 用 GoogleSQL はセット オペレーション（
UNION ALL）をサポートしていないため、複数の値の検索クエリにわたる値のリンクはサポートされていません。このようなリクエストは成功しますが、複数の値検索を含むコンテキスト セットの値はリンクされません。 - データベースのコンテキスト セットは、Conversational Analytics API の
QueryDataエンドポイントでのみ使用されます。