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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

クエリベースのパラメーターを使用すると、作成者は、閲覧者がダッシュボードでデータを探索する際におけるパラメーターの設定で選択できる値の動的または静的なリストを定義できます。これらは、フィールドフィルターとパラメーターフィルターを 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に分類します。クエリは、ピックアップが平日か週末のどちらに発生したかに基づいて結果をフィルター処理します。

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

  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に保存されるため、ユーザーはそれをブックマークして、事前設定されたフィルターやパラメーターを含むダッシュボードの状態を維持したり、同じフィルターやパラメーターを一貫して適用するために他のユーザーと共有したりできます。

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

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

構文の例

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

重要

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

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