問題ウィジェットを使用する

名前付き問題マーカーをクエリに追加すると、 Databricks UI に問題ウィジェットを表示します。ウィジェットを使用すると、ユーザーはクエリを直接編集せずに、値を設定できます。各ウィジェットの種類、タイトル、デフォルト値を設定できます。

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

SQLエディターでは、任意のタイプ (文字列、整数、小数、日付、タイムスタンプ) で任意のウィジェットタイプを使用できます。

新しいSQLエディターの構文

新しいSQLエディターでは、AI/BIダッシュボード、Genie Agent、ノートブックなど、他のDatabricksツールで使用されているのと同じ名前付きパラメーター構文が使用されます。名前付きパラメーターにはコロンがプレフィックスとして付きます (例: :parameter_name)。SQLリファレンスドキュメントについては、名前付きパラメーターマーカーを参照してください。

新しいSQLエディタで実行するには、二重中括弧 ( {{}} ) を使用して括弧をマークする従来のSQLエディタで記述されたクエリを修正する必要があります。従来のSQLエディターから名前付き問題構文を名前付き問題マーカーに変換する例については、名前付き問題構文の例を参照してください。

問題ウィジェットを構成する

名前付きマーカーをクエリに追加します。 UI上にウィジェットが表示されます。
ウィジェットの横にあるギアアイコンをクリックして、ウィジェットダイアログを開きます。
以下の項目を設定してください。
- 問題名 : クエリに表示される問題名。ウィジェットダイアログでの名前を変更する場合は、クエリでも変更する必要があります。
- ウィジェットラベル ：ウィジェットを説明する文字列
- ウィジェットの種類 ：ユーザーが値を入力する方法を制御します。ウィジェットの種類については下記をご覧ください。
- 問題 type : 問題のデータ型。「争点のタイプ」を参照してください。
変更を保存するには、ウィジェットダイアログの外側をクリックしてください。

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

編集：ウィジェットの横にある歯車アイコンをクリックすると、設定画面が再度開きます。

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

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

ウィジェットの種類

Databricks 、クエリに対して次のウィジェットタイプをサポートしています。

ウィジェットタイプ	説明
ドロップダウン	ユーザーは、あらかじめ定義されたリストから選択する必要があります。
コンボボックス	ユーザーは、あらかじめ定義されたリストから選択するか、カスタム値を入力できます。
テキスト入力	提案なしで、あらゆる自由形式の値を受け入れます。
複数選択可	ユーザーは、あらかじめ定義されたリストから複数の値を選択できます。
動的ドロップダウン	静的なリストではなく、保存されたクエリから選択肢を表示します。
日付とタイムスタンプの範囲	`.min`と`.max`を使用して開始範囲と終了範囲を定義します。

ウィジェットタイプ	説明
ドロップダウン	ユーザーは、あらかじめ定義されたリストから選択する必要があります。
コンボボックス	ユーザーは、あらかじめ定義されたリストから選択するか、カスタム値を入力できます。
テキスト入力	提案なしで、あらゆる自由形式の値を受け入れます。
複数選択可	ユーザーは、あらかじめ定義されたリストから複数の値を選択できます。
動的ドロップダウン	静的なリストではなく、保存されたクエリから選択肢を表示します。
日付とタイムスタンプの範囲	`.min`と`.max`を使用して開始範囲と終了範囲を定義します。

テキスト入力

ユーザーから直接、自由形式の値を受け取ります。事前定義されたオプションが不要な場合は、このウィジェットを使用してください。

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

ドロップダウン

あらかじめ定義された値のリストを表示します。ユーザーはリストから選択する必要があり、自由形式の入力は許可されていません。設定パネルに、許可する値を1行に1つずつ入力してください。

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

ドロップダウンウィジェットを作成するには、次のように入力します。

:status_paramウィジェットの横にある歯車アイコンをクリックしてください。
ウィジェットの種類を ドロップダウン に設定します。
争タイプを 文字列 に設定します。
パラメーター値の選択肢 テキスト入力フィールドに値を入力してください。各値の間に 「追加」 をクリックするか、Enterキーを押してください。

コンボボックス

あらかじめ定義された推奨値のリストを表示するだけでなく、リストにないカスタム値をユーザーが入力することもできます。共通の選択肢を用意して利便性を高めつつ、自由形式の入力も可能にしたい場合は、コンボボックスを使用してください。

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

複数選択

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

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

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

list_parameterウィジェットの横にある歯車アイコンをクリックしてください。
ウィジェットの種類を 複数選択 に設定します。
争タイプを 文字列 に設定します。
パラメーター値の選択肢 テキスト入力フィールドに値を入力してください。各値の間に 「追加」 をクリックするか、Enterキーを押してください。

動的なドロップダウン

注記

動的なドロップダウンウィジェットは、SQLエディタでのみ利用可能で、ノートブックでは使用できません。

静的なリストではなく、保存済みのクエリから選択肢のリストを作成します。基となるデータが変更されると、利用可能なオプションも自動的に更新されます。

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

ドロップダウンリストに表示したい値を返すクエリを作成して保存します。
SQL
```
SELECT DISTINCT c_mktsegment FROM samples.tpch.customer ORDER BY c_mktsegment
```
新規または既存のクエリに、名前付きパラメーターマーカーを追加します。
SQL
```
SELECT c_custkey, c_name, c_acctbal
FROM samples.tpch.customer
WHERE c_mktsegment = :segment_param
```
segment_paramウィジェットの横にある歯車アイコンをクリックしてください。
ウィジェットの種類を 「動的ドロップダウン」 に設定します。
「 クエリ」 フィールドをクリックすると、 「既存のクエリを選択」 ダイアログが開きます。ステップ 1 で保存したクエリを選択し、 [選択] をクリックします。
デフォルトの値 を選択してください。
「変更を適用」 をクリックしてください。

注記

動的ドロップダウンには、最大1,024個の値が表示されます。保存されたクエリが1,024個を超える値を返した場合、ウィジェットは最初の1,024個のみを表示し、残りは表示しません。

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

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

SQL
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などの動的な値を選択します。これらの値は自動的に更新されます。

重要

動的な日付値は、スケジュールされたクエリとは互換性がありません。

新しいSQLエディターの構文​

問題ウィジェットを構成する​

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

ウィジェットの種類​

テキスト入力​

ドロップダウン​

コンボボックス​

複数選択​

動的なドロップダウン​

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