Databricksウィジェット

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

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

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

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

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

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

Databricksウィジェットの種類

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

  • text：テキストボックスに値を入力します。

  • dropdown：指定された値のリストから値を選択します。

  • combobox：テキストとドロップダウンを組み合わせたものです。指定されたリストから値を選択するか、テキストボックスに値を入力します。

  • multiselect：指定された値のリストから1つ以上の値を選択します。

ウィジェットのドロップダウンとテキストボックスは、ノートブックツールバーのすぐ後ろに表示されます。 ウィジェットは文字列値のみを受け入れます。

ヘッダーのウィジェット

UI を使用したウィジェットの作成

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

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

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

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

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

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

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

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

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

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

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

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

  • textを除く全てのウィジェットタイプの第3引数はchoicesです。これはウィジェットが取り得る値のリストです。この引数はtextタイプのウィジェットには使用されません。

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

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

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

dbutils.widgets.help("dropdown")

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

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

SELECT "${state}"

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

dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

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

    ウィジェット設定

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

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

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

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

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

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

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

サンプルノートブック

以下のノートブックでは、「アクセスしたコマンドを実行」設定がどのように機能するかのデモをご覧いただけます。yearウィジェットは2014が設定された状態で作成されており、DataFrame APIおよびSQLコマンドで使用されます。

ウィジェット

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

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

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

ノートブックを新しいタブで開く

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

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

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

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

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

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

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

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

制限事項

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

    • ノートブックには最大 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()