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 を使用してウィジェットを作成する

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

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

ウィジェットを作成したら、ウィジェット名の上にマウス ポインターを置いて、ウィジェットを参照する方法を説明するツール ヒントを表示できます。

ウィジェットのヒント

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

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

コンピューティング クラスターで Databricks ウィジェットを使用する

このセクションでは、コンピューティング クラスターにアタッチされたノートブックで Databricks ウィジェットを使用する方法について説明します。 SQL ウェアハウスにアタッチされたノートブックでウィジェットを使用するには、「SQL ウェアハウスで Databricks ウィジェットを使用する」を参照してください。

Databricks ウィジェットの API (クラスター)

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

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

Databricks ウィジェットの例 (クラスター)

各メソッドの詳しい API ドキュメントを表示するには、dbutils.widgets.help("<method-name>") を使用します。 ヘルプ API は、すべての言語で同じです。 次に例を示します。

dbutils.widgets.help("dropdown")

単純なドロップダウン ウィジェットを作成します。

Python

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

SQL

SELECT "${state}"

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

Python

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

SQL

REMOVE WIDGET state

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

Spark SQL でウィジェット値を使用する (クラスター)

Spark SQL は、クエリで使用できる文字列リテラルとしてウィジェット値にアクセスします。

任意の言語で定義されたウィジェットには、ノートブックを対話的に実行しながら、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 ${database}

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

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

    SELECT *
FROM ${database}.${table}
LIMIT 100

注意

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

回避策:

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

注意

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

SQL ウェアハウスで Databricks ウィジェットを使用する

このセクションでは、SQL ウェアハウスにアタッチされたノートブックで Databricks ウィジェットを使用する方法について説明します。 コンピューティング クラスターにアタッチされたノートブックでウィジェットを使用するには、「コンピューティング クラスターで Databricks ウィジェットを使用する」を参照してください。

SQL ウェアハウスのウィジェット値を参照するには、$param ではなく :param 構文を使用します。 たとえば、fare_amount という名前のウィジェットがある場合は、次のようなコードを使用します。

SELECT * FROM samples.nyctaxi.trips WHERE fare_amount < :fare_amount

テーブル、ビュー、スキーマ、列などのオブジェクトを識別するには、IDENTIFIER キーワードを使用します。 たとえば、table_name という名前のウィジェットが samples.nyctaxi.trips に設定されている場合は、次のようになります。

SELECT * FROM IDENTIFIER(:table_name)

詳細については、「IDENTIFIER 句」を参照してください。

パラメーター マーカーの構文の詳細については、「パラメーター マーカー」を参照してください。

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

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

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

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

    ウィジェットの設定

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

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

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

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

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

ノートブックの例

[Run Accessed Commands](アクセスされたコマンドの実行) 設定がどのように動作するかのデモは、次のノートブックで確認できます。 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()