Databricksウィジェット

入力ウィジェットを使用すると、ノートブックやダッシュボードに問題を追加できます。 ウィジェットは、Databricks UI から、またはウィジェット API を使用して追加できます。 ウィジェットを追加または編集するには、 ノートブックに対する CAN EDIT 権限が必要です。

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

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

  • 異なるパラメーターを使用して再実行されるノートブックまたはダッシュボードを構築します。

  • さまざまなパラメーターを使用した単一のクエリの結果を迅速に調査します。

ウィジェット 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 ウェアハウスに接続している場合、これがウィジェットを作成できる唯一の方法です。

[ 編集] > [ウィジェットの追加] を選択します。 ウィジェットの追加ダイアログで、ウィジェット名、オプションのラベル、タイプ、パラメーターのタイプ、可能な値、およびオプションのデフォルト値を入力します。 ダイアログでは、引数 Name はコード内でウィジェットを参照するために使用する名前です。 ウィジェットラベル は、UIのウィジェット上に表示されるオプションの名前です。

ウィジェットの作成ダイアログ

ウィジェットを作成したら、ウィジェット名にカーソルを合わせると、ウィジェットの参照方法を説明するツールチップが表示されます。

ウィジェットツールチップ

ケバブメニューを使用して、ウィジェットを編集または削除できます。

ウィジェットケバブメニュー

SQL、Python、R、Scalaでウィジェットを作成する

コンピュート クラスターに接続されたデル内にウィジェットをプログラムで作成します。

ウィジェット API は、Scala、Python、R で一貫性を保つように設計されています。SQL のウィジェット API は若干異なりますが、他の言語と同等です。 ウィジェットは、Databricks ユーティリティ (dbutils) リファレンスインターフェイスを通じて管理します。

  • すべてのウィジェットタイプの最初の引数はnameです。これは、ウィジェットへのアクセスに使用する名前です。

  • 2 番目の引数はウィジェットのデフォルト設定であるdefaultValueです。

  • すべてのウィジェットタイプ( textを除く)の 3 番目の引数は choicesで、ウィジェットが受け取ることができる値のリストです。 この引数は、 text タイプのウィジェットには使用されません。

  • 最後の引数はlabelです。これは、ウィジェットのテキストボックスやドロップダウンの上に表示されるラベルのための任意の値です。

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

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

ウィジェットを操作

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

dbutils.widgets.get("state")

dbutils.widgets.getAll()

dbutils.widgets.get("state")

dbutils.widgets.getAll()

dbutils.widgets.get("state")

SELECT :state

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

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から任意の言語で定義されたウィジェットにアクセスできます。以下のワークフローを考えてみましょう。

  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)

    注

    データベース、テーブル、ビュー、関数、列、フィールドの名前などのオブジェクト識別子として文字列を解析するには、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. テキスト値を指定するウィジェットを作成します。

 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"

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

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

注

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

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

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

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

  2. ポップアップの「ウィジェットパネル設定」ダイアログボックスで、ウィジェットの実行動作を選択します。

    ウィジェット設定

    • ノートブックを実行：新しい値が選択されるたびに、ノートブック全体が再実行されます。

    • アクセスしたコマンドを実行：新しい値が選択されるたびに、特定のウィジェットの値を取得するセルのみが再実行されます。これは、ウィジェットを作成するときのデフォルト設定です。この設定では、SQLセルは再実行されません。

    • 何もしない：新しい値が選択されても、何も再実行されません。

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

  4. ノートブックに対する CAN MANAGE 権限がある場合は、 をクリックしてウィジェットのレイアウトを構成できます。編集アイコン 。 各ウィジェットの順序とサイズはカスタマイズできます。 変更を保存または閉じるには、 をクリックします 承認およびキャンセルアイコン。

    ウィジェットのレイアウトはノートブックに保存されます。 ウィジェットのレイアウトをデフォルト設定から変更すると、新しいウィジェットはアルファベット順に追加されません。

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

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

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

ウィジェットを含むダッシュボード

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

ウィジェットを含むノートブックを実行する場合、指定されたノートブックはウィジェットのデフォルト値で実行されます。

ダッシュボードがクラスター (SQL ウェアハウスではない) に接続されている場合は、ウィジェットに値を渡すこともできます。 例えば：

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

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

制限事項

詳細については、 Databricks既知の制限事項」を参照してください。