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

Databricks ユーティリティ (dbutils) リファレンス

この記事には、Databricks ユーティリティ (dbutils) のリファレンスが含まれています。 ユーティリティには、ノートブックから Databricks 環境を操作できるようにするコマンドが用意されています。 たとえば、ファイルやオブジェクトストレージを管理したり、シークレットを操作したりできます。 dbutils は、Python、R、および Scala ノートブックで使用できます。

注記

dbutils DBFSを使用するコンピュート環境のみをサポートします。

ユーティリティモジュール​

次の表に、 dbutils.help()を使用して取得できる Databricks ユーティリティ モジュールを示します。

モジュール

説明

資格情報

ノートブック内の資格情報を操作するためのユーティリティ

data

データセットを理解し、データセットを操作するためのユーティリティ (実験的)

FSの

Databricks ファイルシステム (DBFS) にアクセスするためのユーティリティ

jobs

ジョブ機能を活用するためのユーティリティ

ライブラリ

廃止。 セッションスコープのライブラリを管理するためのユーティリティ

メタ

コンパイラにフックするユーティリティ (実験的)

ノートブック

ノートブックの制御フローを管理するためのユーティリティ (実験的)

プレビュー

ユーティリティのプレビュー

secrets

ノートブック内のシークレットを活用するためのユーティリティ

ウィジェット

ノートブックをパラメータ化するためのユーティリティ。

API

アプリケーションビルドを管理するためのユーティリティ

コマンドヘルプ​

ユーティリティ モジュールのコマンドを各コマンドの簡単な説明と共に一覧表示するには、ユーティリティ モジュールの名前の後に .help() を追加します。 次の例は、ノートブック ユーティリティで使用可能なコマンドの一覧を示しています。

dbutils.notebook.help()
Output
The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value

コマンドのヘルプを出力するには、 dbutils.<utility-name>.help("<command-name>")を実行します。 次の例は、ファイル・システム・ユーティリティーの copy コマンド dbutils.fs.cpのヘルプを示しています。

dbutils.fs.help("cp")
Output
/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean

資格情報ユーティリティ (dbutils.credentials)​

credentials ユーティリティを使用すると、ノートブック内の認証情報を操作できます。 このユーティリティは、 資格情報のパススルー が有効になっているクラスターでのみ使用できます。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.credentials.help()を使用して取得できます。

コマンド

説明

引き受けた役割

S3 で認証するための認証情報を検索するときに引き受けるロール ARN を設定します。

showCurrentRole (現在のロールを表示)

現在設定されているロールが表示されます。

ロールを表示

想定される役割のセットを示しています。

assumeRole コマンド (dbutils.credentials.assumeRole)​

assumeRole(role: String): boolean

Amazon S3 で認証するための資格情報を探す際にAWS Identity and Access Management（IAM）ロールが引き受けるAmazon リソースネーム（ARN）を設定します。このコマンドを実行すると、 sc.textFile("s3a://my-bucket/my-file.csv") などの S3 アクセスコマンドを実行してオブジェクトにアクセスできます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.credentials.help("assumeRole")

例​

Python
dbutils.credentials.assumeRole("arn:aws:iam::123456789012:roles/my-role")

# Out[1]: True

showCurrentRole コマンド (dbutils.credentials.showCurrentRole)​

showCurrentRole: List

現在設定されているAWS Identity and Access Management（IAM）ロールを一覧表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.credentials.help("showCurrentRole")

例​

Python
dbutils.credentials.showCurrentRole()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a']

showRoles コマンド (dbutils.credentials.showRoles)​

showRoles: List

想定されるAWS Identity and Access Management（IAM）ロールのセットをリストします。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.credentials.help("showRoles")

例​

Python
dbutils.credentials.showRoles()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a', 'arn:aws:iam::123456789012:role/my-role-b']

データ・ユーティリティ (dbutils.data)​

備考

プレビュー

この機能は パブリック プレビュー段階です。

注記

Databricks Runtime 9.0以降で利用可能です。

データ ユーティリティを使用すると、データセットを理解し、操作することができます。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.data.help()を使用して取得できます。

コマンド

説明

要約

Spark データフレームをまとめ、統計を可視化して迅速な知見を得る

summarize コマンド (dbutils.data.summarize)​

注記

この機能は パブリック プレビュー段階です。

summarize(df: Object, precise: boolean): void

Apache Spark データフレームまたはpandas データフレームの概要統計を計算して表示します。このコマンドは、Python、Scala、Rで使用できます。

important

このコマンドは、データフレーム の完全な内容を分析します。 このコマンドを非常に大きな データフレーム に実行すると、非常にコストがかかる場合があります。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.data.help("summarize")

Databricks Runtime 10.4 LTS 以降では、追加の precise パラメーターを使用して、コンピュート統計の精度を調整できます。

  • precise がfalse（デフォルト）に設定されている場合、返される統計の一部には、実行時間を短縮するための近似値が含まれます。

    • カテゴリ列の異なる値の数には、カーディナリティの高い列の場合、最大5%の相対誤差が生じる可能性があります。
    • 異なる値の数が10000を超える場合、頻繁に発生する値のカウントには最大 0.01%の誤差が生じる可能性があります。
    • ヒストグラムとパーセンタイルの推定値には、行の総数に対して最大0.01%の誤差が生じる場合があります。

  • precise がtrueに設定されている場合、統計はより高い精度で計算されます。数値列のヒストグラムとパーセンタイルを除くすべての統計は正確な値になりました。

    • ヒストグラムとパーセンタイルの推定値には、行の総数に対して最大0.0001%の誤差が生じる場合があります。

データサマリー出力の上部にあるツールチップは、現在の実行のモードを示します。

例​

この例では、Apache Spark データフレーム の要約統計を表示し、近似がデフォルトで有効になっています。 を表示するには 結果としては、ノートブックでこのコマンドを実行します。 この例は 、サンプル データセットに基づいています。

Python
df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)

視覚化では、 SI 表記 を使用して、0.01 より小さい数値または 10000 より大きい数値を簡潔にレンダリングします。 例として、 1.25e-15 数値は 1.25fとレンダリングされます。 1 つの例外: ビジュアライゼーションでは、1.0e9 (ギガ) に対して "G" ではなく "B" が使用されます。

ファイル・システム・ユーティリティ (dbutils.fs)​

ファイル・システム・ユーティリティーを使用すると、DBFS とはにアクセスできます。ワークスペースファイルにアクセスするには、%sh lsなどのシェルコマンドを使用します。これは、ワークスペースファイルで dbutils.fs コマンドを使用する場合にいくつかの制限があるためです。

警告

すべての dbutils.fs メソッドのPython実装では、キーワードの形式に camelCase ではなくsnake_case が使われます。

たとえば、dbutils.fs.help() には dbutils.fs.mount()のオプション extraConfigs が表示されます。ただし、Python では、キーワード extra_configsを使用します。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.fs.help()を使用して取得できます。

コマンド

説明

CPの

ファイルまたはディレクトリを、場合によってはFileSystems間でコピーします。

頭

指定されたファイルの最初の 'maxBytes' バイトまでを UTF-8 でエンコードされた文字列として返します

ls

ディレクトリの内容を一覧表示します

mkdirs

指定されたディレクトリが存在しない場合は作成し、必要な親ディレクトリも作成します

マウント

指定されたソース・ディレクトリを、指定されたマウント・ポイントのDBFSにマウントします

マウント

DBFS 内にマウントされているものに関する情報を表示します

MV

ファイルまたはディレクトリを、おそらくファイルシステム間で移動します

置く

指定された文字列をUTF-8でエンコードされたファイルに書き込みます

リフレッシュマウント

このクラスター内のすべてのマシンにマウント キャッシュの更新を強制し、最新の情報を受け取るようにします

マイクロメートル

ファイルまたはディレクトリを削除します

アンマウント

DBFS マウント・ポイントを削除します。

アップデートマウント

mount () に似ていますが、新しいマウントポイントを作成する代わりに既存のマウントポイントを更新します

ヒント

ノートブックでは、 %fs マジック コマンドを使用して DBFS にアクセスできます。 たとえば、 %fs ls /Volumes/main/default/my-volume/ は dbutils.fs.ls("/Volumes/main/default/my-volume/")と同じです。 マジックコマンドを参照してください。

cp コマンド (dbutils.fs.cp)​

cp(from: String, to: String, recurse: boolean = false): boolean

ファイルまたはディレクトリを、場合によってはファイルシステム間でコピーします。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("cp")

例​

この例では、 data.csv という名前のファイルを同じボリューム内の /Volumes/main/default/my-volume/ から new-data.csv にコピーします。

Python
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

# Out[4]: True

HEAD コマンド (dbutils.fs.head)​

head(file: String, maxBytes: int = 65536): String

指定されたファイル内の指定された最大バイト数まで返します。 バイトは UTF-8 でエンコードされた文字列として返されます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("head")

例​

この例では、 /Volumes/main/default/my-volume/ にあるファイル： data.csv の最初の25バイトを表示しています。

Python
dbutils.fs.head("/Volumes/main/default/my-volume/data.csv", 25)

# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'

ls コマンド (dbutils.fs.ls)​

ls(dir: String): Seq

ディレクトリの内容を一覧表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("ls")

例​

この例では、 /Volumes/main/default/my-volume/の内容に関する情報を表示します。 modificationTime フィールドは、Databricks Runtime 10.4 LTS 以降で使用できます。R では、 modificationTime は文字列として返されます。

Python
dbutils.fs.ls("/Volumes/main/default/my-volume/")

# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]

mkdirs コマンド (dbutils.fs.mkdirs)​

mkdirs(dir: String): boolean

指定されたディレクトリが存在しない場合は作成します。また、必要な親ディレクトリも作成します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("mkdirs")

例​

この例では、/Volumes/main/default/my-volume/ の中に my-data というディレクトリを作成します。

Python
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# Out[15]: True

mount コマンド (dbutils.fs.mount)​

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

指定されたソースディレクトリを、指定されたマウントポイントのDBFSにマウントします。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("mount")

例​

Python
aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.mount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

その他のコード例については、「 Amazon S3 への接続」を参照してください。

mounts コマンド (dbutils.fs.mounts)​

mounts: Seq

DBFS 内に現在マウントされているものに関する情報を表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("mounts")

例​

警告

他のすべての稼働中のクラスターで dbutils.fs.refreshMounts() を呼び出して、新しいマウントを伝搬します。 refreshMounts コマンド (dbutils.fs.refreshMounts)を参照してください。

Python
dbutils.fs.mounts()

# Out[11]: [MountInfo(mountPoint='/mnt/databricks-results', source='databricks-results', encryptionType='sse-s3')]

その他のコード例については、「 Amazon S3 への接続」を参照してください。

mv コマンド (dbutils.fs.mv)​

mv(from: String, to: String, recurse: boolean = false): boolean

ファイルまたはディレクトリを、場合によってはファイルシステム間で移動します。ファイルシステム内での移動の場合でも、コピーの後に削除が行われます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("mv")

例​

この例では、ファイル rows.csv を /Volumes/main/default/my-volume/ から /Volumes/main/default/my-volume/my-data/ に移動します。

Python
dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

# Out[2]: True

put コマンド (dbutils.fs.put)​

put(file: String, contents: String, overwrite: boolean = false): boolean

指定された文字列をファイルに書き込みます。文字列はUTF-8でエンコードされています。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("put")

例​

この例では、Hello, Databricks! という文字列を /Volumes/main/default/my-volume/ 内の hello.txt という名前のファイルに書き込みます。ファイルがすでに存在する場合は、上書きされます。

Python
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

# Wrote 2258987 bytes.
# Out[6]: True

refreshMounts コマンド (dbutils.fs.refreshMounts)​

refreshMounts: boolean

クラスター内のすべてのマシンにマウントキャッシュを強制的に更新させ、最新の情報を確実に受信できるようにします。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("refreshMounts")

例​

Python
dbutils.fs.refreshMounts()

その他のコード例については、「 Amazon S3 への接続」を参照してください。

rm コマンド (dbutils.fs.rm)​

rm(dir: String, recurse: boolean = false): boolean

ファイルまたはディレクトリを削除し、必要に応じてその内容をすべて削除します。 ファイルが指定されている場合、 recurse パラメーターは無視されます。 ディレクトリが指定されている場合、 recurse が無効でディレクトリが空でないとエラーが発生します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("rm")

例​

この例では、その内容を含むディレクトリ /Volumes/main/default/my-volume/my-data/ 全体を削除します。

Python
dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", True)

# Out[8]: True

アンマウント コマンド (dbutils.fs.アンマウント)​

unmount(mountPoint: String): boolean

DBFSのマウントポイントを削除します。

警告

エラーを回避するには、他のジョブがマウント・ポイントを読み取ったり書き込んだりしている間は、マウント・ポイントを変更しないでください。 マウントを変更した後は、常に他のすべての稼働中のクラスターで dbutils.fs.refreshMounts() を実行して、マウントの更新を伝搬します。 refreshMounts コマンド (dbutils.fs.refreshMounts)を参照してください。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("unmount")

例​

Python
dbutils.fs.unmount("/mnt/<mount-name>")

その他のコード例については、「 Amazon S3 への接続」を参照してください。

updateMount コマンド (dbutils.fs.updateMount)​

updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

dbutils.fs.mount コマンドと似ていますが、新しいマウントポイントを作成するのではなく、既存のマウントポイントを更新します。マウントポイントが存在しない場合はエラーを返します。

警告

エラーを回避するには、他のジョブがマウント・ポイントを読み取ったり書き込んだりしている間は、マウント・ポイントを変更しないでください。 マウントを変更した後は、常に他のすべての稼働中のクラスターで dbutils.fs.refreshMounts() を実行して、マウントの更新を伝搬します。 refreshMounts コマンド (dbutils.fs.refreshMounts)を参照してください。

このコマンドは、Databricks Runtime 10.4 LTS 以降で使用できます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.fs.help("updateMount")

例​

Python
aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.updateMount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

ジョブ ユーティリティ (dbutils.jobs)​

ジョブ機能を活用するためのユーティリティを提供します。

注記

このユーティリティはPythonのみで使用できます。

次の表に、このユーティリティで使用可能なモジュールを示します。このモジュールは、 dbutils.jobs.help()を使用して取得できます。

サブモジュール

説明

タスクバリュー

ジョブ・タスク値を活用するためのユーティリティーを提供します

taskValues サブユーティリティ (dbutils.job.taskValues)​

注記

このサブユーティリティは、Pythonでのみ使用できます。

ジョブ・タスクの値を活用するためのコマンドを提供します。

このサブユーティリティを使用して、ジョブの実行中に任意の値を設定および取得します。 これらの値は タスク値 と呼ばれます。 どのタスクも、上流のタスクによって設定された値を取得し、下流のタスクが使用する値を設定できます。

各タスク値には、同じタスク内で一意のキーがあります。 この一意のキーは、タスク値のキーと呼ばれます。 タスク値には、タスク名とタスク値のキーを使用してアクセスします。 これを使用して、同じジョブ実行内のタスクからタスクに情報を渡すことができます。 たとえば、機械学習モデルの評価に関する情報などの識別子やメトリクスを、ジョブ実行内の異なるタスク間で渡すことができます。

次の表に、このサブユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.jobs.taskValues.help()を使用して取得できます。

コマンド

説明

取得

現在のジョブ実行において指定されたタスクで指定されたタスク値の内容を取得します。

SET

タスクの値を設定または更新します。ジョブ実行には最大250のタスク値を設定できます。

get コマンド (dbutils.ジョブ.taskValues.get)​

注記

このコマンドはPythonでのみ使用できます。

Databricks Runtime 10.4 以前では、タスクget見つからない場合、ValueErrorの代わりに Py4JJavaError が発生します。

get(taskKey: String, key: String, default: int, debugValue: int): Seq

現在のジョブ実行において指定されたタスクで指定されたタスク値の内容を取得します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.jobs.taskValues.help("get")

例​

例えば：

Python
dbutils.jobs.taskValues.get(taskKey    = "my-task", \
                            key        = "my-key", \
                            default    = 7, \
                            debugValue = 42)

前述の例を説明します。

  • taskKey は、タスク値を設定するタスクの名前です。 コマンドがこのタスクを見つけられない場合は、 ValueError が発生します。
  • key は、 set コマンド (dbutils.ジョブ.taskValues.set) で設定したタスク値のキーの名前です。 コマンドがこのタスク値のキーを見つけられない場合は、 ValueError が発生します ( default が指定されていない限り)。
  • default は、 key が見つからない場合に返されるオプションの値です。default Noneすることはできません.
  • debugValue は、ジョブの外部で実行されているノートブック内からタスク値を取得しようとした場合に返されるオプションの値です。 これは、デバッグ中にノートブックを手動で実行し、デフォルトで TypeError を上げる代わりに何らかの値を返す場合に便利です。 debugValue Noneすることはできません.

ジョブの外部で実行されているノートブック内からタスク値を取得しようとすると、このコマンドはデフォルトで TypeError を発生させます。ただし、コマンドで debugValue 引数が指定されている場合は、TypeError を発生させる代わりに debugValue の値が返されます。

set コマンド (dbutils.ジョブ.taskValues.set)​

注記

このコマンドはPythonでのみ使用できます。

set(key: String, value: String): boolean

タスクの値を設定または更新します。ジョブ実行には最大250のタスク値を設定できます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.jobs.taskValues.help("set")

例​

例としては次のようなものがあります。

Python
dbutils.jobs.taskValues.set(key   = "my-key", \
                            value = 5)

dbutils.jobs.taskValues.set(key   = "my-other-key", \
                            value = "my other value")

前述の例を説明します。

  • key はタスク値のキーです。このキーはタスクに一意のものでなければなりません。つまり、2 つの異なるタスクが、それぞれに K というキーを持つタスク値を設定する場合、これらは K という同じキーを持つ 2 つの異なるタスク値となります。
  • value は、このタスク値のキーの値です。このコマンドは、値を内部的にJSON形式で表現する必要があります。値のJSON表現のサイズは48 KiBを超えてはなりません。

ジョブの外部で実行されているノートブック内からタスク値を設定しようとしても、このコマンドからは何も得られません。

ライブラリ ユーティリティ (dbutils.ライブラリ)​

dbutils.library サブモジュールのほとんどのメソッドは非推奨です。ライブラリ ユーティリティ (dbutils.ライブラリ) (legacy)を参照してください。

ローカルにインストールまたはアップグレードされたライブラリが現在の SparkSession の Python カーネルで正しく機能することを確認するために、Databricks で Python プロセスをプログラムで再起動することが必要な場合があります。 これを行うには、 dbutils.library.restartPython コマンドを実行します。 「Databricks で Python プロセスを再起動する」を参照してください。

ノートブック ユーティリティ (dbutils.ノートブック)​

ノートブック ユーティリティを使用すると、ノートブックをチェーンし、その結果に基づいて操作できます。 「ノートブックのオーケストレーションとノートブックでのコードのモジュール化」を参照してください。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.notebook.help()を使用して取得できます。

コマンド

説明

出口

値を持つノートブックを終了します

実行

ノートブックを実行し、その終了値を返します

exit コマンド (dbutils.ノートブック.exit)​

exit(value: String): void

値を持つノートブックを終了します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.notebook.help("exit")

例​

この例では、Exiting from My Other Notebook という値でノートブックを終了します。

Python
dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook
注記

実行に 、バックグラウンドで実行されている構造化ストリーミング のクエリがある場合、 dbutils.notebook.exit() を呼び出しても実行は終了しません。 クエリがバックグラウンドで実行されている限り、実行は実行され続けます。 バックグラウンドで実行中のクエリを停止するには、クエリのセルで [キャンセル ] をクリックするか、 query.stop()を実行します。 クエリが停止したら、 dbutils.notebook.exit()で実行を終了できます。

実行 コマンド (dbutils.ノートブック.実行)​

run(path: String, timeoutSeconds: int, arguments: Map): String

ノートブックを実行し、その終了値を返します。デフォルトでは、ノートブックは現在のクラスターで実行されます。

注記

run コマンドから返される文字列値の最大長は 5 MB です。「1 回の実行の出力の取得 (GET /jobs/runs/get-output) を参照してください。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.notebook.help("run")

例​

この例では、呼び出し元のノートブックと同じ場所で My Other Notebook という名前のノートブックを実行します。呼び出されたノートブックは、dbutils.notebook.exit("Exiting from My Other Notebook") というコード行で終わります。呼び出されたノートブックの実行が60秒以内に終了しない場合、例外がスローされます。

Python
dbutils.notebook.run("My Other Notebook", 60)

# Out[14]: 'Exiting from My Other Notebook'

シークレット・ユーティリティ (dbutils.secrets)​

secrets ユーティリティを使用すると、機密性の高い認証情報をノートブックに表示せずに保存およびアクセスできます。 「シークレットの管理」および「ステップ 3: ノートブックでシークレットを使用する」を参照してください。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.secrets.help()を使用して取得できます。

コマンド

説明

取得

スコープとキーを持つシークレット値の文字列表現を取得します

getBytes

スコープとキーを含むシークレット値のバイト表現を取得します

リスト

スコープ内のシークレットのシークレットメタデータを一覧表示します

リストスコープ

シークレットスコープを一覧表示します

get コマンド (dbutils.secrets.get)​

get(scope: String, key: String): String

指定されたシークレットスコープとキーのシークレット値の文字列表現を取得します。

警告

管理者、シークレット作成者、 およびアクセス許可 を付与されたユーザーは、Databricks シークレットを読み取ることができます。 つつ Databricks は、ノートブックに表示される可能性のあるシークレット値を編集する努力をしていますが、そのようなユーザーがシークレットを読み取るのを防ぐことはできません。 詳細については、「 シークレット編集」を参照してください。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.secrets.help("get")

例​

この例では、 my-scope という名前のスコープと my-keyという名前のキーのシークレット値の文字列表現を取得します。

Python
dbutils.secrets.get(scope="my-scope", key="my-key")

# Out[14]: '[REDACTED]'

getBytes コマンド (dbutils.secrets.getBytes)​

getBytes(scope: String, key: String): byte[]

指定されたスコープとキーのシークレット値のバイト表現を取得します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.secrets.help("getBytes")

例​

この例では、 my-scope という名前のスコープと my-key という名前のキーのシークレット値（この例では a1!b2@c3#）のバイト表現を取得します。

Python
dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# Out[1]: b'a1!b2@c3#'

list コマンド (dbutils.secrets.list)​

list(scope: String): Seq

指定したスコープ内のシークレットのメタデータを一覧表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.secrets.help("list")

例​

この例では、 my-scope という名前のスコープ内のシークレットのメタデータを一覧表示します。

Python
dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]

listScopes コマンド (dbutils.secrets.listScopes)​

listScopes: Seq

利用可能なスコープを一覧表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.secrets.help("listScopes")

例​

この例では、使用可能なスコープを一覧表示しています。

Python
dbutils.secrets.listScopes()

# Out[14]: [SecretScope(name='my-scope')]

ウィジェット・ユーティリティ (dbutils.widgets)​

widgets ユーティリティを使用すると、ノートブックをパラメーター化できます。 「Databricks ウィジェット」を参照してください。

次の表に、このユーティリティで使用可能なコマンドを示します。これらのコマンドは、 dbutils.widgets.help()を使用して取得できます。

コマンド

説明

コンボボックス

指定された名前、デフォルト値、および選択肢を持つコンボボックス入力ウィジェットを作成します

ドロップダウン

ドロップダウン入力ウィジェットaを、指定された名前、デフォルト値、および選択肢で作成します

取得

入力ウィジェットの現在の値を取得します

すべて取得

すべてのウィジェット名とその値のマップを取得します

引数を取得する

廃止。 get と同等

複数選択

複数選択入力ウィジェットを、指定された名前、デフォルト値、および選択肢で作成します

REMOVE

ノートブックから入力ウィジェットを削除します

すべて削除します

ノートブック内のすべてのウィジェットを削除します

TEXT

指定された名前とデフォルト値を持つテキスト入力ウィジェットを作成します

combobox コマンド (dbutils.widgets.combobox)​

combobox(name: String, defaultValue: String, choices: Seq, label: String): void

指定されたプログラム名、デフォルト値、選択肢、およびオプションのラベルを使用してcomboboxウィジェットを作成し、表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("combobox")

例​

この例では、プログラム名が fruits_combobox のcomboboxウィジェットを作成して表示します。apple 、banana 、coconut、dragon fruit の選択肢が提供され、初期値は banana に設定されます。このcomboboxウィジェットには Fruits というラベルが付いています。この例は、comboboxウィジェットの初期値 banana を出力して終了します。

Python
dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=['apple', 'banana', 'coconut', 'dragon fruit'],
  label='Fruits'
)

print(dbutils.widgets.get("fruits_combobox"))

# banana

ドロップダウン コマンド (dbutils.widgets.ドロップダウン)​

dropdown(name: String, defaultValue: String, choices: Seq, label: String): void

指定されたプログラム名、デフォルト値、選択肢、およびオプションのラベルを持つdropdownウィジェットを作成して表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("dropdown")

例​

この例では、toys_dropdown というプログラム名のdropdownウィジェットを作成して表示します。alphabet blocks 、basketball 、cape、doll の選択肢が提供され、初期値は basketball に設定されます。この dropdownウィジェットには Toys というラベルが付いています。この例は、dropdownウィジェットの初期値：basketball を出力することで終了します。

Python
dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=['alphabet blocks', 'basketball', 'cape', 'doll'],
  label='Toys'
)

print(dbutils.widgets.get("toys_dropdown"))

# basketball

get コマンド (dbutils.widgets.get)​

get(name: String): String

指定されたプログラム名を持つウィジェットの現在値を取得します。このプログラム名は、次のいずれかになります。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("get")

例​

この例では、fruits_combobox というプログラム名を持つウィジェットの値を取得します。

Python
dbutils.widgets.get('fruits_combobox')

# banana

この例では、プログラム名が age であるノートブック・タスク・パラメーターの値を取得します。関連するノートブック・タスクの実行時に、このパラメーターは 35 に設定されました。

Python
dbutils.widgets.get('age')

# 35

getAll コマンド (dbutils.widgets.getAll)​

getAll: map

現在のすべてのウィジェットの名前と値のマッピングを取得します。 これは、ウィジェットの値を spark.sql() クエリにすばやく渡す場合に特に便利です。

このコマンドは、Databricks Runtime 13.3 LTS 以降で使用できます。 PythonとScalaでのみ使用できます。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("getAll")

例​

この例では、ウィジェット値のマップを取得し、それを Spark SQL クエリのパラメーター引数として渡します。

Python
df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()

# Query output

getArgument コマンド (dbutils.widgets.getArgument)​

getArgument(name: String, optional: String): String

指定されたプログラム名を持つウィジェットの現在値を取得します。ウィジェットが存在しない場合は、オプションのメッセージを返すことができます。

注記

このコマンドは非推奨です。 代わりに dbutils.widgets.get を使用してください。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("getArgument")

例​

この例では、fruits_combobox というプログラム名を持つウィジェットの値を取得します。このウィジェットが存在しない場合は、Error: Cannot find fruits combobox というメッセージが返されます。

Python
dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'

multiselect コマンド (dbutils.widgets.multiselect)​

multiselect(name: String, defaultValue: String, choices: Seq, label: String): void

指定されたプログラム名、デフォルト値、選択肢、およびオプションのラベルを持つ複数選択ウィジェットを作成して表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("multiselect")

例​

この例では、days_multiselect というプログラム名のウィジェットを作成して表示します。Monday から Sunday までの選択肢があり、初期値は Tuesday に設定されます。この複数選択ウィジェットには Days of the Week というラベルが付いています。この例は、複数選択ウィジェットの初期値：Tuesday を出力することで終了します。

Python
dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'],
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# Tuesday

remove コマンド (dbutils.widgets.remove)​

remove(name: String): void

指定したプログラム名を持つウィジェットを削除します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("remove")
important

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

例​

この例では、プログラム上の名前が fruits_combobox のウィジェットを削除します。

Python
dbutils.widgets.remove('fruits_combobox')

removeAll コマンド (dbutils.widgets.removeAll)​

removeAll: void

ノートブックからすべてのウィジェットを削除します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("removeAll")
important

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

例​

この例では、ノートブックからすべてのウィジェットを削除します。

Python
dbutils.widgets.removeAll()

テキスト・コマンド (dbutils.widgets.text)​

text(name: String, defaultValue: String, label: String): void

指定されたプログラム名、デフォルト値、およびオプションのラベルを持つテキスト・ウィジェットを作成し、表示します。

このコマンドの完全なヘルプを表示するには、次のコマンドを実行します。

dbutils.widgets.help("text")

例​

この例では、プログラム名 your_name_textのテキスト・ウィジェットを作成して表示します。初期値は Enter your name に設定されます。このテキスト・ウィジェットには、Your name というラベルが付いています。この例は、テキスト・ウィジェットの初期値：Enter your name を出力することで終了します。

Python
dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

print(dbutils.widgets.get("your_name_text"))

# Enter your name

Databricks ユーティリティ API ライブラリ​

important

Databricks ユーティリティ API (dbutils-api) ライブラリは廃止されました。Databricks では、代わりに次のいずれかを使用することをお勧めします。

アプリケーションを実稼働ジョブとしてデプロイする前に、アプリケーションをコンパイル、構築、テストすると、アプリケーション開発を加速するのに役立ちます。Databricksユーティリティに対してコンパイルできるようにするために、Databricksは dbutils-api ライブラリを提供します。Maven RepositoryウェブサイトのDBUtils APIウェブページから dbutils-api ライブラリをダウンロードするか、ビルドファイルに依存関係を追加してライブラリをインクルードすることができます。

  • SBT

    Scala
    libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"

  • Maven

    XML
    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_TARGET</artifactId>
        <version>VERSION</version>
    </dependency>

  • Gradle

    Bash
    compile 'com.databricks:dbutils-api_TARGET:VERSION'

TARGET を目的のターゲット (2.12など) に置き換え、VERSION を目的のバージョン (0.0.5など) に置き換えます。使用可能なターゲットとバージョンの一覧については、Maven リポジトリ Web サイトの DBUtils API Web ページを参照してください。

このライブラリに対してアプリケーションを構築すると、アプリケーションをデプロイできます。

important

dbutils-api ライブラリでは、 dbutilsを使用するアプリケーションをローカルでコンパイルすることしかできず、実行できません。アプリケーションを実行するには、Databricks にデプロイする必要があります。

制限​

エグゼキューターの内部で dbutils を呼び出すと、予期しない結果やエラーが発生する可能性があります。

dbutilsを使用してエグゼキューター上でファイルシステム操作を実行する必要がある場合は、ファイルシステム操作の並列化を参照してください。

エグゼキューターの詳細については、Apache Sparkウェブサイトの「クラスターモードの概要」を参照してください。

に最終更新