パラメータ ウィジェットを操作する

名前付きパラメーター マーカーをクエリに追加すると、Azure Databricks によって UI にパラメーター ウィジェットが表示されます。 ウィジェットを使用すると、ユーザーはクエリを直接編集せずにパラメーター値を設定できます。 各ウィジェットの種類、タイトル、既定値を構成できます。

パラメーター ウィジェットは、SQL エディター、ノートブック、AI/BI ダッシュボード、Genie スペースでサポートされていますが、これらのサーフェスでは動作が異なります。 このページでは、SQL エディターのパラメーター ウィジェットについて説明します。 その他のサーフェスについては、次を参照してください。

• ダッシュボードのパラメーターを操作する
• Genie スペースの SQL クエリでパラメーターを使用する
• ノートブック用の Databricks ウィジェット

SQL エディターでは、任意のパラメーター型 (String、Integer、Decimal、Date、Timestamp) で任意のウィジェット型を使用できます。

パラメーター ウィジェットを構成する

1. 名前付きパラメーター マーカーをクエリに追加します。 ウィジェットが UI に表示されます。
2. ウィジェットの横にある歯車アイコンをクリックして、ウィジェット ダイアログを開きます。
3. 次のフィールドを設定します。
   • パラメーター名: クエリに表示されるパラメーター名。 パラメーター名を変更する場合は、ウィジェット ダイアログでクエリでも変更する必要があります。
   • ウィジェット ラベル: ウィジェットを記述した文字列
   • ウィジェットの種類: ユーザーが値を入力する方法を制御します。 以下の ウィジェットの種類 を参照してください。
   • パラメーター型: パラメーター データ型。 「パラメーターの型」を参照してください。
4. ウィジェット ダイアログから離れた場所をクリックして変更を保存します。

ウィジェットの編集、削除、並べ替え

編集: ウィジェットの横にある歯車アイコンをクリックして、設定ウィンドウを再度開きます。

削除: クエリからパラメーター マーカーを削除します。 ウィジェットは自動的に削除されます。

並べ替え: ウィジェットの左側にあるドラッグ ハンドルを使用して並べ替えます。

ウィジェットの種類

Azure Databricks では、クエリ パラメーターに対して次のウィジェットの種類がサポートされています。

テキスト入力

自由形式の値をユーザーから直接受け入れます。 定義済みのオプションが必要ない場合は、このウィジェットを使用します。

SELECT * FROM samples.tpch.region WHERE r_name = :region_param

ドロップダウン

定義済みの値の一覧を表示します。 ユーザーはリストから選択する必要があります。自由形式の入力は許可されていません。 設定ウィンドウに、1 行に 1 つずつ、使用できる値を入力します。

SELECT * FROM samples.tpch.orders WHERE o_orderstatus = :status_param

ドロップダウン ウィジェットの種類を作成するには:

1. :status_param ウィジェットの横にある歯車アイコンをクリックします。
2. ウィジェットの種類をドロップダウンに設定します。
3. パラメーターの型を文字列に設定します。
4. [パラメーター値の選択肢] テキスト入力フィールドに値を入力します。 [ 追加] をクリックするか、各値の間で Enter キーを押します。

コンボボックス

推奨値の定義済みリストを表示しますが、ユーザーはリストにないカスタム値を入力することもできます。 一般的なオプションが便利で、自由形式の入力を許可する場合は、コンボ ボックスを使用します。

SELECT * FROM samples.tpch.part WHERE p_brand = :brand_param

複数選択

ユーザーが定義済みのリストから複数の値を選択できるようにします。 選択した値は、コレクションとしてクエリに渡されます。

SELECT * FROM samples.nyctaxi.trips WHERE
  array_contains(
    TRANSFORM(SPLIT(:list_parameter, ','), s -> TRIM(s)),
    CAST(dropoff_zip AS STRING)
  )

複数選択ドロップダウン リストのオプションを追加するには:

1. list_parameter ウィジェットの横にある歯車アイコンをクリックします。
2. [ウィジェットの種類] を [複数選択] に設定します。
3. パラメーターの型を文字列に設定します。
4. [パラメーター値の選択肢] テキスト入力フィールドに値を入力します。 [ 追加] をクリックするか、各値の間で Enter キーを押します。

動的ドロップダウンメニュー

静的リストではなく、保存されたクエリの選択肢の一覧を設定します。 基になるデータが変更されると、使用可能なオプションが自動的に更新されます。

動的ドロップダウンを使用するには:

1. ドロップダウンに必要な値を返すクエリを作成して保存します。

   SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment
   

2. 新規または既存のクエリで、名前付きパラメーター マーカーを追加します。

   SELECT c_custkey, c_name, c_acctbal
   FROM samples.tpch.customer
   WHERE c_mktsegment = :segment_param
   

3. segment_param ウィジェットの横にある歯車アイコンをクリックします。

4. [ウィジェットの種類] を [動的] ドロップダウンに設定します。

5. [ クエリ ] フィールドをクリックして、[ 既存のクエリの選択 ] ダイアログを開きます。 手順 1 で保存したクエリを選択し、[ 選択] をクリックします。

6. 既定の パラメーター値を選択します。

7. [変更の適用] をクリックします。

日付とタイムスタンプの範囲

日付とタイムスタンプのパラメーターは、 範囲 ウィジェットの種類をサポートします。 選択すると、Azure Databricks は、範囲の開始と終了を定義するために、 .min と .max サフィックスを使用して 2 つのパラメーターを作成します。

SELECT * FROM samples.nyctaxi.trips
WHERE tpep_pickup_datetime
BETWEEN CAST(:date_range_min AS TIMESTAMP) AND CAST(:date_range_max AS TIMESTAMP)

青い稲妻アイコンをクリックして、 today、 yesterday、 this week、 last week、 last month、 last yearなどの動的な値を選択します。 これらの値は自動的に更新されます。