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

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

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

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

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

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

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

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

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

  2. [パラメーターを追加]をクリックし、新しいパラメーターを追加します。

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

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

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

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

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

    • 表示名: フィルター エディターでの名前。 デフォルトでは、タイトルはキーワードと同じになります。

    • タイプ: サポートされているタイプには、文字列、日付、日付と時刻、数値が含まれます。

      • デフォルトタイプは文字列です。

      • 数値データ型では、Decimal と Integer のどちらかを指定できます。デフォルトの数値型はDecimalです。

  2. UI の別の部分をクリックして、ダイアログを閉じます。

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

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

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

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

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

  1. 可能なパラメータ値のリストに限定されたデータセットを作成します。

  2. パラメーターを使用するデータセットクエリーを作成します。

  3. キャンバス上でフィールドをフィルタリングし、パラメーターを使用するフィルタウィジェットを設定します。

    • フィールド構成は、適切な引数値の必要なリストを持つパラメーター値を使用するように設定する必要があります。

    • 値を選択するには、構成を設定する必要があります。

注：

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

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

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

閲覧者がパラメーターの値を選択するために使用するドロップダウンにデータを入力する動的なデータセットを作成するには、単一のフィールドを返し、そのフィールド内のすべての値を含める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. 「問題」見出しの右側にあるプラス記号をクリックし、ドロップダウンから「問題」を選択します。

  4. 間違いなく、問題の値は[データ]タブのクエリに設定されている内容を反映しています。 それをそのままにしておくか、データセットに代入する新しい値を選択できます。 テキスト フィールドから移動して、新しいパラメーターが適用された視覚化を表示します。

  5. ダッシュボードを確認します。

    次の画像は、それぞれが静的ウィジェットを持つヒストグラムとして構成された 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. 最初のチャートは、パラメーター値が Weekday に設定された Trip Distances by Day Type データセットを表示するように構成されています。

  2. グラフを複製して、適用されたすべての設定を維持します。

  3. 週末に行った旅行のデータを表示するには、静的パラメーターを Weekend に調整します。

  4. [生成] を選択すると、クローン操作で 3 番目のグラフが生成されます。

  5. パラメーター All を設定して、週末と平日の移動の距離別の移動回数の合計を表示します。

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

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

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

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

  1. フィルター アイコンフィルター（フィールド/パラメーター）を追加するをクリックします。

  2. コンフィギュレーションパネルにある[フィールドの追加] アイコンの隣のパラメーターをクリックします。

  3. このウィジェットでビューアが使用するパラメーター名をクリックします。

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フィールドが指定された引数値より大きいレコードに結果を制限するNumericTextが含まれています。

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

フィールド名を挿入する

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

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

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

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

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

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

重要

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

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

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

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

JSON 文字列の操作

パラメーターを使用して、 JSON 文字列から属性を抽出できます。 次の例では、 'from_json' 関数 を使用して JSON 文字列を構造体値に変換します。 文字列 a をパラメーター (param) の値に置き換えると、属性 1 が返されます。

SELECT
  from_json('{"a": 1}', 'map<string, int>') [:param]

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

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

構文の変更

次の表は、問題の一般的な使用例、元のDatabricks SQL構文、および名前付きマーカー構文を使用した同等の構文を示しています。

使用例

Databricks SQL 構文

AI/BIダッシュボードの構文

指定した日付より前のデータのみをロードする

WHERE date_field < '{{date_param}}'

日付を引用符で囲み、中括弧を含める必要があります。

WHERE date_field < :date_param

指定した数値より小さいデータのみをロードする

WHERE price < {{max_price}}

WHERE price < :max_price

2つの文字列を比較する

WHERE region = {{region_param}}

WHERE region = :region_param

クエリで使用するテーブルを指定します

SELECT * FROM {{table_name}}

SELECT * FROM IDENTIFIER(:table)

ユーザーがこの引数を入力するときは、完全な 3 レベルの名前空間を使用してテーブルを識別する必要があります。

クエリで使用されるカタログ、スキーマ、およびテーブルを個別に指定します

SELECT * FROM {{catalog}}.{{schema}}.{{table}}

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

より長い書式設定された文字列のテンプレートとして「問題」を使用する

"({{area_code}}) {{phone_number}}"

問題値は文字列として自動的に連結されます。

format_string("(%d)%d, :area_code, :p hone_number)

完全な例については、「複数の問題を連結する」を参照してください。