次の方法で共有

Databricks ウィジェット

  • [アーティクル]

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

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

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

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

Scala、Python、R のウィジェット API のドキュメントを表示するには、次のコマンドを使用してください: dbutils.widgets.help()

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() コマンドでは、ウィジェット レイアウトをリセットしません。

ノートブックの例

次のノートブックでは、[アクセスされたコマンドの実行] の設定がどのように機能するかを示します。 year ウィジェットは設定 2014 を使って作成され、DataFrame API と SQL コマンドで使われます。

ウィジェット

year ウィジェットの設定を 2007 に変更すると、DataFrame コマンドは再実行されますが、SQL コマンドは再実行されません。

このノートブックは、SQL ウェアハウスではなく、クラスターにアタッチされたノートブックでのウィジェットの使用方法を示しています。

ウィジェット デモ ノートブック

ノートブックを入手

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

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

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

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

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

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

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

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

制限事項

  • ウィジェットには次の制限が適用されます。

    • ノートブックには最大 512 個のウィジェットを作成できます。
    • ウィジェット名は 1024 文字に制限されています。
    • ウィジェット ラベルは 2048 文字に制限されています。
    • テキスト ウィジェットには最大 2048 文字まで入力できます。
    • 複数選択、コンボ ボックス、またはドロップダウン ウィジェットには、最大 1024 個の選択肢があります。

  • コード内のウィジェットをクリアまたは削除した後でも、[すべて実行] を押したら、ウィジェットの状態が正しくクリアされないという既知の問題が発生します。 これが発生すると、ウィジェットの表示状態と出力される状態が一致しません。 セルを個別に再実行すると、この問題が回避される可能性があります。 この問題を完全に回避するため、Databricks では ipywidgets を使うことをお勧めします。

  • スレッド、サブプロセス、構造化ストリーミング (foreachBatch) などの非同期コンテキストではウィジェットの状態に直接アクセスしないでください。これは、非同期コードの実行中にウィジェットの状態が変化する可能性があるためです。 非同期コンテキストでウィジェットの状態にアクセスする必要がある場合は、それを引数として渡します。 たとえば、スレッドを使用する次のコードがあるとします。

    import threading

def thread_func():
  # Unsafe access in a thread
  value = dbutils.widgets.get('my_widget')
  print(value)

thread = threading.Thread(target=thread_func)
thread.start()
thread.join()

    この場合、代わりに次のように記述する必要があります。

    # Access widget values outside the asynchronous context and pass them to the function
value = dbutils.widgets.get('my_widget')

def thread_func(val):
  # Use the passed value safely inside the thread
  print(val)

thread = threading.Thread(target=thread_func, args=(value,))
thread.start()
thread.join()

  • 一般に、ウィジェットはノートブック内の異なる言語間で引数を渡すことはできません。 一度に 1 つのセルを実行する場合は、Python セルでウィジェット arg1 を作成し、SQL または Scala セルで使用できます。 ただし、[すべて実行] を使用する場合、またはジョブとしてノートブックを実行する場合は機能しません。 次のような回避策があります。

    • 言語が混在していないノートブックの場合は、言語ごとにノートブックを作成し、ノートブックの実行時に引数を渡すことができます。
    • ウィジェットにアクセスするには、spark.sql() 呼び出しを使用します。 たとえば、Python では次のようになります: spark.sql("select getArgument('arg1')").take(1)[0][0]。