Omni の Topic に sample_queries を設定してみた
こんにちは、ikumiです。
Omni の Topic を作成したとき、「ユーザーが ワークブック上でトピックを開いてもどこから分析を始めればいいか分からない」という状況になることがあります。
sample_queries パラメーターを使うと、よく使う集計パターンをトピックにあらかじめ登録しておき、トピック を開いたときの分析の出発点として提供できます。さらに、登録したサンプルクエリは Omni Agent（AI）がトピックの使い方を理解するためのコンテキストとしても活用されます。今回はこの sample_queries の設定方法と動作を試してみました。
機能概要
sample_queries は、トピックに対して実行可能なサンプルクエリのリストを定義するパラメーターです。
登録したサンプルクエリは以下の場面で活用されます。
| 活用場面 | 内容 |
|---|---|
| Explore の初期画面 | トピックを選択したときの画面にサンプルクエリが表示され、クリックするとそのまま実行できる |
| Omni Agent | AI エージェントが参照するコンテキストとして使われ、AI の回答精度向上に寄与する |
設定できる主なプロパティは以下の通りです。
| プロパティ | 必須 | 内容 |
|---|---|---|
query_name |
✅ | サンプルクエリの識別名（YAML のキー名） |
query.fields |
✅ | クエリに含めるフィールドのリスト |
query.base_view |
✅ | クエリの対象となるビュー名 |
description |
✅ | クエリの説明文 |
query.sorts |
ー | ソート条件 |
query.limit |
ー | 取得する最大行数 |
query.calculations |
ー | SQL 式で定義するカスタム計算項目 |
prompt |
ー | ユーザーの自然言語での問いかけ例 |
hidden |
ー | true にすると Explore の初期画面から非表示（AI には渡る） |
exclude_from_ai_context |
ー | true にすると AI のコンテキストからも除外する |
試してみた
今回は事前に作成してある、brand_ana__tran トピックのファイルを編集します。
1. GUI からサンプルクエリを登録する
まず GUI での操作方法を確認します。ワークブック上のbrand_ana__tranトピックからクエリを実行し、登録したい内容が出来上がったら Model メニュー >Save as sample query to topic を選択します。
表示された画面でクエリ名・説明・prompt などを入力し、Save topic sample query を押します。
保存後にIDEでトピックを確認すると、sample_queries として追記されていることを確認できます。GUI から登録した場合でも、生成された YAML を直接確認・編集できます。
sample_queries:
カテゴリー別売上高と利益:
query:
fields:
[
brand_ana__tran.l_catefgory,
brand_ana__tran.m_category,
brand_ana__tran.sales_sum,
brand_ana__tran.profit_sum
]
base_view: brand_ana__tran
limit: 1000
sorts:
- field: brand_ana__tran.profit_sum
desc: true
topic: brand_ana__tran
description: 売上と利益の指標を、大型および中型製品カテゴリ別に分類し、利益の高い順に並べ替えて分析します。
prompt: どの製品カテゴリーが最も高い利益を生み出しているか？
2. YAML を直接編集してサンプルクエリを追加する
YAML を直接書いて登録することもできます。brand_ana__tran.topic.yaml に以下を追加します。
sample_queries:
ブランド別売上合計:
query:
fields:[brand_ana__tran.brand,brand_ana__tran.sales_sum]
base_view: brand_ana__tran
sorts:
- field: brand_ana__tran.sales_sum
desc: true
limit: 20
topic: brand_ana__tran
description: ブランドごとの売上合計を降順で表示する
prompt: ブランド別の売上合計を見たい
月別ブランド別売上推移:
query:
fields: [ brand_ana__tran.yyyymm, brand_ana__tran.brand, brand_ana__tran.sales_sum ]
base_view: brand_ana__tran
sorts:
- field: brand_ana__tran.yyyymm
desc: false
topic: brand_ana__tran
description: 月別・ブランド別の売上推移を時系列で表示する
prompt: 月ごとのブランド別売上の推移を確認したい
なお、GUIから登録する方法と、YAML を直接編集する方法どちらでも、定義できる内容に違いはございません。
3. Explore の初期画面でサンプルクエリを確認する
変更を保存し、brand_ana__tran ワークブック上で対象のトピックを新しく開きます。初期画面に登録したサンプルクエリが表示されていれば問題ありません。
サンプルクエリをクリックすると、定義したフィールドとソート条件が自動で適用された状態でクエリが実行されます。
最後に
Omni の sample_queries を使って、トピックにサンプルクエリを登録する方法を試してみました。
GUI の Save as sample query to topic で簡単に登録できるほか、YAML を直接書いて細かく制御することもできます。よく使う集計パターンをあらかじめ登録しておくことで、データに不慣れなユーザーでも迷わず分析を始められる導線が作れます。Omni Agent を活用している場合は AI のコンテキストとしても利用されるため、是非利用してみてください。
