はじめに
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