Databricks ウィジェット
入力ウィジェットを使用すると、ノートブックとダッシュボードにパラメーターを追加できます。 ウィジェットは、Databricks UI から、またはウィジェット API を使用して追加できます。 ウィジェットを追加または編集するには、 ノートブックに対する CAN EDIT アクセス許可が必要です。
Databricks Runtime 11.3 LTS 以降を実行している場合は、 Databricks ノートブックで ipywidgets を使用することもできます。
Databricksウィジェットは、以下の場合に最適です。
- 異なるパラメーターで再実行されるノートブックまたはダッシュボードをビルドする。
- 異なるパラメーターを持つ 1 つのクエリの結果をすばやく探索します。
ウィジェット API のドキュメンテーションを Scala、Python、または R で表示するには、次のコマンドを使用します。 dbutils.widgets.help()
. ウィジェット・ユーティリティ (dbutils.widgets) のマニュアルも参照してください。
Databricks ウィジェットの種類
ウィジェットには4つの種類があります。
text
:テキストボックスに値を入力します。dropdown
:指定された値のリストから値を選択します。combobox
:テキストとドロップダウンを組み合わせたものです。指定されたリストから値を選択するか、テキストボックスに値を入力します。multiselect
:指定された値のリストから1つ以上の値を選択します。
ウィジェットのドロップダウンとテキストボックスは、ノートブックツールバーのすぐ後ろに表示されます。 ウィジェットは文字列値のみを受け入れます。
ウィジェットを作成してください
このセクションでは、UI を使用してウィジェットを作成する方法、または SQL マジックまたは Python、Scala、R のウィジェット API を使用してプログラムでウィジェットを作成する方法を示します。
UI を使用したウィジェットの作成
ノートブック UI を使用してウィジェットを作成します。 SQLウェアハウスに接続している場合、ウィジェットを作成できる唯一の方法です。
[編集] > [ウィジェットの追加 ] を選択します。[ ウィジェットの追加 ] ダイアログで、ウィジェット名、オプションのラベル、タイプ、パラメーター タイプ、使用可能な値、およびオプションの デフォルト値を入力します。 ダイアログでは、 [パラメーター名 ] は、コード内のウィジェットを参照するために使用する名前です。 ウィジェットラベル は、UIのウィジェット上に表示されるオプションの名前です。
ウィジェットを作成したら、ウィジェット名にカーソルを合わせると、ウィジェットの参照方法を説明するツールチップが表示されます。
ケバブメニューを使ってウィジェットを編集したり削除したりできます。
SQL、Python、R、Scala を使用したウィジェットの作成
プログラムでウィジェットをコンピュート クラスターにアタッチされたノートブックに作成します。
ウィジェット API は、Scala、Python、R で一貫性を保つように設計されています。SQLのウィジェットAPIは少し異なりますが、他の言語と同等です。 ウィジェットは、 Databricks ユーティリティ (dbutils
) リファレンス インターフェイスを使用して管理します。
- すべてのウィジェットタイプの最初の引数は
name
です。これは、ウィジェットへのアクセスに使用する名前です。 - 2 番目の引数は
defaultValue
で、ウィジェットのデフォルト設定です。 - すべてのウィジェットタイプ(
text
を除く)の 3 番目の引数はchoices
で、ウィジェットが受け取ることができる値のリストです。 この引数は、text
タイプのウィジェットには使用されません。 - 最後の引数は
label
です。これは、ウィジェットのテキストボックスやドロップダウンの上に表示されるラベルのための任意の値です。
- Python
- Scala
- R
- SQL
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])
CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))
ウィジェットパネルからウィジェットを操作します。
ウィジェットの現在の値にアクセスしたり、すべてのウィジェットのマッピングを取得したりできます。
- Python
- Scala
- R
- SQL
dbutils.widgets.get("state")
dbutils.widgets.getAll()
dbutils.widgets.get("state")
dbutils.widgets.getAll()
dbutils.widgets.get("state")
SELECT :state
最後に、ノートブック内のウィジェットまたはすべてのウィジェットを削除できます。
- Python
- Scala
- R
- SQL
dbutils.widgets.remove("state")
dbutils.widgets.removeAll()
dbutils.widgets.remove("state")
dbutils.widgets.removeAll()
dbutils.widgets.remove("state")
dbutils.widgets.removeAll()
REMOVE WIDGET state
ウィジェットを削除すると、同じセルにウィジェットを作成できなくなります。 ウィジェットは別のセルに作成する必要があります。
Spark SQL と SQLウェアハウスでのウィジェット値の使用
Spark SQL ウェアハウスと SQLウェアハウスは、 パラメーター マーカーを使用してウィジェットの値にアクセスします。 パラメーター マーカーは、指定された値を SQL ステートメントから明確に分離することで、SQL インジェクション攻撃からコードを保護します。
ウィジェットのパラメーター マーカーは、Databricks Runtime 15.2 以降で使用できます。 以前のバージョンの Databricks Runtime では、 DBR 15.1 以前の古い構文を使用する必要があります。
ノートブックを対話的に実行しながら、Spark SQLから任意の言語で定義されたウィジェットにアクセスできます。以下のワークフローを考えてみましょう。
-
現在のカタログ内のすべてのデータベースを含むドロップダウンウィジェットを作成します。
Pythondbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])
-
テーブル名を手動で指定するためのテキストウィジェットを作成します。
Pythondbutils.widgets.text("table", "")
-
SQLクエリーを実行して、(ドロップダウンリストから選択した)データベース内のすべてのテーブルを表示します。
SQLSHOW TABLES IN IDENTIFIER(:database)
SQL IDENTIFIER()
句を使用して、データベース、テーブル、ビュー、関数、カラム、フィールドの名前などの文字列をオブジェクト識別子として解析する必要があります。
-
table
ウィジェットにテーブル名を手動で入力します。 -
テキストウィジェットを作成して、フィルター値を指定します。
Pythondbutils.widgets.text("filter_value", "")
-
テーブルの内容をプレビューします(クエリーの内容を編集する必要はありません)。
SQLSELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100
Databricks Runtime 15.1 以下でウィジェットの値を使用する
このセクションでは、Databricks ウィジェットの値を Databricks Runtime 15.1 以前の %sql
ノートブック セルに渡す方法について説明します。
- テキスト値を指定するウィジェットを作成してください。
- Python
- Scala
- R
- SQL
dbutils.widgets.text("database", "")
dbutils.widgets.text("table", "")
dbutils.widgets.text("filter_value", "100")
dbutils.widgets.text("database", "")
dbutils.widgets.text("table", "")
dbutils.widgets.text("filter_value", "100")
dbutils.widgets.text("database", "")
dbutils.widgets.text("table", "")
dbutils.widgets.text("filter_value", "100")
CREATE WIDGET TEXT database DEFAULT ""
CREATE WIDGET TEXT table DEFAULT ""
CREATE WIDGET TEXT filter_value DEFAULT "100"
-
ウィジェットの値は、
${param}
構文を使用して渡します。SQLSELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100
SQL 文字列リテラル内の $
文字をエスケープするには、\$
を使用します。たとえば、文字列 $1,000
を表すには、 "\$1,000"
を使用します。 $
文字は、SQL ID でエスケープできません。
ウィジェット設定の構成
新しい値が選択されたときのウィジェットの動作、ウィジェットパネルを常にノートブックの上部に固定するかどうか、ノートブック内でのウィジェットのレイアウトを変更するかどうかを構成できます。
-
ウィジェットパネルの右端にある
アイコンをクリックします。
-
ポップアップの「ウィジェットパネル設定」ダイアログボックスで、ウィジェットの実行動作を選択します。
- ノートブックを実行 :新しい値が選択されるたびに、ノートブック全体が再実行されます。
- アクセスしたコマンドを実行 :新しい値が選択されるたびに、特定のウィジェットの値を取得するセルのみが再実行されます。これは、ウィジェットを作成するときのデフォルト設定です。この設定では、SQLセルは再実行されません。
- 何もしない :新しい値が選択されても、何も再実行されません。
-
ウィジェットをノートブックの一番上に固定したり、最初のセルの上にウィジェットを配置したりするには、
をクリックします。設定はユーザーごとに保存されます。画鋲アイコンをもう一度クリックすると、デフォルトの動作にリセットされます。
-
ノートブックの CAN MANAGE アクセス許可がある場合は、[
] をクリックしてウィジェットのレイアウトを構成できます。 各ウィジェットの順序とサイズはカスタマイズできます。 変更を保存または閉じるには、[
] をクリックします。
ウィジェットのレイアウトはノートブックとともに保存されます。 ウィジェットのレイアウトをデフォルトの構成から変更した場合、新しいウィジェットはアルファベット順に追加されません。
-
ウィジェットのレイアウトをデフォルトの順序とサイズにリセットするには、[
] をクリックして [ウィジェット パネルの設定 ] ダイアログを開き、[ レイアウトのリセット ] をクリックします。
removeAll()
コマンドは、ウィジェットのレイアウトをリセットしません。
ダッシュボードの Databricks ウィジェット
入力ウィジェットを含むノートブックからダッシュボードを作成すると、すべてのウィジェットが上部に表示されます。 プレゼンテーション モードでは、ウィジェットの値を更新するたびに [ 更新 ] ボタンをクリックしてノートブックを再実行し、ダッシュボードを新しい値で更新できます。
Databricks ウィジェットを %run と共に使用する
ウィジェットを含む ノートブックを実行すると 、指定したノートブックはウィジェットのデフォルト値で実行されます。
ノートブックが ( SQLウェアハウスではなく) クラスターに接続されている場合は、ウィジェットに値を渡すこともできます。 例えば:
%run /path/to/notebook $X="10" $Y="1"
この例では、指定されたノートブックを実行し、10
をウィジェットXに渡し、1
をウィジェットYに渡します。
制限
詳細については 、ノートブック Databricks 既知の制限事項 を参照してください。