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

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

/**
* 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）

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

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

コマンド

説明

assumeRole

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

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

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

showRoles(ロールズを表示)

引き受け可能なロールのセットが表示されます。

assignRoleコマンド（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")

例 

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

# Out[1]: True

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

# TRUE

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

// res0: Boolean = true

showCurrentRoleコマンド（dbutils.credentials.showCurrentRole）

showCurrentRole: List

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

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

dbutils.credentials.help("showCurrentRole")

例 

dbutils.credentials.showCurrentRole()

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

dbutils.credentials.showCurrentRole()

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

dbutils.credentials.showCurrentRole()

// res0: java.util.List[String] = [arn:aws:iam::123456789012:role/my-role-a]

showRolesコマンド（dbutils.credentials.showRoles）

showRoles: List

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

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

dbutils.credentials.help("showRoles")

例 

dbutils.credentials.showRoles()

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

dbutils.credentials.showRoles()

# [[1]]
# [1] "arn:aws:iam::123456789012:role/my-role-a"
#
# [[2]]
# [1] "arn:aws:iam::123456789012:role/my-role-b"

dbutils.credentials.showRoles()

// res0: java.util.List[String] = [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 DataFrameをまとめ、統計を可視化して迅速な知見を得る

要約コマンド（dbutils.data.summarize）

注：

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

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

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

重要：

このコマンドは、DataFrame の完全な内容を分析します。 非常に大きな DataFrames に対してこのコマンドを実行すると、非常にコストがかかる可能性があります。

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

dbutils.data.help("summarize")

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

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

    • カテゴリ列の異なる値の数には、カーディナリティの高い列の場合、最大5%の相対誤差が生じる可能性があります。

    • 異なる値の数が10000を超える場合、頻繁に発生する値のカウントには最大 0.01%の誤差が生じる可能性があります。

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

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

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

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

例

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

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

df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)

val df = spark.read.format("csv")
  .option("inferSchema", "true")
  .option("header", "true")
  .load("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv")
dbutils.data.summarize(df)

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

ファイルシステム・ユーティリティ（dbutils.fs）

ファイル システム ユーティリティを使用すると、「DBFS とは何か?」にアクセスできるため、Databricks をファイル システムとして簡単に使用できるようになります。

警告：

すべての 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

ファイルまたはディレクトリを (場合によっては FileSystems 間で) 移動します。

置く

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

リフレッシュマウント

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

マイクロメートル

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

アンマウント

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

updateMount (更新マウント)

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 にコピーします。

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

# Out[4]: True

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

# [1] TRUE

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

// res3: Boolean = 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バイトを表示しています。

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

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

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

# [1] "Year,First Name,County,Se"

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

// [Truncated to first 25 bytes]
// res4: String =
// "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文字列として返されます。

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

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

# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`

# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"

# [[1]]$name
# [1] "data.csv"

# [[1]]$size
# [1] 2258987

# [[1]]$isDir
# [1] FALSE

# [[1]]$isFile
# [1] TRUE

# [[1]]$modificationTime
# [1] "1711357839000"

dbutils.fs.ls("/tmp")

// res6: Seq[com.databricks.backend.daemon.dbutils.FileInfo] = WrappedArray(FileInfo(/Volumes/main/default/my-volume/data.csv, 2258987, 1711357839000))

mkdirsコマンド（dbutils.fs.mkdirs）

mkdirs(dir: String): boolean

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

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

dbutils.fs.help("mkdirs")

例

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

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

# Out[15]: True

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

# [1] TRUE

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

// res7: Boolean = 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")

例 

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

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

val AwsBucketName = "my-bucket"
val MountName = "s3-my-bucket"

dbutils.fs.mount(s"s3a://$AwsBucketName", s"/mnt/$MountName")

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

mountsコマンド（dbutils.fs.mounts）

mounts: Seq

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

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

dbutils.fs.help("mounts")

例

警告：

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

dbutils.fs.mounts()

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

dbutils.fs.mounts()

その他のコード例については、「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/ に移動します。

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

# Out[2]: True

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

# [1] TRUE

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

// res1: Boolean = 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 という名前のファイルに書き込みます。ファイルがすでに存在する場合は、上書きされます。

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

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

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

# [1] TRUE

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

// Wrote 2258987 bytes.
// res2: Boolean = true

refreshMountsコマンド（dbutils.fs.refreshMounts）

refreshMounts: boolean

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

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

dbutils.fs.help("refreshMounts")

例 

dbutils.fs.refreshMounts()

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/ とその内容全体を削除します。

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

# Out[8]: True

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

# [1] TRUE

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

// res6: Boolean = true

unmountコマンド（dbutils.fs.unmount）

unmount(mountPoint: String): boolean

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

警告：

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

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

dbutils.fs.help("unmount")

例 

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

例 

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

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

val AwsBucketName = "my-bucket"
val MountName = "s3-my-bucket"

dbutils.fs.updateMount(s"s3a://$AwsBucketName", s"/mnt/$MountName")

ジョブ・ユーティリティ（dbutils.jobs）

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

注：

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

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

サブモジュール

説明

タスクバリュー

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

taskValuesサブユーティリティ（dbutils.jobs.taskValues）

注：

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

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

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

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

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

コマンド

説明

取得

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

SET

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

getコマンド（dbutils.jobs.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")

例

例：

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.jobs.taskValues.set）

注：

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

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

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

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

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

例

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

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.library) (レガシー)」を参照してください。

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

ノートブック・ユーティリティ（dbutils.notebook）

ノートブック・ユーティリティを使用すると、ノートブックを連結し、その結果に基づいて操作できます。Databricksノートブックを別のノートブックから実行するを参照してください。

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

コマンド

説明

出口

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

実行

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

終了コマンド（dbutils.notebook.exit）

exit(value: String): void

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

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

dbutils.notebook.help("exit")

例

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

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

# Notebook exited: Exiting from My Other Notebook

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

# Notebook exited: Exiting from My Other Notebook

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

// Notebook exited: Exiting from My Other Notebook

注：

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

runコマンド（dbutils.notebook.run）

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

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

注：

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

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

dbutils.notebook.help("run")

例

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

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

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

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

// res2: String = 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という名前のキーのシークレット値の文字列表現を取得します。

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

# Out[14]: '[REDACTED]'

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

# [1] "[REDACTED]"

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

// res0: String = [REDACTED]

getBytesコマンド（dbutils.secrets.getBytes）

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

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

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

dbutils.secrets.help("getBytes")

例

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

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

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

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

# [1] 61 31 21 62 32 40 63 33 23

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

// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)

listコマンド（dbutils.secrets.list）

list(scope: String): Seq

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

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

dbutils.secrets.help("list")

例

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

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

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

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

# [[1]]
# [[1]]$key
# [1] "my-key"

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

// res2: Seq[com.databricks.dbutils_v1.SecretMetadata] = ArrayBuffer(SecretMetadata(my-key))

listScopesコマンド（dbutils.secrets.listScopes）

listScopes: Seq

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

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

dbutils.secrets.help("listScopes")

例

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

dbutils.secrets.listScopes()

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

dbutils.secrets.listScopes()

# [[1]]
# [[1]]$name
# [1] "my-scope"

dbutils.secrets.listScopes()

// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))

ウィジェット・ユーティリティ（dbutils.widgets）

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

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

コマンド

説明

コンボボックス

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

ドロップダウン

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

取得

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

getAll (すべて)

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

getArgument

廃止。 get と同等

複数選択

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

取り去る

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

すべて削除

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

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 を出力して終了します。

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.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=list('apple', 'banana', 'coconut', 'dragon fruit'),
  label='Fruits'
)

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

# [1] "banana"

dbutils.widgets.combobox(
  "fruits_combobox",
  "banana",
  Array("apple", "banana", "coconut", "dragon fruit"),
  "Fruits"
)

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

// banana

CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

getコマンド（dbutils.widgets.get）

get(name: String): String

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

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

dbutils.widgets.help("get")

例

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

dbutils.widgets.get('fruits_combobox')

# banana

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

SELECT :fruits_combobox

-- banana

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

dbutils.widgets.get('age')

# 35

dbutils.widgets.get('age')

# [1] "35"

dbutils.widgets.get("age")

// res6: String = 35

SELECT :age

-- 35

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

getAll: map

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

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

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

dbutils.widgets.help("getAll")

例

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

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

# Query output

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

// res6: 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 というメッセージが返されます。

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'

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.
# [1] "banana"

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

// command-1234567890123456:1: warning: method getArgument in trait WidgetsUtils is deprecated: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
// dbutils.widgets.getArgument("fruits_combobox", "Error: Cannot find fruits combobox")
//                 ^
// res7: String = 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 を出力することで終了します。

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

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

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

# [1] "Tuesday"

dbutils.widgets.multiselect(
  "days_multiselect",
  "Tuesday",
  Array("Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"),
  "Days of the Week"
)

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

// Tuesday

CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))

SELECT :days_multiselect

-- Tuesday

removeコマンド（dbutils.widgets.remove）

remove(name: String): void

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

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

dbutils.widgets.help("remove")

重要：

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

例

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

dbutils.widgets.remove('fruits_combobox')

dbutils.widgets.remove('fruits_combobox')

dbutils.widgets.remove("fruits_combobox")

REMOVE WIDGET fruits_combobox

removeAllコマンド（dbutils.widgets.removeAll）

removeAll: void

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

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

dbutils.widgets.help("removeAll")

重要：

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

例

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

dbutils.widgets.removeAll()

dbutils.widgets.removeAll()

dbutils.widgets.removeAll()

textコマンド（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 を出力することで終了します。

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

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

# Enter your name

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

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

# [1] "Enter your name"

dbutils.widgets.text(
  "your_name_text",
  "Enter your name",
  "Your name"
)

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

// Enter your name

CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

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

重要：

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

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

  • SBT

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

  • Maven

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

  • Gradle

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

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

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

重要：

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

制限事項

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

を使用してエグゼキューターのファイルシステム操作を実行する必要がある場合は、dbutils でファイルを高速にリストおよび削除する方法Spark の Databricksを使用した並列リストおよび削除の方法を参照してください。

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