QueryData をテストする

このドキュメントでは、QueryData をテストしてコンテキスト セット ファイルを更新する方法について説明します。QueryData の自然言語による質問から SQL クエリを生成する能力をテストできます。生成されたクエリが正確でない場合は、コンテキスト セット ファイルを更新できます。

コンテキスト セットの詳細については、コンテキスト セットの概要をご覧ください。

始める前に

コンテキスト セットがすでに作成され、コンテキスト セット ファイルが QueryData エージェントにアップロードされていることを確認します。詳細については、AlloyDB Studio でコンテキスト セットを管理するをご覧ください。

QueryData をテストする

QueryData をテストする手順は次のとおりです。

  1. Google Cloud コンソールで、AlloyDB ページに移動します。

    AlloyDB に移動する

  2. リストからクラスタを選択します。

  3. ナビゲーション メニューで [AlloyDB Studio] をクリックします。

  4. Identity and Access Management 認証を使用して Studio にログインします。

  5. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。

  6. [コンテキスト セットをテスト] をクリックします。

  7. クエリエディタで、[SQL を生成] をクリックして [コーディング サポート] パネルを開きます。

  8. エディタに自然言語の質問を入力して SQL クエリを生成し、[生成] をクリックします。

  9. SQL クエリの精度を確認します。

コンテキスト セットをダウンロードして更新する

自然言語による質問に対して生成された SQL クエリにご納得いただけない場合は、既存のコンテキスト セット ファイルをダウンロードします。次に、クエリ テンプレートを確認して更新し、更新したコンテキスト ファイルをエージェントに再アップロードできます。

コンテキスト セットをダウンロードして更新する手順は次のとおりです。

  1. [エクスプローラ] ペインで、[アクションを表示] をクリックします。
  2. [コンテキスト ファイルをダウンロード] をクリックします。
  3. Gemini CLI を使用してコンテキストを構築するの手順に沿ってクエリのペアを追加し、コンテキストを更新します。
  4. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。
  5. [コンテキスト セットを編集] をクリックします。
  6. [コンテキスト セット ファイルのアップロード] セクションで [参照] をクリックし、更新したコンテキスト セット ファイルを選択します。
  7. [保存] をクリックして、コンテキスト セットを更新します。

レスポンスの精度が納得できるものになったら、QueryData エンドポイントを使用してアプリケーションをコンテキスト セットに接続できます。

コンテキスト セット ID を確認する

データ アプリケーションを QueryData エージェントに接続するには、コンテキスト セットの ID が必要です。

  1. Google Cloud コンソールで、AlloyDB ページに移動します。

    AlloyDB に移動する

  2. リストからクラスタを選択します。

  3. ナビゲーション メニューで [AlloyDB Studio] をクリックします。

  4. Identity and Access Management 認証を使用して Studio にログインします。

  5. [エクスプローラ] ペインで、使用しているコンテキスト セットの横にある [アクションを表示] をクリックします。

  6. [コンテキスト セットを編集] をクリックします。

  7. [コンテキスト セット ID] に示されているコンテキスト ID をメモします。コンテキスト セット ID の形式は projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates のようになります。

QueryData をアプリケーションに接続する

QueryData メソッド呼び出しでコンテキスト セット ID を設定して、AlloyDB、Spanner、Cloud SQL、Cloud SQL for PostgreSQL などのデータベース データソースの作成済みコンテキストを提示します。詳細については、データベースのデータソースのエージェント コンテキストを定義するをご覧ください。

コンテキスト セットをテストしたら、QueryData 呼び出しでデータベースのデータソースを参照できます。

作成されたコンテキストを含む QueryData リクエストの例

以下の例は、alloydb データベースをデータソースとして使用した QueryData リクエストを示しています。agent_context_reference.context_set_id フィールドは、データベースに保存されている事前作成済みのコンテキストにリンクするために使用されます。

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans? A3 contains the data of region.",
  "context": {
    "datasource_references": [
      {
        "alloydb": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "context-set-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-east1/contextSets/bdf_pg_all_templates"
          }
        }
      }
    ]
  },
  "generation_options": {
    "generate_query_result": true,
    "generate_natural_language_answer": true,
    "generate_disambiguation_question": true,
    "generate_explanation": true
  }
}

リクエスト本文には次のフィールドが含まれます。

  • prompt: エンドユーザーからの自然言語による質問。
  • context: データソースに関する情報を入力します。
    • datasource_references: データソースのタイプを指定します。
      • alloydb: データベースのクエリを実行する際に必須となります。このフィールドは、クエリの実行対象とするデータベースによって異なります。
        • database_reference: データベース インスタンスに関する情報を指定します。
          • cluster_id: データベース インスタンスのクラスタ ID。
          • project_id: データベース インスタンスのプロジェクト ID。
          • region: AlloyDB インスタンスのリージョン。
          • instance_id: AlloyDB インスタンスのインスタンス ID。
          • database_id: データベースの ID。
        • agent_context_reference: データベースに保存されている作成済みコンテキストへのリンク。
          • context_set_id: データベースに保存されているコンテキストの完全なコンテキスト セット ID。例: projects/context-set-project/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates
  • generationOptions: 生成する出力のタイプを構成します。
    • generate_query_result: クエリ結果を生成して取得する場合は true に設定します。
    • generate_natural_language_answer: 省略可。true に設定すると、自然言語による回答が生成されます。
    • generate_explanation: 省略可。true に設定すると、SQL クエリの説明が生成されます。
    • generate_disambiguation_question: 省略可。true に設定すると、クエリがあいまいな場合はクエリを明確にするための質問が生成されます。

QueryData の回答の例

以下は、QueryData 呼び出しによる回答の成功例です。

{
  "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
  "query_result": {
    "columns": [
      {
        "name": "count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

次のステップ