Databricks ウィジェット

2025-03-28

入力ウィジェットを使用すると、ノートブックとダッシュボードにパラメーターを追加できます。 Databricks UI またはウィジェット API を使用して、ウィジェットを追加できます。ウィジェットを追加または編集するには、"編集可能" アクセス許可をノートブックに対して持っている必要があります。

Databricks Runtime 11.3 LTS またはそれ以上を実行している場合は、Databricks ノートブックで ipywidgets を使用することもできます。

Databricks ウィジェットは、次の場合に最適です。

異なるパラメーターを使用して再実行されるノートブックまたはダッシュボードの構築。
パラメーターが異なる 1 つのクエリの結果に対するすばやい探索。

Scala、Python、または R でウィジェット API のドキュメントを表示するには、次のコマンドを使用します: dbutils.widgets.help()。また、 widgets ユーティリティ (dbutils.widgets) のドキュメントを参照することもできます。

ウィジェットには次の 4 種類があります。

text: テキストボックスに値を入力します。
dropdown: 指定された値のリストから値を選択します。
combobox: テキストとドロップダウンの組み合わせ。指定されたリストから値を選択するか、テキストボックスに値を入力します。
multiselect: 指定された値のリストから 1 つ以上の値を選択します。

ノートブックツールバーの直後にウィジェットのドロップダウンとテキストボックスが表示されます。ウィジェットでは文字列値のみが許可されます。

ウィジェットを作成する

このセクションでは、UI を使用するか、SQL マジックまたは Python、Scala、R 用のウィジェット API を使用してプログラムでウィジェットを作成する方法について説明します。

UI を使用してウィジェットを作成する

ノートブック UI を使ってウィジェットを作成します。 SQL ウェアハウスに接続している場合、これがウィジェットを作成できる唯一の方法です。 [ 編集] > [パラメーターの追加] を選択します。

ウィジェットの設定を編集するには、歯車アイコンをクリックします。

ウィジェット設定ダイアログで、ウィジェット名、省略可能なラベル、型、パラメーターの種類、使用可能な値、および省略可能な既定値を入力できます。このダイアログの [パラメーター名] は、コード内のウィジェットを参照するために使用する名前です。 [Widget Label] (ウィジェットラベル) は、UI のウィジェットに表示される省略可能な名前です。

ウィジェットを作成したら、ウィジェット名をポイントすると、ウィジェットを参照する方法を説明するヒントを表示できます。

SQL、Python、R、Scala を使用してウィジェットを作成する

コンピューティングクラスターにアタッチされたノートブックに、プログラムでウィジェットを作成します。

ウィジェット API は、Scala、Python、R で一貫性があるように設計されています。SQL のウィジェット API は若干異なりますが、他の言語と同等です。ウィジェットは、 Databricks Utilities (dbutils) 参照インターフェイスを使用して管理します。

すべての種類のウィジェットの最初の引数は name です。これは、ウィジェットにアクセスするために使用する名前です。
2 番目の引数は、ウィジェットの既定の設定である defaultValueです。
すべてのウィジェットの種類 (text を除きます) の 3 番目の引数は、ウィジェットが受け取ることができる値の一覧である choices です。この引数は、ウィジェットの種類 text には使用されません。
最後の引数は label です。ウィジェットのテキストボックスまたはドロップダウンに表示されるラベルの省略可能な値です。

Python（プログラミング言語）

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

スカラ (プログラミング言語)

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

R

dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

SQL

CREATE WIDGET DROPDOWN state DEFAULT "CA" CHOICES SELECT * FROM (VALUES ("CA"), ("IL"), ("MI"), ("NY"), ("OR"), ("VA"))

ウィジェットパネルからウィジェットを操作します。

ウィジェットの現在の値にアクセスしたり、すべてのウィジェットのマッピングを取得したりできます。

Python（プログラミング言語）

dbutils.widgets.get("state")

dbutils.widgets.getAll()

スカラ (プログラミング言語)

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

最後に、1 つのウィジェットまたはノートブック内のすべてのウィジェットを削除できます。

Python（プログラミング言語）

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

スカラ (プログラミング言語)

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

ウィジェットを削除した場合、同じセルにウィジェットを作成することはできません。別のセルでウィジェットを作成する必要があります。

Spark SQL と SQL ウェアハウスは、パラメーターマーカーを使ってウィジェットの値にアクセスします。パラメーターマーカーは、指定された値を SQL ステートメントから明確に分離して、SQL インジェクション攻撃からコードを保護します。

ウィジェットのパラメーターマーカーは、Databricks Runtime 15.2 以降で使用できます。以前のバージョンの Databricks Runtime では、古い DBR 15.1 以前の構文を使う必要があります。

任意の言語で定義されたウィジェットには、ノートブックを対話的に実行しながら、Spark SQL からアクセスできます。次のワークフローを考慮してください。

現在のカタログ内のすべてのデータベースのドロップダウンウィジェットを作成します。
```
dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])
```
テーブル名を手動で指定するテキストウィジェットを作成します。
```
dbutils.widgets.text("table", "")
```
SQL クエリを実行して、データベース内のすべてのテーブルを表示します (ドロップダウンリストから選択)。
```
SHOW TABLES IN IDENTIFIER(:database)
```
注

データベース、テーブル、ビュー、関数、列、フィールドの名前などのオブジェクト識別子として文字列を解析するには、SQL の IDENTIFIER() 句を使う必要があります。
table ウィジェットにテーブル名を手動で入力します。
フィルター値を指定するためのテキストウィジェットを作成します。
```
dbutils.widgets.text("filter_value", "")
```

クエリの内容を編集せずに、テーブルの内容をプレビューします。

SELECT *
FROM IDENTIFIER(:database || '.' || :table)
WHERE col == :filter_value
LIMIT 100

このセクションでは、Databricks Runtime 15.1 以前を使って、Databricks ウィジェットの値を %sql ノートブックセルに渡す方法について説明します。

テキスト値を指定するためのウィジェットを作成します。

Python（プログラミング言語）

 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")

R

 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

SQL

 CREATE WIDGET TEXT database DEFAULT ""
 CREATE WIDGET TEXT table DEFAULT ""
 CREATE WIDGET TEXT filter_value DEFAULT "100"

${param} 構文を使ってウィジェットの値を渡します。

SELECT *
FROM ${database}.${table}
WHERE col == ${filter_value}
LIMIT 100

注

$文字をSQL文字列リテラル内でエスケープするには、\$を使用します。たとえば、文字列 $1,000 を表すには、"\$1,000" を使用します。 $ の文字はSQL識別子としてエスケープできません。

新しい値が選択された場合のウィジェットの動作、ウィジェットパネルが常にノートブックの上部にピン留めされるようにするかどうかを構成し、ノートブック内のウィジェットのレイアウトを変更できます。

[ウィジェット] パネルの右端にあるアイコンをクリックします。
ポップアップの [ウィジェットパネルの設定] ダイアログボックスで、ウィジェットの実行動作を選択します。
- ノートブックの実行: 新しい値が選択されるたびに、ノートブック全体が再実行されます。
- アクセスされたコマンドの実行: 新しい値が選択されるたび、その特定のウィジェットの値を取得するセルだけが再実行されます。これはウィジェットを作成するときの既定の設定です。 SQL セルは、この構成では再実行されません。
- 何もしない: 新しい値が選択されるたび、何も再実行されません。
ウィジェットをノートブックの上部にピン留めするか、最初のセルの上にウィジェットを配置するには、をクリックします。設定はユーザーごとに保存されます。サムタックアイコンをもう一度クリックして、既定の動作にリセットします。
ノートブックに対して "管理可能" のアクセス許可がある場合は、をクリックしてウィジェットのレイアウトを構成できます。各ウィジェットの順序とサイズはカスタマイズできます。変更を保存または破棄するには、をクリックします。

ウィジェットのレイアウトはノートブックと一緒に保存されます。ウィジェットのレイアウトを既定の構成から変更した場合、新しいウィジェットはアルファベット順に追加されなくなります。
ウィジェットのレイアウトを既定の順序とサイズにリセットするには、をクリックして [Widget Panel Settings](ウィジェットパネル設定) ダイアログを開き、次に [レイアウトのリセット] をクリックします。 removeAll() コマンドでは、ウィジェットレイアウトをリセットしません。

ダッシュボードの Databricks ウィジェット

入力ウィジェットがあるノートブックからダッシュボードを作成すると、すべてのウィジェットが上部に表示されます。プレゼンテーションモードでは、ウィジェットの値を更新するたびに、[更新] ボタンをクリックしてノートブックを再実行し、ダッシュボードを新しい値で更新できます。

%run で Databricks ウィジェットを使用する

ウィジェットを含むノートブックを実行すると、指定したノートブックがウィジェットの既定値で実行されます。

ノートブックが (SQL ウェアハウスではなく) クラスターにアタッチされている場合は、ウィジェットに値を渡すこともできます。次に例を示します。

%run /path/to/notebook $X="10" $Y="1"

この例では、指定したノートブックを実行し、ウィジェット X に 10 を渡し、ウィジェット Y に 1 を渡します。

制限事項

詳細については、「Databricks ノートブックの既知の制限事項」を参照してください。

次の方法で共有

Databricks ウィジェット