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 を使用してウィジェットを作成する方法、または 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() コマンドはウィジェットのレイアウトをリセットしません。

サンプルノートブック

次のノートブックは、「アクセスしたコマンドの実行」設定がどのように機能するかを示しています。 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()

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

    • 言語が混在しないノートブックの場合は、言語ごとにノートブックを作成し、 ノートブックの実行時に引数を渡すことができます。

    • spark.sql()コールを使用することで、ウィジェットにアクセスできます。Pythonの例：spark.sql("select getArgument('arg1')").take(1)[0][0].