次の方法で共有

Databricks ウィジェット

  • [アーティクル]

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

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

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

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

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

Databricks ウィジェットの種類

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

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

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

ヘッダー内のウィジェット

ウィジェットを作成する

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

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

ノートブック UI を使ってウィジェットを作成します。 SQL ウェアハウスに接続している場合、これがウィジェットを作成できる唯一の方法です。

[編集] > [ウィジェットの追加] を選びます。 [Add widget] (ウィジェットの追加) ダイアログで、ウィジェット名、省略可能なラベル、種類、パラメーターの型、使用可能な値、および省略可能な既定値を入力します。 このダイアログの [パラメーター名] は、コード内のウィジェットを参照するために使用する名前です。 [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"])

Scala

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

Scala

dbutils.widgets.get("state")

dbutils.widgets.getAll()

R

dbutils.widgets.get("state")

SQL

SELECT :state

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

Scala

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

R

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Spark SQL と SQL ウェアハウスでウィジェットの値を使用する

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

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

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

  1. 現在のカタログ内のすべてのデータベースのドロップダウン ウィジェットを作成します。

    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. テーブル名を手動で指定するテキスト ウィジェットを作成します。

    dbutils.widgets.text("table", "")

  3. SQL クエリを実行して、データベース内のすべてのテーブルを表示します (ドロップダウン リストから選択)。

    SHOW TABLES IN IDENTIFIER(:database)

    Note

    データベース、テーブル、ビュー、関数、列、フィールドの名前などのオブジェクト識別子として文字列を解析するには、SQL の IDENTIFIER() 句を使う必要があります。

  4. table ウィジェットにテーブル名を手動で入力します。

  5. フィルター値を指定するためのテキスト ウィジェットを作成します。

    dbutils.widgets.text("filter_value", "")

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

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

Databricks Runtime 15.1 以前でウィジェットの値を使用する

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

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

Python

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

Scala

 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"

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

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

Note

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

ウィジェットの設定を構成する

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

  1. [ウィジェット] パネルの右端にある 歯車アイコン アイコンをクリックします。

  2. ポップアップ表示される [Widget Panel Settings](ウィジェット パネル設定) ダイアログ ボックスで、ウィジェットの実行動作を選択します。

    ウィジェットの設定

    • ノートブックの実行: 新しい値が選択されるたびに、ノートブック全体が再実行されます。
    • アクセスされたコマンドの実行: 新しい値が選択されるたび、その特定のウィジェットの値を取得するセルだけが再実行されます。 これはウィジェットを作成するときの既定の設定です。 SQL セルは、この構成では再実行されません。
    • 何もしない: 新しい値が選択されるたび、何も再実行されません。

  3. ウィジェットをノートブックの上部にピン留めするか、最初のセルの上にウィジェットを配置するには、ピン アイコン をクリックします。 設定はユーザーごとに保存されます。 サムタック アイコンをもう一度クリックして、既定の動作にリセットします。

  4. ノートブックに対して "管理可能" のアクセス許可がある場合は、編集アイコン をクリックしてウィジェットのレイアウトを構成できます。 各ウィジェットの順序とサイズはカスタマイズできます。 変更を保存または破棄するには、同意アイコンとキャンセル アイコン をクリックします。

    ウィジェットのレイアウトはノートブックと一緒に保存されます。 ウィジェットのレイアウトを既定の構成から変更した場合、新しいウィジェットはアルファベット順に追加されなくなります。

  5. ウィジェットのレイアウトを既定の順序とサイズにリセットするには、歯車アイコン をクリックして [Widget Panel Settings](ウィジェット パネル設定) ダイアログを開き、次に [レイアウトのリセット] をクリックします。 removeAll() コマンドでは、ウィジェット レイアウトをリセットしません。

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

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

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

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

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

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

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

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

制限事項

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