Databricksのwidget(ウィジェット)

Widgets | Databricks on AWS [2022/1/13時点]の翻訳です。

本書は抄訳であり内容の正確性を保証するものではありません。正確な内容に関しては原文を参照ください。

インプットウィジェットを用いることで、お使いのノートブック、ダッシュボードにパラメーターを追加することができます。ウィジェットAPIにおいては、様々なインプットウィジェットを作成、削除、値の取得を行うための呼び出しがサポートされています。

以下のようなケースでウィジェットの利用が適しています。

• 異なるパラメーターを用いて再実行されるノートブック、ダッシュボードの構築。
• 異なるパラメーターを用いて同一のクエリーの結果をクイックに探索する。

以下のコマンドを実行することで、Scala、Python、RのウィジェットAPIのドキュメントを確認することができます。

Scala

dbutils.widgets.help()

ウィジェットのタイプ

ウィジェットには4つのタイプが存在します。

• text: テキストボックスに値を入力します。
• dropdown: 指定された値のリストから値を選択します。
• combobox: テキストボックスとドロップダウンの組み合わせとなります。リストから値を選択するか、テキストボックスに値を入力します。
• multiselect: 指定された値のリストから1つ以上の値を選択します。

ドロップダウン、テキストボックスのウィジェットはノートブックのツールバーの直後に即時に表示されます。

ウィジェットAPI

ウィジェットAPIは、Scala、Python、Rにおいて一貫性を保持するように設計されています。SQLにおけるウィジェットAPIは若干差異がありますが、他の言語同様にパワフルなものです。Databricks Utilitiesインタフェースを介して、ウィジェットを管理することができます。

Python

dbutils.widgets.dropdown("X123", "1", [str(x) for x in range(1, 10)])

dbutils.widgets.dropdown("1", "1", [str(x) for x in range(1, 10)], "hello this is a widget")

dbutils.widgets.dropdown("x123123", "1", [str(x) for x in range(1, 10)], "hello this is a widget")

dbutils.widgets.dropdown("x1232133123", "1", [str(x) for x in range(1, 10)], "hello this is a widget 2")

ウィジェットのサンプル

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

Python

dbutils.widgets.dropdown("X", "1", [str(x) for x in range(1, 10)])

ウィジェットパネルからウィジェットを操作することができます。

メソッド呼び出しを通じてウィジェットの現在の値にアクセスすることができます。

Python

dbutils.widgets.get("X")

特定のウィジェット、ノートブック上の全てのウィジェットを削除することもできます。

Python

dbutils.widgets.remove("X")

dbutils.widgets.removeAll()

重要！
ウィジェットを削除するコマンドを追加した場合、同じセルにウィジェットを追加するコマンドを削除コマンドの後に追加することはできません。別のセルでウィジェットを作成する必要があります。

Scala、Python、Rにおけるウィジェット

それぞれのメソッドの詳細なAPIドキュンメントを参照するには、dbutils.widgets.help("<method-name>")を使用してください。help APIは全ての言語で共通です。例えば、

Python

dbutils.widgets.help("dropdown")

ユニークな識別名、デフォルト値、デフォルト選択肢のリスト、ラベル(オプション)を指定することでドロップダウンリストを作成することができます。作成すると、ノートブックの先頭にドロップダウンインプットウィジェットが表示されます。これらのインプットウィジェットはノートブックレベルのエンティティとなります。

既に存在しているウィジェットを作成しようとすると、既存のウィジェットの設定は、新たなオプションで上書きされます。

SQLにおけるウィジェット

SQLにおいてウィジェットを作成するためのAPIは若干異なりますが、他の言語同様パワフルなものです。以下に、テキストインプットウィジェットの作成例を示します。

SQL

CREATE WIDGET TEXT y DEFAULT "10"

SQLでドロップダウンウィジェットの選択可能な値を指定する際に、サブクエリーを記述することも可能です。サブクエリーの結果テーブルの最初のカラムが値になります。

以下のセルでは、テーブルに対するサブクエリーからドロップダウンウィジェットを作成します。

SQL

CREATE WIDGET DROPDOWN cuts DEFAULT "Good" CHOICES SELECT DISTINCT cut FROM diamonds

ドロップダウンウィジェットを作成する際に指定されたデフォルト値は、選択可能な値を選択する必要があり、文字列リテラルである必要があります。SQLでインプットウィジェットの選択値にアクセスするためには、クエリーに特殊なUDF関数を使用することができます。この関数はgetArgument()となります。例えば、

SQL

SELECT COUNT(*) AS numChoices, getArgument("cuts") AS cuts FROM diamonds WHERE cut = getArgument("cuts")

注意
getArgumentはScala UDFで実装されているので、テーブルACLが有効化されたハイコンカレンシークラスターではサポートされていません。このようなクラスターでは、以下の例にあるように$<parameter>構文を使用してください。

SQLインプットウィジェットの現在の値にアクセするために$<parameter>構文を用いることができます。

SQL

SELECT * FROM diamonds WHERE cut LIKE '%$cuts%'

SQLコマンドを用いてウィジェットを削除することができます。

SQL

REMOVE WIDGET cuts

重要！
通常、ノートブック内の異なる言語間で引数を受け渡しするためにウィジェットを使用することはできません。Pythonのセルでウィジェットarg1を作成し、セルごとに実行した場合はSQLやScalaで使用することができます。しかし、Run Allを用いて全てのコマンドを実行したり、ジョブとしてノートブックを実行した場合には動作しません。この制限を回避するためには、言語ごとのノートブックを作成し、ノートブックを実行する際に引数を渡すことをお勧めします。

SQLにおけるレガシーインプットウィジェット

注意
2022/1/15にレガシーSQLウィジェットのサポートを終了します。お使いのウィジェットがUIにレンダリングされるようにするには、SQLのウィジェットを使用するようにコードを更新してください。%runを用いてノートブックに引き渡されたパラメーターを取得するために$<parameter>を使用することができます。

$<parameter>文法を用いたSQLクエリーにおけるウィジェットを作成する旧来の方法は、以前通り動作します。以下に例を示します。

SQL

SELECT * FROM diamonds WHERE cut LIKE '%$cuts%'

注意
SQL文字列リテラルで$をエスケープするには、\$を使用してください。例えば、文字列$1,000は、\$1,000とエスケーすることができます、SQLの識別子では$の文字をエスケープすることはできません。

ウィジェットの設定

新規の値が選択された際のウィジェットの挙動、ウィジェットパネルを常にノートブックの上部にピン留めするのかどうかの設定、ノートブックにおけるウィジェットのレイアウトの変更を行うことができます。

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

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

   • Run Notebook: 新規の値が選択される度にノートブック全体を再実行します。

   • Run Accessed Commands: 新規の値が選択される度に特定のウィジェットの値を取得するセルのみが再実行されます。これはウィジェット作成時のデフォルトの設定となります。

     注意
     SQLセルはこの設定で実行されません

   • Do Nothing: 新たな値が選択されても処理の再実行は行われません。

3. ノートブックの上部にウィジェットにピン留めするか、最初のセル上にウィジェットを配置するのかを切り替えるには、をクリックします。この設定はユーザーごとに保存されます。

4. ノートブックに対するCan Manage権限を持っているのであれば、をクリックすることでウィジェットのレイアウトを設定することができます。それぞれのウィジェットの並び順、サイズをカスタマイズすることができます。変更を保存したり取り消すにはをクリックします。

   注意
   ウィジェットのレイアウトはノートブックに保存されます。
   ウィジェットのレイアウトが設定されると、新規ウィジェットはアルファベット順に追加されます。

5. レイアウトをデフォルトの並び順、サイズにリセットするには、をクリックし、Widget Panel SettingsでReset Layoutをクリックします。

   注意
   ウィジェットのレイアウトはremoveAll()コマンドではリセットされません。

ノートブック

以下のノートブックを用いることで、Run Accessed Commandsの設定がどのように動作するのかのデモを体験することができます。2014の設定でyearウィジェットが作成され、データフレームAPIとSQLコマンドで使用されます。

yearウィジェットを2007に変更すると、データフレームコマンドが再実行されますが、SQLコマンドは再実行されません。

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

ダッシュボードにおけるウィジェット

インプットウィジェットを持つノートブックからダッシュボードを作成した際、全てのウィジェットがダッシュボードの上部に表示されます。プレゼンテーションモードでは、ウィジェットの値を更新しUpdateボタンをクリックすることで、ノートブックを再実行し、ダッシュボードを新たな値で更新することができます。

%runにおけるウィジェットの使用

ウィジェットを含むノートブックを実行する際、指定されたノートブックはウィジェットのデフォルト値で動作します。以下のようにウィジェットに値を渡すこともできます。

Bash

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

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

Databricks 無料トライアル

Databricks 無料トライアル