はじめに

Databricks の AI/BI Genie（現 Genie Agent、旧 Genie Space）では、あらかじめ「例SQLクエリ（Example query）」を登録しておくことで、Genie が自然言語の質問に答える際の手がかりにできます。この例SQLクエリの一部を「パラメータ」にしておくと、実行時にユーザー入力で値を差し替えられるようになり、さらにその質問への回答は「Trusted（検証済み）」として扱われます。

本記事では、サンプルスペース「Bakehouse Sales Starter Space」を使って、パラメータ化した例SQLクエリを実際に登録し、チャットで Trusted な回答が返るところまでを実機で確認しました。

先に要点をまとめると、次のとおりです。

パラメータは :parameter_name という記法で例SQLクエリに埋め込む
データ型は String / Date / Date and Time / Decimal / Integer から選ぶ
パラメータ化クエリのテキストが回答生成に使われると、回答は Trusted（Trusted Asset）として扱われる
ユーザーは回答画面でパラメータ値を編集して再実行できる

UIの位置についての注意（重要）

Databricks の公式ドキュメント（AWS版）では、パラメータ化例SQLクエリの設置場所は「Configure ＞ Instructions ＞ SQL Queries タブ」と説明されています。しかし、今回検証した Free Edition の現行UIでは、例SQLクエリは Instructions ではなく Examples タブに統合されており、Add ＞ Example query から登録する形になっていました。

つまり実機での導線は次のとおりです。

Configure ＞ Examples ＞ Add ＞ Example query

対象クラウド（AWS / Azure / GCP）やエディションによってUI文言・導線に差異が出る可能性があるため、最終的にはご自身の環境のドキュメントとUIで確認してください。本記事のスクリーンショットはすべて Free Edition の現行UIのものです。

登録手順

1. Examples タブを開く

Configure を開き、Examples タブを選びます。ここには既存の例（QUERY / MEASURE など）が一覧表示されます。

2. Add ＞ Example query

右上の Add をクリックすると、Example query / Filter / Measure / Field / Join の選択肢が出ます。パラメータ化した例SQLクエリを作るので Example query を選びます。

3. 質問文とSQLを入力する

上部の「What question does this query answer?」に、このクエリが答える質問を入力します。続けて下のエディタにSQLを入力します。

今回は次のSQLを入力しました。パラメータにしたい位置に :payment_method と直接書いています。

SELECT * FROM samples.bakehouse.sales_transactions
WHERE paymentMethod = :payment_method
LIMIT 100

:parameter_name の形式でSQL本文に直接書くと、その名前のパラメータが自動的に登録されます（Add parameter ボタンから追加することもできます）。下部の Parameters セクションを開くと、payment_method が登録されているのが確認できます。

4. Parameter details で詳細を設定する

パラメータ名の横の歯車アイコンをクリックすると、Parameter details ダイアログが開きます。

設定項目は次の3つです。

項目	内容
Keyword	クエリ内でパラメータを表す名前。SQL本文の `:name` トークンと対応する
Data type	パラメータのデータ型。String（既定）/ Date / Date and Time / Decimal / Integer
Comment	取りうる値や制約の説明。Genie が正しい値を選ぶ手がかりになる

Data type の選択肢は以下のとおりです。

今回は Data type を String のままにし、Comment に「支払い方法。visa / mastercard / amex / paypal のいずれか」と補足を入れました。

5. Preview で検証して保存する

Parameters セクションでパラメータにテスト値（今回は visa）を入れ、Preview を押すと、その値でクエリが実行され結果が表示されます。ここでSQLの妥当性を確認できます。

問題なければ Save で保存します。保存すると一覧に QUERY タイプの例として追加されます。

動作確認：Trusted な回答とパラメータ値の編集

チャット（Chat モード）で、登録した質問に近い内容を聞いてみます。ここでは「mastercardで支払われた取引を表示して」と質問しました。

回答には緑色の Trusted バッジと「Found a trusted query that might match your question: 指定した支払い方法の取引を表示する」という表示が付きました。パラメータ化クエリのテキストが回答生成に使われたため、回答が検証済み（Trusted Asset）として扱われていることが分かります。回答には payment_method: mastercard というパラメータ値のピルと、結果テーブル（100行）が含まれています。

payment_method: mastercard のピルをクリックすると、パラメータ値を編集できる入力欄が開きます。値を書き換えて再実行すれば、同じクエリを別の支払い方法で実行できます。

注意点

入力値が指定したデータ型と一致しないと、Genie は誤った型として扱い、不正確な結果を招くことがあります。型指定は正確に行い、Comment で取りうる値の範囲を補足しておくとよいです。
パラメータを持たない静的な例クエリは Trusted にはならず、文脈提供・SQL生成の手がかり止まりになります。回答を Trusted にしたい場合はパラメータ化が必要です。

権限

Trusted Asset（パラメータ化クエリを含む）の追加・削除には、対象の Genie Agent への CAN EDIT 権限が必要です。

まとめ

パラメータ化例SQLクエリは :parameter_name 記法でSQL本文に埋め込む
Parameter details で Keyword / Data type / Comment を設定する
テスト値＋Preview で妥当性を確認してから Save する
パラメータ化クエリが使われた回答は Trusted になり、ユーザーが値を編集して再実行できる
現行 Free Edition UI では Configure ＞ Examples ＞ Add ＞ Example query から登録する（AWS版ドキュメントの「SQL Queries タブ」とは導線が異なる）

出典

Genie のチューニング（品質向上）: https://docs.databricks.com/aws/en/genie/tune-quality
Trusted assets: https://docs.databricks.com/aws/en/genie/trusted-assets.html