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

プレビュー

この機能はパブリックプレビュー段階です。

AI/BIダッシュボードは、ダッシュボードをインタラクティブにする 1 つの方法であり、閲覧者が単一値セレクターと日付ピッカーを使用できるようにします。 たとえば、 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)

フィルターの種類

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

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

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

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

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

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

  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)

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

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