メインコンテンツまでスキップ

Databricks ウィジェット

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

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

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

  • 異なるパラメーターで再実行されるノートブックまたはダッシュボードをビルドする。
  • 異なるパラメーターを持つ 1 つのクエリの結果をすばやく探索します。

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

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

「ウィジェットを作成」ダイアログ

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

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

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

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

SQL、Python、R、Scala を使用したウィジェットの作成​

プログラムでウィジェットをコンピュート クラスターにアタッチされたノートブックに作成します。

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

  • すべてのウィジェットタイプの最初の引数はnameです。これは、ウィジェットへのアクセスに使用する名前です。
  • 2 番目の引数は defaultValueで、ウィジェットのデフォルト設定です。
  • すべてのウィジェットタイプ( textを除く)の 3 番目の引数は choicesで、ウィジェットが受け取ることができる値のリストです。 この引数は、 text タイプのウィジェットには使用されません。
  • 最後の引数はlabelです。これは、ウィジェットのテキストボックスやドロップダウンの上に表示されるラベルのための任意の値です。
Python
dbutils.widgets.dropdown("state", "CA", ["CA", "IL", "MI", "NY", "OR", "VA"])

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

ウィジェットを操作

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

Python
dbutils.widgets.get("state")

dbutils.widgets.getAll()

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

Python
dbutils.widgets.remove("state")

dbutils.widgets.removeAll()

ウィジェットを削除すると、同じセルにウィジェットを作成できなくなります。 ウィジェットは別のセルに作成する必要があります。

Spark SQL と SQLウェアハウスでのウィジェット値の使用​

Spark SQL ウェアハウスと SQLウェアハウスは、 パラメーター マーカーを使用してウィジェットの値にアクセスします。 パラメーター マーカーは、指定された値を SQL ステートメントから明確に分離することで、SQL インジェクション攻撃からコードを保護します。

ウィジェットのパラメーター マーカーは、Databricks Runtime 15.2 以降で使用できます。 以前のバージョンの Databricks Runtime では、 DBR 15.1 以前の古い構文を使用する必要があります。

ノートブックを対話的に実行しながら、Spark SQLから任意の言語で定義されたウィジェットにアクセスできます。以下のワークフローを考えてみましょう。

  1. 現在のカタログ内のすべてのデータベースを含むドロップダウンウィジェットを作成します。

    Python
    dbutils.widgets.dropdown("database", "default", [database[0] for database in spark.catalog.listDatabases()])

  2. テーブル名を手動で指定するためのテキストウィジェットを作成します。

    Python
    dbutils.widgets.text("table", "")

  3. SQLクエリーを実行して、（ドロップダウンリストから選択した）データベース内のすべてのテーブルを表示します。

    SQL
    SHOW TABLES IN IDENTIFIER(:database)
注記

SQL IDENTIFIER() 句を使用して、データベース、テーブル、ビュー、関数、カラム、フィールドの名前などの文字列をオブジェクト識別子として解析する必要があります。

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

  2. テキストウィジェットを作成して、フィルター値を指定します。

    Python
    dbutils.widgets.text("filter_value", "")

  3. テーブルの内容をプレビューします（クエリーの内容を編集する必要はありません）。

    SQL
    SELECT *
    FROM IDENTIFIER(:database || '.' || :table)
    WHERE col == :filter_value
    LIMIT 100

Databricks Runtime 15.1 以下でウィジェットの値を使用する​

このセクションでは、Databricks ウィジェットの値を Databricks Runtime 15.1 以前の %sql ノートブック セルに渡す方法について説明します。

  1. テキスト値を指定するウィジェットを作成してください。
Python
 dbutils.widgets.text("database", "")
 dbutils.widgets.text("table", "")
 dbutils.widgets.text("filter_value", "100")

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

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

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

ウィジェット設定の構成​

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

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

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

    ウィジェット設定

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

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

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

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

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

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

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

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

Databricks ウィジェットを %run と共に使用する​

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

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

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

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

制限​

詳細については 、ノートブック Databricks 既知の制限事項 を参照してください。

に最終更新