メトリクス ビューでパラメーターを使用する
パラメーターを使用すると、メトリクスビューをクエリーする際に値を渡すことができます。パラメーターを使用して、割引率や日付ウィンドウなど、さまざまな入力間で単一のメトリクスビュー定義を再利用します。フィルター、フィールドとメジャーの式、ソース、結合など、定数SQL式が有効な場所ならどこでもパラメーターを参照できます。ビューをクエリーする際に、値を引数として渡します。
パラメーターは重複を減らします。バリアントごとに個別のメトリクスビューを維持する代わりに、一度ロジックを定義し、各呼び出し元が独自の値を指定できるようにします。パラメーターにはdefault値を含めることができるため、引数を渡さない呼び出し元はdefaultにフォールバックします。
SQLクエリーまたはAI/BI dashboardからパラメーター値を渡すことができます。ダッシュボードで、閲覧者がランタイム時に値を選択できるように、パラメーターをフィルターウィジェットに接続します。「ダッシュボードでパラメーター化されたクエリーを使用する」を参照してください。
要件
- パラメーターを定義するメトリクスビューを作成するには、スキーマに対する
CREATE TABLEとUSE SCHEMAの権限、および親カタログに対するUSE CATALOGの権限が必要です。メトリクスビューを作成するために必要な権限の完全なリストについては、「メトリクスビューの作成」を参照してください。 - パラメーターを定義するメトリクスビューをクエリーするには、Databricks Runtime 18.2以降を実行するSQLウェアハウスまたはその他のコンピュートリソースが必要です。その他のバージョン要件については、「メトリクスビュー機能の利用可能性」を参照してください。
制限事項
パラメーターを定義するメトリクスビューには、次の制限が適用されます。
- パラメーターを定義するメトリクスビューをマテリアライズすることはできません。
- default値には制限があります。default値は、パラメーターの宣言されたデータ型にキャストできる必要があり、別のパラメーターを参照したり、サブクエリを含めたりすることはできません。1つのパラメーターにdefaultを設定した場合、それに続くすべてのパラメーターもdefaultを持つ必要があります。See パラメーター.
パラメーターを定義
パラメーターは、Catalog Explorerローコードエディタで、またはYAMLで直接定義できます。パラメーターを作成したら、定数SQL式が有効な場所ならどこでも、フィルター、フィールドとメジャーの式、ソース、結合などで名前で参照します。
YAMLでパラメーターを定義するには、メトリクス ビュー定義にトップレベルのparametersブロックを追加します。完全なフィールドリファレンスとYAMLの例については、パラメーターを参照してください。
以下のステップでは、カタログエクスプローラーのローコードエディターと、すべてのワークスペースで利用可能なsamples.tpch.ordersテーブルを使用して、discountパラメーターと2つのメジャーを持つメトリクスビューを構築します。1つのメジャーがパラメーターを適用し、もう1つが割引なしの合計を計算するため、2つを比較できます。
ステップ1: メトリクスビューを作成する
パラメーターとメジャーを保持するメトリクスビューを作成します。
- ワークスペースサイドバーの
カタログ をクリックし、検索バーを使用して samples.tpch.ordersを見つけてテーブル名をクリックします。 - 作成 > メトリクス・ビュー をクリックします。
- メトリクスビューの作成 ダイアログで、名前を入力し、メトリクスビューを作成するカタログとスキーマを選択します。 作成 をクリックします。
エディターは「UI」tabで開きます。 メトリクスビューエディターの詳しい手順については、メトリクスビューを作成するを参照してください。
ステップ 2：パラメーターの追加
数値型でdefault値を指定したdiscountパラメーターを追加します。
-
エディターのヘッダーで、「 パラメーターを追加 」をクリックします。
-
「 パラメーター詳細 」ダイアログで:
- 「 Name 」に
discountと入力します。 - 種類 ドロップダウンから 数値 を選択します。
- 表示される 数値型 ドロップダウンから、 倍精度浮動小数点数型 を選択します。
- 「 Name 」に
-
ダイアログから離れて閉じ、 discount のdefault値として
0.15を入力します。
パラメーターは、作成後にエディターのヘッダーに表示されます。ここで設定した値は、クエリーが引数を省略した場合に適用されるdefaultです。
ステップ3: パラメーターを使用するメジャーを追加します。
メジャー式でパラメーターを名前で参照してください。このメジャーは、各注文合計に割引を適用します。
-
エディターの上部にある「 Measures 」tabをクリックします。
-
[ + 追加 ] をクリックします。
-
メジャー名 として
Discounted Salesを入力します。 -
カスタム をクリックし、次の式を入力します。
SQLSUM((1 - discount) * source.o_totalprice)
ステップ 4：別のメジャーを追加
割引なしの合計の2つ目のメジャーを追加します。
- [ + 追加 ] をクリックします。
- メジャー名 として
Total Salesを入力します。 - Builder で、
source.o_totalpriceと Sum 集計を選択してSUM(source.o_totalprice)を生成します。
ステップ 5: メトリクスビューを保存します。
保存 をクリックします。メトリクスビューをクエリーし、discountパラメーターの値を渡す方法については、パラメーターを使用したメトリクスビューのクエリーを参照してください。
パラメーターを使用してメトリクスビューをクエリー
パラメーターを定義するメトリクスビューをクエリーするには、メトリクスビューをテーブル値関数として呼び出し、パラメーターを引数として渡します。引数を名前または位置で渡すことも、省略して default 値を使用することもできます。
名前で引数を渡す
名前で引数を渡すには、=>演算子を使用します。次の例では、discountの0.15値を渡します。
SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;
位置で引数を渡す
位置で引数を渡すには、パラメーターが定義されている順序で値をリストします。次の例では、0.15と同じdiscount値が渡されます。
SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;
デフォルトのパラメーター値を使用する
メトリクスビューを呼び出すときにdefaultのパラメーター値を使用するには、引数を省略します。次のクエリーは同等であり、すべてのdefault値を使用します。
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view() GROUP BY product;
SELECT product, MEASURE(discountedSales) FROM catalog.schema.metric_view GROUP BY product;
メトリクスビューが定義するパラメーターの表示
メトリクスビューが定義するパラメーターを確認するには、parametersブロックを含むYAML定義を表示します。メトリクスビューの定義とメタデータを表示を参照してください。
ダッシュボードでパラメーター化されたクエリーを使用する
これらのクエリーのいずれかを使用して、AI/BI dashboardでデータセットを定義できます。SQLデータセットでメトリクスビューを参照し、パラメーターをテーブル値関数の呼び出しの引数として渡します。ダッシュボードの閲覧者がランタイム時に値を選択できるようにするには、ダッシュボードのパラメーターを引数に渡し、フィルターウィジェットに接続します。「メトリクスビューにパラメーターを渡す」を参照してください。