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

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

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

  • AlloyDB for PostgreSQL
  • Cloud SQL for MySQL
  • Cloud SQL for PostgreSQL
  • Spanner
  • MongoDB 互換の Firestore

コンテキスト セットとは

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

コンテキストは、コンテキスト タイプごとに JSON オブジェクトを含むファイルで定義します。このようなコンテキスト ファイルは、コンテキスト エンジニアリング エージェントを使用して作成できます。その後、 Google Cloudコンソールで作成したコンテキスト セットにコンテキスト ファイルをアップロードします。このプロセスにより、QueryData などのツールはデータベースの特定のスキーマとアプリケーションのビジネス ロジックを学習できます。

コンテキスト ファイルは次のようになります。

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "db.accounts.countDocuments({ \"district.region\": \"Prague\", \"loans\": { $exists: true, $not: { $size: 0 } }});",
      "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": "db.accounts.countDocuments({ \"district.region\": $1, \"loans\": { $exists: true, $not: { $size: 0 } }});",
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "\"district.average_salary\": { $gt: 6000, $lt: 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": "\"district.average_salary\": { $gt: $1, $lt: $2 }"
      }
    }
  ],
  "value_searches": [
    {
      "query": "db.airports.aggregate([{ '$match': { 'iata': $value } }, { '$project': { 'value': '$iata', 'columns': 'airports.iata', 'concept_type': 'Airport IATA Code', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (standard MQL) for 3-letter airport codes"
    },
    {
      "query": "db.airports.aggregate([{ '$match': { 'name': { '$regex': $value, '$options': 'i' } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Regex match for partial airport names"
    },
    {
      "query": "db.products.aggregate([{ '$match': { '$text': { '$search': $value } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': { '$meta': 'textScore' }, 'context': '', '_id': 0 } }, { '$sort': { 'distance': -1 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Full-text search for airport names"
    }
  ]
}

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

コンテキスト セット ファイルは、JSON 形式のテンプレート、ファセット、値検索をまとめたもので、QueryData などのツールが自然言語の質問を特定のデータベースのクエリに変換する際に役立ちます。コンテキストを定義すると、一般的なクエリパターンに対して高精度の MongoDB 互換のクエリ言語（MQL）を確実に生成できます。

精度を最大限に高めるには、コンテキスト セットが正確で、想定されるアプリケーション クエリを包括的にカバーしていることを確認します。

コンテキスト セットは、us-central1、us-east1、europe-west4、asia-southeast1 のリージョンで作成できます。

クエリ テンプレート

クエリ テンプレートは、代表的な自然言語の質問とそれに対応する MQL クエリをまとめたものです。また、自然言語から MQL への生成の宣言的な根拠を提供する説明も含まれています。

クエリ テンプレート オブジェクトは次のようになります。

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "db.accounts.countDocuments({ \"district.region\": \"Prague\", \"loans\": { $exists: true, $not: { $size: 0 } }});",
      "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": "db.accounts.countDocuments({ \"district.region\": $1, \"loans\": { $exists: true, $not: { $size: 0 } }});"
      }
    }
  ],
  ...
}

クエリ テンプレートの JSON オブジェクトの主なコンポーネントは次のとおりです。

  • nl_query: QueryData などのツールが処理する自然言語クエリの例。
  • sql: 自然言語クエリの MQL クエリ。sql キーの名前に関係なく、これには MQL が含まれます。
  • intent: 自然言語クエリの目標または目的。設定されていない場合、この値はデフォルトで自然言語クエリになります。
  • manifest: 一般化された自動生成形式のインテント。
  • parameterized_intent: テンプレート化された自動生成形式のインテント（エンティティ値がパラメータによって置き換えられている）。
  • parameterized_sql: テンプレート化された自動生成形式の MQL クエリ（パラメータ化されたインテントに対応している）。parameterized_sql キーの名前に関係なく、これには MQL が含まれます。

クエリ ファセット

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

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

{
  ...
  "facets": [
    {
      "sql_snippet": "\"district.average_salary\": { $gt: 6000, $lt: 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": "\"district.average_salary\": { $gt: $1, $lt: $2 }"
      }
    }
  ]
}

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

  • sql_snippet: MQL スニペット。sql_snippet キーの名前に関係なく、これには MQL が含まれます。あいまいさを避けるため、フィールド名をドキュメント名で修飾します（例: doc_name.field_name）。
  • intent: MQL 述語の説明。
  • manifest: 一般化された自動生成形式のインテント。
  • parameterized_intent: テンプレート化された自動生成形式のインテント（エンティティ値がパラメータによって置き換えられている）。
  • parameterized_sql_snippet: テンプレート化された自動生成形式の sql_snippet（パラメータ化されたインテントに対応している）。parameterized_sql_snippet キーの名前とは異なり、これには MQL が含まれています。

値の検索クエリ

値検索クエリは、一致関数を使用してデータベース内の値とそのコンテキストを検索する、デベロッパー定義のクエリです。値のリンクでは、これらのクエリの結果を使用して、一致する値を含むテーブルと列を特定し、値のコンセプト タイプを理解して、スペルミスを修正します。

QueryData API は、値のリンクを使用して、自然言語をより正確に MQL に変換します。値検索クエリを使用すると、API はデータベース値に基づいてスペルミスを修正し、値タイプを解決できるため、変換精度が向上します。

値のリンクにより、自然言語から MQL への変換精度が向上します。たとえば、ユーザーが「ヒースロー発のフライトはありますか？」と尋ねた場合、データベースには空港名が「ロンドン ヒースロー」として保存されることがあります。値のリンクがない場合、生成された MQL は { "name": "Heathrow" } でフィルタリングされ、結果が返されない可能性があります。値検索クエリは、エージェントが「Heathrow」を正しいデータベース値「London Heathrow」とそのスキーマの場所（airports.name）にマッピングするようにガイドし、生成された MQL が正確であることを保証します。

値検索クエリの例を次に示します。

{
  ...
  "value_searches": [
    {
      "query": "db.airports.aggregate([{ '$match': { 'iata': $value } }, { '$project': { 'value': '$iata', 'columns': 'airports.iata', 'concept_type': 'Airport IATA Code', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (standard MQL) for 3-letter airport codes"
    },
    {
      "query": "db.airports.aggregate([{ '$match': { 'name': { '$regex': $value, '$options': 'i' } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': 0, 'context': '', '_id': 0 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Regex match for partial airport names"
    },
    {
      "query": "db.products.aggregate([{ '$match': { '$text': { '$search': $value } } }, { '$project': { 'value': '$name', 'columns': 'airports.name', 'concept_type': 'Airport Name', 'distance': { '$meta': 'textScore' }, 'context': '', '_id': 0 } }, { '$sort': { 'distance': -1 } }, { '$limit': 1 }])",
      "concept_type": "Airport Name",
      "description": "Full-text search for airport names"

    }
  ]
}

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

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

制限事項

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

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

次のステップ