次の方法で共有

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

  • [アーティクル]

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

AI/BI ダッシュボードのパラメーターを使用すると、実行時にデータセット クエリに複数の値を代入できます。 これにより、データが SQL クエリで集計される前に、日付や製品カテゴリなどの抽出条件によりデータをフィルター処理することができ、より効率的なクエリと正確な分析が可能になります。 パラメーターをフィルター ウィジェットと共に使用して、ダッシュボードを対話型にしたり、視覚エフェクトウィジェットを使用してデータセットを再利用しやすくしたりできます。

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

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

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

ダッシュボード データセットにパラメーターを追加するには、下書きダッシュボードに少なくとも編集可能アクセス許可が必要です。 [データ] タブのデータセット クエリに直接パラメーターを追加できます。

Gif は次の手順の例を示しています。

クエリにパラメーターを追加するには、次の操作を行います。

  1. パラメーターをクエリに配置する場所にカーソルを配置します。

  2. 新しいパラメーターを挿入するには、[パラメーターの追加] をクリックします。

    これは、既定の名前の parameter を用いて新しいパラメーターを作成します。 既定の名前を変更するには、クエリ エディターでその名前を置き換えます。 クエリ エディターにこの構文を入力してパラメーターを追加することもできます。

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

パラメーターを編集するには、次の操作を行います。

  1. パラメーター名の横の 歯車アイコン をクリックします。 [パラメーターの詳細] ダイアログが表示され、次の構成オプションが記載されます。

    • キーワード: クエリ内のパラメーターを表すキーワード。 これは、クエリ内のテキストを直接更新することによってのみ変更できます。

    • 表示名: フィルター エディターの名前。 既定では、タイトルはキーワードと同じです。

    • 型: String、Date、Date and Time、Numeric がサポートされています。

      • 既定の型は String です。
      • Numeric データ型では、Decimal と Integer の間を指定できます。 既定の数値型は Decimal です。

    • 複数の選択を許可する: 実行時にユーザーが複数のパラメーターを選択できるようにするには、チェック ボックスをオンにします。

      Note

      この選択には、クエリの追加の変更が必要になる場合があります。 「 複数の選択項目を適用するを参照してください。

  2. ダイアログを閉じるには、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

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

  1. [パラメーター 追加] をクリックします。

  2. パラメーター名の横の 歯車アイコン をクリックします。 KeywordとDisplay 名を入力。 .minまたは.maxサフィックスは含めないでください。

  3. タイプとして日付範囲または日付と時間範囲を選択。

  4. 範囲を定義する WHERE 句をクエリに挿入します。 範囲を定義するには、.min値と.max値を含むBETWEEN句を使用します。 次に例を示します。

     WHERE date_col BETWEEN :date_param.min AND :date_param.max

  5. 既定の日付値を入力し、クエリを実行してテストします。 カレンダー アイコンを使用して、先週や先月などのプリセット オプションを選択します。

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

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

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

  1. 結果セットが使用可能なパラメーター値のリストに制限されているデータセットを作成します。
  2. パラメーターを使用するデータセット クエリを作成します。
  3. フィールドをフィルター処理し、パラメーターを使用するフィルター ウィジェットをキャンバスに構成します。
    • フィールドの構成は、対象となるパラメーター値の希望するリストと共にフィールドを使用するように設定する必要があります。
    • パラメーター値を選択するには、パラメーター構成を設定する必要があります。

Note

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

クエリ ベースのパラメーターと視覚化を追加する方法を示す段階的なチュートリアルについては、「クエリ ベースのパラメーターを使用する」をご覧ください。

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

ビューアーがパラメーター値の選択に使用するドロップダウンを設定する動的データセットを作成するには、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

静的ウィジェット パラメーターを視覚エフェクトに追加するには:

  1. 下書きダッシュボード キャンバスに視覚エフェクト ウィジェットを追加します。

  2. 新しいウィジェットが選択されたら、構成パネルの データセット ドロップダウンからパラメーター化されたデータセットを選択します。

  3. [フィルターの表示 ] をクリック。 パラメーターを含むデータセットの場合、構成パネルに Parameters セクションが表示されます。

    パラメーターを選択するオプションを示す視覚エフェクト構成パネル。

  4. パラメーター見出しの右側にある正符号をクリックし、ドロップダウンからパラメーターを選択します。

  5. 既定では、パラメーター値は [データ] タブのクエリで設定されたものを反映します。この値を保持することも、データセットに置き換える新しい値を選択することもできます。 テキスト フィールドから移動して、新しいパラメーターが適用された視覚エフェクトを表示します。

  6. ダッシュボードをレビューします。

    次の図は、2 つの視覚化ウィジェットを示しています。 それぞれは、静的ウィジェット パラメーターを使用してヒストグラムとして構成されます。 左側のグラフは平日から始まる乗車距離の分布を示し、右側のグラフには週末の同じデータが表示されます。 どちらの視覚エフェクトも同じデータセットに基づいています。

    説明されているように、静的ウィジェット レベルのパラメーターを使用するように構成された 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 つのグラフをすばやく作成する方法が示されています。

  1. 最初のグラフは、パラメーター値が「平日」に設定された「日にちの種類による旅の距離」データセットを表示するように構成されています。
  2. グラフをクローンして適用されたすべての構成を維持します。
  3. 週末に行った旅のデータを表示するには、静的パラメーターを「週末」に調整します。
  4. 新しいグラフのクローンを作成して、以前に適用されたすべての構成を維持します。
  5. 新しいグラフのパラメーターを [すべて] に設定すると、週末と平日の旅行の合計旅行数が距離で表示されます。

前のテキストで説明した gif。

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

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

ダッシュボードにパラメーターを追加するには、次の操作を行います。

  1. フィルター アイコン [フィルターの追加 (フィールド/パラメーター)] をクリックします。
  2. 構成パネルの [パラメーター] の横にある [フィールドの追加] アイコン をクリックします。
  3. このウィジェットでビューアーが使用するパラメーター名をクリックします。

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

パラメーターは、実行時にクエリに代入する固定値です。 ダッシュボードの更新時に同じパラメーターへの 2 つ以上のリファレンスが異なる値で設定されている場合、視覚化ウィジェットには、競合する値を持つパラメーターを示すエラーが表示されます。 これは、複数のフィルター ウィジェットが同じパラメーターを使用する場合、または静的パラメーターがビューアーの選択を許可するフィルター ウィジェットと競合する場合に発生する可能性があります。

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


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

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

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

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

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

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

構文の例

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

重要

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