Share via

ダッシュボード パラメーターとは

  • [アーティクル]

ダッシュボード パラメーターは、ダッシュボードを対話的にする方法の 1 つで、ビューアーが単一値セレクターや日付ピッカーを使用して、実行時にデータセット クエリに特定の値を入力できるようにします。 たとえば、SQL クエリで集計する前に、日付や製品カテゴリなどの条件に基づいてパラメーターでデータをフィルター処理することができ、より効率的なクエリと正確な分析が可能になります。

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

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

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

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

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

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

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

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

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

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

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

  1. パラメーター名の横の 歯車アイコン をクリックします。 [パラメーターの詳細] ダイアログが表示され、次の構成オプションがあります。
    • キーワード: クエリ内のパラメーターを表すキーワード。 これは、クエリ内のテキストを直接更新することによってのみ変更できます。
    • 表示名: フィルター エディターの名前。 既定では、タイトルはキーワードと同じです。
    • 型: String、Date、Date and Time、Numeric がサポートされています。
      • 既定の型は String です。
      • Numeric データ型では、Decimal と Integer の間を指定できます。 既定の数値型は Decimal です。
  2. ダイアログを閉じるには、UI の他の部分をクリックします。

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

パラメーターの既定値は、パラメーター名の下のテキスト フィールドに入力することで設定できます。 クエリを実行して、パラメーター値が適用されたクエリ結果をプレビューします。 クエリを実行すると、既定値も保存されます。 キャンバス上のフィルター ウィジェットを使用してこのパラメーターを設定すると、既定値が使用されます。

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

クエリベースのパラメーターを使用すると、作成者はダッシュボードでデータを探索する場合に選択できる動的または静的な値のリストを定義できます。 クエリ ベースのパラメーターを作成するには、ダッシュボードの作成者は次の手順を実行します。

  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)

フィルター タイプ

単一値と日付の選択フィルターでは、パラメーターの設定がサポートされます。 日付の選択フィルター を使用してクエリベースのパラメーターを設定すると、基になるクエリの結果に表示される日付は黒で表示されます。 クエリ結果に表示されない日付は灰色で表示されます。 基になるクエリに含まれていない場合でも、ユーザーは灰色の日付を選択できます。

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

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

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

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

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

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

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

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

パラメーター構文の例

次の例では、パラメーターの一般的なユース ケースをいくつか示します。

日付を挿入する

次の例には、クエリ結果を特定の日付より後のレコードに制限する Date パラメーターが含まれています。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  sum(o_totalprice) AS `Total Price`
FROM
  samples.tpch.orders
WHERE
  o_orderdate > :date_param
GROUP BY
  1,
  2

数値を挿入する

次の例には、o_total_price フィールドが指定されたパラメーター値より大きいレコードに結果を制限する Numeric パラメーターが含まれています。


SELECT
  o_orderdate AS Date,
  o_orderpriority AS Priority,
  o_totalprice AS Price
FROM
  samples.tpch.orders
WHERE
  o_totalprice > :num_param

フィールド名を挿入する

次の例では、IDENTIFIER 関数と共に field_param を使用して、実行時にクエリのしきい値を指定します。 パラメーター値は、クエリで使用されるテーブルの列名にする必要があります。


SELECT
  *
FROM
  samples.tpch.orders
WHERE
  IDENTIFIER(:field_param) < 10000

データベース オブジェクトを挿入する

次の例では、3 つのパラメーター catalog、schema、table を作成します。 ダッシュボード閲覧者は、キャンバス上のフィルター ウィジェットを使用して、パラメーター値を選択できます。


SELECT
  *
FROM
  IDENTIFIER(:catalog || '.' || :schema || '.' || :table)

「IDENTIFIER 句」を参照してください。

重要

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

複数のパラメーターを連結する

他の SQL 関数にパラメーターを含めることができます。 この例では、閲覧者が従業員の役職と番号 ID を選択できるようにします。 このクエリでは、format_string 関数を使用して 2 つの文字列を連結し、一致する行をフィルター処理します。 「format_string 関数」を参照してください。


SELECT
  o_orderkey,
  o_clerk
FROM
  samples.tpch.orders
WHERE
  o_clerk LIKE format_string('%s%s', :title, :emp_number)

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

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