メトリック ビューでパラメーターを使用する

パラメーターを使用すると、クエリを実行するときにメトリック ビューに値を渡すことができます。 パラメーターを使用して、割引率や日付ウィンドウなど、さまざまな入力で 1 つの メトリック ビュー 定義を再利用します。 フィルター、フィールド式、メジャー式、ソース、結合など、定数 SQL 式が有効な任意の場所でパラメーターを参照します。 また、整数パラメータをウィンドウ指標の range や offsetの値として参照することもでき、クエリ時に呼び出し側がウィンドウサイズを渡すこともできます。 ビューのクエリを実行するときに、値を引数として渡します。

パラメーターは重複を減らします。 バリアントごとに個別のメトリック ビューを保持する代わりに、ロジックを 1 回定義し、呼び出し元ごとに独自の値を指定します。 パラメーターには既定値を含めることができるため、引数を渡さない呼び出し元は既定値にフォールバックします。

パラメーター値は、SQL クエリまたは AI/BI ダッシュボードから渡すことができます。 ダッシュボードで、パラメーターをフィルター ウィジェットに接続して、ビューアーが実行時に値を選択できるようにします。 「ダッシュボードでパラメーター化されたクエリを使用する」を参照してください。

必要条件

• パラメーターを定義するメトリック ビューを作成するには、スキーマに対する CREATE TABLE 権限と USE SCHEMA 権限、および親カタログに対する USE CATALOG 権限が必要です。 メトリック ビューの作成に必要な権限の完全な一覧については、「 メトリック ビューの作成」を参照してください。
• パラメーターを定義するメトリック ビューに対してクエリを実行するには、Databricks Runtime 18.2 以降を実行している SQL ウェアハウスまたはその他のコンピューティング リソースが必要です。 バージョン要件の詳細については、 メトリック ビュー機能の可用性に関する記事を参照してください。

Limitations

パラメーターを定義するメトリック ビューには、次の制限事項が適用されます。

• パラメーターを定義するメトリック ビューを具体化することはできません。
• 既定値には制限があります。 既定値は、パラメーターの宣言されたデータ型にキャスト可能である必要があり、別のパラメーターを参照したり、サブクエリを含めたりすることはできません。 1 つのパラメーターに既定値を設定する場合は、それに続くすべてのパラメーターにも既定値が必要です。 「パラメーター」を参照してください。

パラメーターを定義する

パラメーターは、カタログ エクスプローラーのローコード エディターで定義することも、YAML で直接定義することもできます。 パラメーターを作成したら、フィルター、フィールド、メジャー式、ソース、結合など、定数 SQL 式が有効な任意の場所で名前で参照します。 また、整数パラメータをウィンドウの測度の range や offsetの値として参照することもできます。 「ウィンドウの寸法」を参照してください。

YAML でパラメーターを定義するには、最上位レベルの parameters ブロックをメトリック ビュー定義に追加します。 完全なフィールド リファレンスと YAML の例については、「 パラメーター」を参照してください。

次の手順では、カタログ エクスプローラーのローコード エディターと、すべてのワークスペースで使用できる samples.tpch.orders テーブルを使用して、 discount パラメーターと 2 つのメジャーを含むメトリック ビューを作成します。 1 つのメジャーでパラメーターが適用され、もう 1 つのメジャーで計算されていない合計が計算されるため、2 つを比較できます。

手順 1: メトリック ビューを作成する

パラメーターとメジャーを保持するメトリック ビューを作成します。

1. [ワークスペースのサイドバーでカタログを作成し、検索バーを使用してsamples.tpch.ordersを検索し、テーブル名をクリックします。
2. [ 作成>メトリック ビュー] をクリックします。
3. [ メトリック ビューの作成 ] ダイアログで名前を入力し、メトリック ビューを作成するカタログとスキーマを選択します。 Create をクリックしてください。

エディターが UI タブで開きます。メトリック ビュー エディターの完全なチュートリアルについては、「メトリック ビューの作成」を参照してください。

手順 2: パラメーターを追加する

数値型と既定値を持つ discount パラメーターを追加します。

1. エディターの見出しで、[ パラメーターの追加] をクリックします。

2. [ パラメーターの詳細 ] ダイアログで、次の手順を実行します。

   1. discount] に「」と入力します。
   2. [種類] ドロップダウンから [数値] を選択します。
   3. 表示される [数値の種類] ドロップダウンから [Double] を選択します。

   

3. ダイアログから離れてクリックして閉じ、0.15の既定値として「」と入力します。

   

パラメーターは、作成後にエディターの見出しに表示されます。 ここで設定する値は、クエリが引数を省略したときに適用される既定値です。

手順 3: パラメーターを使用するメジャーを追加する

メジャー式では、パラメーターを名前で参照します。 この指標は、各注文の合計金額に割引を適用します。

1. エディター上部にある測定値タブをクリックします。

2. [+ 追加] をクリックします。

3. Discounted Salesとしてを入力します。

4. [ カスタム] をクリックし、次の式を入力します。

   SUM((1 - discount) * source.o_totalprice)
   

手順 4: 別のメジャーを追加する

割引前合計を算出する 2 つ目のメジャーを追加します。

1. [+ 追加] をクリックします。
2. Total Salesとしてを入力します。
3. Builder で、source.o_totalpriceと合計集計を選択して、SUM(source.o_totalprice)を生成します。

手順 5: メトリック ビューを保存する

保存 をクリックします。 メトリック ビューのクエリを実行し、 discount パラメーターの値を渡すには、「パラメーターを 使用したメトリック ビューのクエリ」を参照してください。

パラメーターを使用してメトリック ビューにクエリを実行する

パラメーターを定義するメトリック ビューにクエリを実行するには、メトリック ビューをテーブル値関数として呼び出し、パラメーターを引数として渡します。 引数は、名前または位置で渡すか、既定値を使用するために省略できます。

名前で引数を渡す

引数を名前で渡すには、 => 演算子を使用します。 次の例では、discountの0.15値を渡します。

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(discount => 0.15)
GROUP BY product;

引数を位置で渡す

引数を位置で渡すには、パラメーターが定義されている順序で値を一覧表示します。 次の例では、discountと同じ0.15値を渡します。

SELECT product, MEASURE(discountedSales)
FROM catalog.schema.metric_view(0.15)
GROUP BY product;

既定のパラメーター値を使用する

メトリック ビューを呼び出すときに既定のパラメーター値を使用するには、引数を省略します。 次のクエリは同等であり、すべての既定値を使用します。

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 ダッシュボードでデータセットを定義できます。 SQL データセットのメトリック ビューを参照し、テーブル値関数呼び出しでパラメーターを引数として渡します。 ダッシュボード ビューアーが実行時に値を選択できるようにするには、ダッシュボード パラメーターを引数に渡し、フィルター ウィジェットに接続します。 「パラメーターをメトリック ビューに渡す」を参照してください。

その他のリソース

• メトリック ビューを作成する
• メトリック ビューのクエリ
• パラメーター