ダッシュボードパラメーターの操作

この記事では、AI/BI ダッシュボードでパラメーターを使用する方法について説明します。代わりにフィールドフィルターについて学習する場合は、「フィールドでのフィルター」を参照してください。

AI/BIダッシュボードのパラメーターを使用すると、ランタイム時にデータセットクエリにさまざまな値を代入できます。これにより、SQL クエリでデータが集計される前に、日付や製品カテゴリなどの条件でデータをフィルタリングできるため、クエリの効率が向上し、分析が正確になります。パラメーターは、フィルターウィジェットと併用してダッシュボードをインタラクティブにしたり、視覚化ウィジェットと併用してデータセットを再利用しやすくしたりできます。

ダッシュボードの作成者または編集者は、データセットにパラメーターを追加し、ダッシュボードキャンバス上の 1 つ以上のウィジェットに接続します。視覚化ウィジェットで設定された静的パラメーターの場合、値は作成者または編集者によって設定されます。フィルターウィジェットで使用されるパラメーターの場合、ダッシュボードの閲覧者は、実行時にフィルターウィジェットの値を選択することでデータを操作できます。このインタラクションは、関連付けられたクエリを再実行し、フィルタリングされたデータに基づいてビジュアライゼーションを表示します。

パラメーターはクエリを直接変更するため、強力です。データセットフィールドフィルターは、パラメーターよりも大規模なデータセットでダッシュボードの対話性、より多くの機能、および優れたパフォーマンスを提供することもできます。「フィルターを使用する」を参照してください。

クエリにパラメーターを追加する

ダッシュボードデータセットにパラメーターを追加するには、ドラフトダッシュボードに対するCAN EDIT権限以上が必要です。 [データ]タブでデータセットのクエリに直接パラメーターを追加できます。

Gif は次のステップの例を示します。

クエリにパラメーターを追加するには:

クエリ内のパラメーターを配置する場所にカーソルを置きます。
[パラメーターを追加]をクリックし、新しいパラメーターを追加します。

これにより、デフォルト名parameterを持つ新しいコンテナーが作成されます。デフォルト名を変更するには、クエリエディターで置き換えます。クエリエディターでこの構文を入力して、パラメーターを追加することもできます。

クエリのパラメーターを編集する

パラメーターを編集するには:

パラメーター名の横にあるをクリックします。パラメーターの詳細ダイアログが表示され、次の構成オプションが含まれます。
- キーワード: クエリ内のパラメーターを表すキーワード。これは、クエリ内のテキストを直接更新することによってのみ変更できます。
- 表示名: フィルターエディターでの名前。デフォルトでは、タイトルはキーワードと同じになります。
- タイプ: サポートされているタイプには、文字列、日付、日付と時刻、数値が含まれます。
  - デフォルトタイプは文字列です。
  - 数値データ型では、Decimal と Integer のどちらかを指定できます。デフォルトの数値型はDecimalです。
- 複数選択を許可: このチェックボックスを選択すると、ユーザーはランタイムで複数のパラメーターを選択できます。
  
  注：
  
  この選択では、クエリに追加の変更が必要になる場合があります。「複数選択の許可」を参照してください。
UI の別の部分をクリックして、ダイアログを閉じます。

デフォルトパラメーターを設定する

クエリを実行するには、パラメーター名の下のテキストフィールドにデフォルト値を入力して、パラメーターのデフォルト値を選択します。クエリを実行して、パラメーター値が適用されたクエリ結果をプレビューします。クエリを実行すると、デフォルト値も保存されます。キャンバス上のフィルターウィジェットを使用してこのパラメーターを設定すると、フィルターウィジェットで新しいデフォルト値が指定されていない限り、デフォルト値が使用されます。「フィルターを使用する」を参照してください。

複数選択を許可する

複数の選択を許可するクエリには、クエリに ARRAY_CONTAINS 関数を含める必要があります。

次の例は、実行時にクエリに挿入する複数の値を選択できる SQL クエリを示しています。 WHERE 句では ARRAY_CONTAINS 関数を使用します。この関数は、パラメーターキーワードと列名を引数として受け取ります。クエリを実行すると、選択したパラメーター値を含むすべての行が返されます。

SELECT
  *
FROM
  samples.tpch.lineitem
WHERE array_contains(:parameter, l_quantity)

デフォルト値を設定するには、表示名の下のテキストフィールドに入力します。現在の値を選択してから、次の値を入力します。

デフォルト値はエディタで設定します。複数の値が選択され、スペースで区切られます。

日付範囲パラメーターの適用

パラメーターを使用して範囲を定義し、その範囲内の結果のみを返すことができます。次のいずれかのパラメーターの種類を選択すると、 .min と .max のサフィックスで指定される 2 つのパラメーターが作成されます。

日付範囲
日時範囲

次の例は、date_param という名前の日付範囲パラメーターを作成する SQL クエリを示しています。

SELECT * FROM samples.tpch.lineitem
WHERE l_shipdate BETWEEN :date_param.min and :date_param.max

日付範囲パラメーターを作成するには:

[パラメーターの追加] をクリックします。
パラメーター名の横にある [ ] をクリックします。 キーワードと表示名を入力します。.min や .max のサフィックスは含めないでください。
タイプとして [日付範囲] または [日付と時刻の範囲] を選択します。
範囲を定義する WHERE 句をクエリに挿入します。範囲を定義するには、.min と .max の値を持つ BETWEEN 句を使用します。例えば：
```
 WHERE date_col BETWEEN :date_param.min AND :date_param.max
```
デフォルトの日付値を入力し、クエリを実行してテストします。カレンダーアイコンを使用して、先週や先月などのプリセットオプションを選択します。

クエリベースのパラメーター

クエリベースのパラメーターを使用すると、作成者は、閲覧者がダッシュボードでデータを探索する際におけるパラメーターの設定で選択できる値の動的または静的なリストを定義できます。これらは、フィールドフィルターとパラメーターフィルターを 1 つのフィルターウィジェットに組み合わせて定義されます。

クエリベースのパラメーターを作成するには、ダッシュボード作成者は次の手順を実行します。

可能なパラメータ値のリストに限定されたデータセットを作成します。
パラメーターを使用するデータセットクエリーを作成します。
キャンバス上でフィールドをフィルタリングし、パラメーターを使用するフィルタウィジェットを設定します。
- フィールド構成は、適切な引数値の必要なリストを持つパラメーター値を使用するように設定する必要があります。
- 値を選択するには、構成を設定する必要があります。

注：

クエリベースのパラメーターで使用されるデータセットがダッシュボード上の他のビジュアライゼーションでも使用されている場合、閲覧者のフィルター選択によって、接続されているすべてのクエリが変更されます。これを回避するには、作成者はダッシュボード上の他のビジュアライゼーションでは使用されない、クエリベースのパラメーター専用のデータセットを作成する必要があります。

クエリベースのパラメーターとビジュアライゼーションを追加する方法を示すステップバイステップのチュートリアルについては、「クエリベースのパラメーターの使用」を参照してください。

動的パラメーターのリストを作成する

ビューアーがパラメーター値を選択するために使用するドロップダウンに入力する動的データセットを作成するには、1 つのフィールドを返し、そのフィールド内のすべての値を含む SQL クエリを記述します。そのフィールドの新しい値は、パラメーター選択として自動的に追加されます。 SQL クエリの例を次に示します。

 SELECT
    DISTINCT c_mktsegment
  FROM
    samples.tpch.customer

静的パラメーターのリストを作成する

データセットにハードコーディングした値のみを含む静的データセットを作成できます。クエリの例を次に示します。

SELECT
  *
FROM
  (
    VALUES
      ('MACHINERY'),
      ('BUILDING'),
      ('FURNITURE'),
      ('HOUSEHOLD'),
      ('AUTOMOBILE')
  ) AS data(available_choices)

クエリパラメーターを削除する

パラメーターを削除するには、クエリからパラメーターを削除します。

静的ウィジェット

静的ウィジェットは可視化ウィジェット内で直接設定されるため、作成者は同じデータセットを共有する可視化ウィジェットを個別にパラメータ化できます。これにより、同じデータセットでキャンバス上に異なるビューを表示できるようになります。

このセクションの例は、 samples.nyctaxi.trips テーブルをクエリするデータセットに基づいています。指定されたクエリは、各移動の距離を返し、集荷日を Weekday または Weekendに分類します。 query パラメーターは、ピックアップが平日と週末のどちらに発生したかに基づいて結果をフィルター処理します。

クエリテキストは次のコードブロックで提供されていますが、このセクションの手順は、静的ウィジェットパラメーターで構成された関連する視覚化の設定に限定されています。パラメーターを使用してデータセットを設定する手順については、「クエリにパラメーターを追加する」を参照してください。

  WITH DayType AS (
    SELECT
      CASE
        WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
        ELSE 'Weekday'
      END AS day_type,
      trip_distance
    FROM samples.nyctaxi.trips
  )
  SELECT day_type, trip_distance
  FROM DayType
  WHERE day_type = :day_type_param

静的ウィジェットをビジュアライゼーションに追加するには:

ビジュアライゼーションウィジェットをドラフトダッシュボードキャンバスに追加します。
新しいウィジェットを選択した状態で、構成パネルの [データセット ] ドロップダウンからパラメーター化されたデータセットを選択します。
[ フィルターを表示] をクリックします。パラメーターを含むデータセットの場合、 パラメーター ・セクションが構成パネルに表示されます。
「パラメーター」見出しの右側にあるプラス記号をクリックし、ドロップダウンから「パラメーター」を選択します。
デフォルトでは、パラメーターの値は[データ]タブのクエリに設定されている内容を反映しています。それをそのままにしておくか、データセットに代入する新しい値を選択できます。テキストフィールドから移動して、新しいパラメーターが適用された視覚化を表示します。
ダッシュボードを確認します。

次の図は、2 つの視覚化ウィジェットを示しています。それぞれが、静的ウィジェットパラメーターを持つヒストグラムとして構成されます。左側のグラフは、平日から始まる移動の移動距離の分布を示し、右側のグラフは週末の同じデータを示しています。どちらのビジュアライゼーションも同じデータセットに基づいています。

フィルター条件を使用したデータの比較

データ部分の集計をデータセット全体に適用された集計と比較できるフィルター条件を追加できます。

次の例では、前のクエリを拡張して、指定したパラメーター値が Allであるフィルター条件を含めます。この値はデータには表示されません。フィルター条件の最初の部分は、前の例と同じように機能し、 day_type が Weekday または Weekendである結果をフィルター処理します。フィルター条件の 2 番目の部分では、パラメーター自体がデータに表示されない特定の値 (この場合は All) に設定されているかどうかを確認します。データセットエディターでそのパラメーターのデフォルト値を設定すると、 Weekday も Weekend も値として渡されない場合に、フィルターが実質的にバイパスされます。

WITH DayType AS (
  SELECT
    CASE
      WHEN DAYOFWEEK(tpep_pickup_datetime) IN (1, 7) THEN 'Weekend'
      ELSE 'Weekday'
    END AS day_type,
    trip_distance
  FROM
    samples.nyctaxi.trips
)
SELECT
  day_type,
  trip_distance
FROM
  DayType
WHERE
  day_type = :day_type_param
  OR :day_type_param = 'All'

このデータセットを使用して、 day_type_param をそれぞれ [ All]、[ Weekday ]、および [ Weekend ] に設定した 3 つの視覚化ウィジェットを構成できます。その後、ダッシュボードの閲覧者は、日の種類でフィルター処理された各データセットをデータセット全体と比較できます。

次の GIF は、このクエリで作成されたデータセットから 3 つのグラフをすばやく作成する方法を示しています。

最初のチャートは、パラメーター値が Weekday に設定された Trip Distances by Day Type データセットを表示するように構成されています。
グラフを複製して、適用されたすべての設定を維持します。
週末に行った旅行のデータを表示するには、静的パラメーターを Weekend に調整します。
新しいチャートを複製して、以前に適用したすべての設定を維持します。
新しいグラフのパラメーターを [すべて ] に設定すると、週末と平日の移動の距離別の移動回数の合計が表示されます。

ダッシュボードにパラメーターを表示する

ダッシュボードキャンバスにフィルターを追加すると、閲覧者はパラメーター値を選択および変更して、データを対話形式で探索および分析できます。ダッシュボードでパラメーターを公開しない場合、ビューアーには、クエリで設定したデフォルトパラメーター値を使用するクエリ結果のみが表示されます。

パラメーターをダッシュボードに追加するには:

フィルター（フィールド/パラメーター）を追加するをクリックします。
コンフィギュレーションパネルにあるの隣のパラメーターをクリックします。
このウィジェットでビューアが使用するパラメーター名をクリックします。

フィルターウィジェットと静的パラメーターの操作

パラメーターは、実行時にクエリに置き換えられる固定値です。ダッシュボードの更新時に、同じパラメーターへの 2 つ以上の参照が異なる値で設定されている場合、ビジュアライゼーションウィジェットには、どのパラメーターに競合する値があるかを示すエラーが表示されます。これは、複数のフィルターウィジェットが同じパラメーターを使用している場合、または静的パラメーターがビューアーの選択を許可するフィルターウィジェットと競合する場合に発生する可能性があります。

次の例のようなパターンを使用して、同じクエリ内の異なるパラメーターのフォールバック値を設定できます。

CASE WHEN :static_param != 'All' THEN :static_param ELSE :dash_param END

この例では、 :static_param は静的パラメーターを参照しており、視覚化ウィジェットとデータセットエディターの両方で 'All' に設定する必要があります。パラメーター :dash_param は、ダッシュボードキャンバス上のフィルターウィジェットによって制御される動的な値です。この文は、静的パラメータとして指定された値をチェックします。何も設定されていない場合は、ビューアーが選択したダッシュボードパラメーターの値にフォールバックします。

URLにパラメーターを含める

パラメーターの設定は URL に格納されるため、ユーザーは URL をブックマークして、事前設定されたフィルターやパラメーターなどのダッシュボードの状態を維持したり、他のユーザーと共有して同じフィルターやパラメーターを一貫して適用したりできます。

ダッシュボードのパラメーターと Mustache クエリのパラメーター

Dashboard パラメーターは、名前付きパラメーターマーカーと同じ構文を使用します。名前付きパラメーターマーカーを参照してください。ダッシュボードは、Mustache スタイルのパラメーターをサポートしていません。

構文の例

パラメーターの一般的な用途には、日付、数値、テキスト、データベースオブジェクト、 JSON 文字列からの値の挿入などがあります。このような場合にパラメーターを使用する方法を示す例については、「名前付きパラメーターの構文例」を参照してください。

重要

ビューアーがテーブル名やカタログ名などのパラメーター選択を通じてデータにアクセスできるようにすると、機密情報が誤って公開される可能性があります。これらのオプションを使用してダッシュボードを発行する場合、Databricks では、公開されたダッシュボードに資格情報を埋め込まないことをお勧めします。

ダッシュボード パラメーターの操作