QueryData の概要

QueryData は、Conversational Analytics API の自然言語から SQL への変換（NL2SQL）ツールです。これにより、AI エージェントとアプリケーションは自然言語を使用して運用データベースにクエリを実行できます。アプリケーションまたはエージェントが自然言語を使用して質問を送信すると、QueryData は質問を言語固有の SQL クエリに変換し、データベースに対してクエリを実行して、生成された SQL と QueryData が質問をどのように解釈したかの説明とともにクエリ結果を返します。

データベースで QueryData を使用する方法については、サポートされているデータベースのドキュメントをご覧ください。

主な機能

QueryData は、エージェント向けデータベース アプリケーションに次の機能を提供します。

  • 高精度: データベース スキーマ メタデータと、キュレートしたコンテキスト セットを組み合わせることで、ビジネス クリティカルなクエリでほぼ 100% の精度を達成します。
  • ビジネスとの関連性: SQL 生成を、未加工のテーブル名や列名のみに依存するのではなく、組織のドメイン用語、指標定義、ビジネス ロジックにグラウンディングします。
  • 説明可能性: 合成された SQL クエリと自然言語の回答とともに、人間が読める形式のインテントの説明を生成します。これにより、ユーザーは QueryData がリクエストをどのように変換したかを確認できます。
  • データ セキュリティ: AlloyDB、Cloud SQL for MySQL、Cloud SQL for PostgreSQL でパラメータ化されたセキュアビューを使用して、行レベルのアクセス制御を適用し、プロンプト インジェクションからユーザーデータを保護します。

QueryData を使用する場面

QueryData は、オペレーショナル データベース データへの高速で予測可能かつ正確なアクセスを必要とするインタラクティブなアプリケーションや AI エージェントを構築するデベロッパー向けに設計されています。たとえば、QueryData は次のユースケースに最適です。

  • カスタマー サービスの自動化: 「注文した商品はどこにありますか？」、「現在のアカウント残高はいくらですか？」といった大量のユーザーからの問い合わせに対応します。
  • e コマースとカタログ検索のアシスタント: 「16 GB 以上の RAM と 10 時間以上のバッテリー駆動時間を備えた軽量ノートパソコンを見せて」といった複数の条件を含む質問を使用して、ユーザーが構造化されたカタログをフィルタリングして探索できるようにします。
  • 現場作業と社内ツール: 従業員がリアルタイムで在庫状況、部品の入手可能性、サービス チケットのステータスをクエリできるようにします。
  • Agentic Workflows: Agent Development Kit（ADK）、データベース向け MCP ツールボックス、LangChain などの Agentic Workflows で、構造化データベース クエリをツールとして公開します。

QueryData の仕組み

一般的な大規模言語モデル（LLM）には、組織のプライベート データ値、わかりにくい列名、ドメイン固有のビジネスルールに関する情報がありません。ユーザーの質問方法とデータベースのデータ保存方法のギャップを埋めるため、QueryData は次の階層化されたコンテキストを使用します。

  • スキーマ オントロジー: データベース カタログまたは Knowledge Catalog 内のテーブルと列の説明を拡充し、テーブル、列、ステータス コード、結合関係のビジネス上の意味を説明します。
  • コンテキスト セット: データベース インスタンスに関連付けられた、次の 3 つの構成要素を定義するキュレートされたコレクション。
    • クエリ テンプレート: 検証済みのパラメータ化された SQL ステートメントとインテントの説明とペア設定された、代表的な自然言語の質問。
    • クエリ ファセット: モジュラー SQL 述語とフィルタ フラグメント。QueryData は、クエリ テンプレートと動的に組み合わせて、フィルタの組み合わせごとに個別のテンプレートを必要とせずにファセット検索をサポートします。
    • 値検索: 完全一致、ファジー トライグラム、セマンティック ベクトル検索クエリ。ユーザーの非公式なフレーズ、類義語、スペルミスのある用語を、データベース内の実際の値と列にリンクします。

アプリケーションが Conversational Analytics API の projects.locations.queryData メソッドを呼び出すと、QueryData は次の手順を実行します。

  1. 値の解決: データベースに対して値検索クエリを実行し、プロンプト内のエンティティ フレーズ（都市名、商品カテゴリ、コードなど）を正確なデータベース列値にマッピングします。
  2. インテントの照合と曖昧性除去: ユーザーの質問を、コンテキスト セット内のクエリ テンプレートとファセット、およびスキーマ オントロジーと照合します。質問があいまいな場合や、必須パラメータが不足している場合、QueryData は曖昧性除去の質問を返してユーザーの意図を明確にできます。
  3. クエリ合成: 一致したテンプレート構造、適用可能なファセット、解決されたリテラル値を組み合わせるか、テンプレートが一致しない場合はスキーマ オントロジーから SQL を生成して、言語固有の SQL クエリを合成します。
  4. クエリの実行とレスポンス: 生成された SQL をターゲット データベースに対して実行し、表形式の結果セット、生成された SQL クエリ、インテントの説明、オプションの自然言語の要約を返します。

100% に近い精度の Text-to-SQL を実現するための戦略

Text-to-SQL で 100% に近い精度を達成するには、ヒルクライミングと呼ばれる反復的なエンジニアリング プロセスが必要です。ユーザーの質問を事前に予測するのではなく、ベースライン スキーマの説明から始めて、EvalBench を使用してゴールデン SQL クエリの代表的なベンチマークに対してエージェントを評価し、精度のギャップを解決します。

アーキテクチャ図、SQL の例、評価ベンチマークなど、精度のギャップを解決するための推奨戦略（レシピ）の詳細については、100% に近い精度の Text-to-SQL を実現するための 6 つのレシピをご覧ください。また、これらの Text-to-SQL の精度レシピを実装する方法を学ぶためのコンパニオン Codelab もお試しください。

要約すると、6 つのレシピは次のとおりです。

  • レシピ 0: コンテキスト セットを初期化してアプリケーションを接続する。まず、スキーマにわかりやすいテーブルと列のコメントを記述し、Conversational Analytics API クライアント ライブラリまたは データベース向け MCP ツールボックス の cloud-gemini-data-analytics-query ツールを使用して、アプリケーションを QueryData に接続します。
  • レシピ 1: クエリ テンプレートを使用して解釈を挿入する。最も重要なビジネス上の質問に対して検証済みのサンプル SQL クエリを提供し、パラメータ化された SQL テンプレート、パラメータ化されたインテントの説明、意味的に同等の質問バリエーションをキャプチャするマニフェストに一般化します。
  • レシピ 2: ファセット テンプレートを使用する。ベースクエリ テンプレートをモジュラー クエリ ファセット（独自のマニフェストとインテントを持つ再利用可能な SQL 条件）と組み合わせることで、QueryData は条件の組み合わせごとに個別のテンプレートを必要とせずに、マルチフィルタ クエリを動的に作成できます。
  • レシピ 3: 値検索で曖昧さを解消する。値検索クエリを定義して、自然言語の質問の値のフレーズ（固有の用語、類義語、スペルミスなど）を実際のデータベースの列と値にリンクします。また、用語が複数のエンティティ タイプに一致する場合は、QueryData が明確化を求めるようにします。
  • レシピ 4: セマンティック検索と AI 演算子を統合する。構造化された SQL テンプレートとファセットをベクトル検索およびデータベース内 AI 演算子（AlloyDB の AI.IF や AI.RANK など）と組み合わせて、セマンティック基準を使用して非構造化テキストまたはマルチモーダル データをフィルタリングしてランク付けします。
  • レシピ 5: パラメータ化されたセキュアビューを使用する。AlloyDB、Cloud SQL for MySQL、Cloud SQL for PostgreSQL のパラメータ化されたセキュアビューで認証済みユーザー パラメータをバインドすることで、厳格な行レベルのセキュリティを適用し、プロンプト インジェクションからユーザーデータを保護します。

これらのレシピを手動で適用することも、オープンソースのコンテキスト エンジニアリング エージェントを使用して、ヒルクライミング ワークフロー（評価セットの拡張、EvalBench 評価の実行、精度のギャップの分析、新しいテンプレート、ファセット、値検索の提案）を自動化することもできます。

次のステップ