次の方法で共有

Databricks Utilities (dbutils) リファレンス

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

注

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

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

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

モジュール 説明
データ データセットを理解および操作するためのユーティリティ (EXPERIMENTAL)
fs Databricks ファイル システム (DBFS) にアクセスするためのユーティリティ
仕事 ジョブ機能を活用するためのユーティリティ
図書館 非推奨になりました。 セッション スコープ ライブラリを管理するためのユーティリティ
ノートパソコン ノートブックの制御フローを管理するためのユーティリティ (試験段階)
秘密 ノートブック内のシークレットを活用するためのユーティリティ
ウィジェット ノートブックをパラメーター化するためのユーティリティ。
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>")を実行します。 次の例では、ファイル・システム・ユーティリティーのコピー・コマンドのヘルプを表示 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

data ユーティリティ (dbutils.data)

重要

この機能はパブリック プレビュー段階にあります。

注

Databricks Runtime 9.0 以降で使用できます。

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

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

コマンド 説明
要約 Spark DataFrame を要約し、統計を視覚化してすばやく分析情報を取得する

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

注

この機能はパブリック プレビュー段階にあります。

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

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

重要

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

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

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 の概要統計情報が表示されます。 結果を表示するには、ノートブックでこのコマンドを実行します。 この例は、サンプル データセットに基づいています。

Python（プログラミング言語）
df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)
R
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 と表示されます。 例外として、視覚化では、B (1.0e9) に対して、"" ではなく "G" が使用されます。

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

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

警告

すべての dbutils.fs メソッドの Python 実装では、キーワードの書式設定では snake_case ではなく camelCase を使用します。

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

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

コマンド 説明
を cp する ファイルまたはディレクトリを、場合によっては FileSystems 間でコピーする。
頭 指定されたファイルの最初の 'maxBytes' バイトまでを UTF-8 でエンコードされた文字列として返します。
ls ディレクトリの内容を一覧表示します
mkdirs 指定されたディレクトリが存在しない場合は作成し、必要な親ディレクトリも作成します
マウント 指定されたマウント ポイントで、指定されたソース ディレクトリを DBFS にマウントします。
マウント DBFS 内にマウントされている内容に関する情報を表示します
mv ファイルまたはディレクトリを FileSystems 間で移動する
置く 指定された文字列を UTF-8 でエンコードされたファイルに書き込みます
refreshMounts このクラスター内のすべてのマシンにマウント キャッシュの更新を強制し、最新の情報を確実に受け取ります
マイクロメートル ファイルまたはディレクトリを削除します
アンマウント 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 にコピーします。

Python（プログラミング言語）
dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

# Out[4]: True
R
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")

例

この例では、data.csv にあるファイル /Volumes/main/default/my-volume/ の最初の 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'
R
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 は文字列として返されます。

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

例

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

Python（プログラミング言語）
dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

# Out[15]: True
R
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")

例

Python（プログラミング言語）
dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
スカラ (プログラミング言語)
dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
  mountPoint = "/mnt/<mount-name>",
  extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))

その他のコード例については、「 Azure Data Lake Storage と Blob Storage への接続」を参照してください。

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

mounts: Seq

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

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

dbutils.fs.help("mounts")

例

警告

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

Python（プログラミング言語）
dbutils.fs.mounts()
スカラ (プログラミング言語)
dbutils.fs.mounts()

その他のコード例については、「 Azure Data Lake Storage と Blob Storage への接続」を参照してください。

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
R
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! を hello.txt 内の /Volumes/main/default/my-volume/ という名前のファイルに書き込みます。 このファイルが存在する場合、上書きされます。

Python（プログラミング言語）
dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

# Wrote 2258987 bytes.
# Out[6]: True
R
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")

例

Python（プログラミング言語）
dbutils.fs.refreshMounts()
スカラ (プログラミング言語)
dbutils.fs.refreshMounts()

追加コードの例については、「 Azure Data Lake Storage と Blob Storage への接続」を参照してください。

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

その他のコード例については、「 Azure Data Lake Storage と Blob Storage への接続」を参照してください。

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（プログラミング言語）
dbutils.fs.updateMount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})
スカラ (プログラミング言語)
dbutils.fs.updateMount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net/<directory-name>",
  mountPoint = "/mnt/<mount-name>",
  extraConfigs = Map("<conf-key>" -> dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")))

Jobs ユーティリティ (dbutils.jobs)

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

注

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

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

サブモジュール 説明
taskValues ジョブタスクの値を活用するためのツールを提供します

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

注

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

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

このサブユーティリティを使用して、ジョブの実行中に任意の値を設定および取得します。 これらの値は "タスク値" と呼ばれます。 どのタスクでも、アップストリーム タスクによって設定された値を取得し、ダウンストリーム タスクで使用する値を設定できます。

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

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

コマンド 説明
取得する 現在のジョブ実行で、指定したタスクの指定したタスク値の内容を取得します。
セット タスク値を設定または更新します。 1 つのジョブ実行に対して、最大 250 個のタスク値を設定できます。

get コマンド (dbutils.jobs.taskValues.get)

注

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

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

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.jobs.taskValues.set) で設定したタスク値のキーの名前です。 コマンドでこのタスク値のキーが見つからない場合は、(ValueErrorが指定されていない限り) defaultが発生します。
  • default は、key が見つからない場合に返される省略可能な値です。 default に None は指定できません。
  • debugValue は、ジョブの外部で実行されているノートブック内からタスク値を取得しようとすると返される省略可能な値です。 これは、ノートブックを手動で実行し、デバッグ中に既定で TypeError を発生させるのではなく値を返す場合に役立ちます。 debugValue に None は指定できません。

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

set コマンド (dbutils.jobs.taskValues.set)

注

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

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

タスク値を設定または更新します。 1 つのジョブ実行に対して、最大 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 以下にする必要があります。

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

Library ユーティリティ (dbutils.library)

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

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

notebook ユーティリティ (dbutils.notebook)

notebook ユーティリティを使用すると、ノートブックをチェーンし、その結果に基いて処理を行うことができます。 「ノートブックを調整し、ノートブック内のコードをモジュール化する」を参照してください。

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

コマンド 説明
出口 ノートブックを終了し、値を返します。
走る ノートブックを実行し、その終了値を返します

exit コマンド (dbutils.notebook.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
R
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 です。 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.notebook.run("My Other Notebook", 60)

// res2: String = Exiting from My Other Notebook

secrets ユーティリティ (dbutils.secrets)

secrets ユーティリティを使用すると、機密の資格情報がノートブックに表示されないようにして、それらの情報を保存でき、またそれらの情報にアクセスできます。 「 シークレットの管理 と 手順 3: ノートブックでシークレットを使用するを参照してください。

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

コマンド 説明
取得する スコープとキーを持つシークレット値の文字列表現を取得します。
getBytes スコープとキーを持つシークレット値のバイト表現を取得します。
一覧 スコープ内のシークレットのメタデータを一覧表示します
listScopes シークレット スコープを一覧表示します

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

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

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

警告

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

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

dbutils.secrets.help("get")

例

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

Python（プログラミング言語）
dbutils.secrets.get(scope="my-scope", key="my-key")

# Out[14]: '[REDACTED]'
R
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")

例

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

Python（プログラミング言語）
dbutils.secrets.getBytes(scope="my-scope", key="my-key")

# Out[1]: b'a1!b2@c3#'
R
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 という名前のスコープ内のシークレットのメタデータを一覧表示します。

Python（プログラミング言語）
dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]
R
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")

例

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

Python（プログラミング言語）
dbutils.secrets.listScopes()

# Out[14]: [SecretScope(name='my-scope')]
R
dbutils.secrets.listScopes()

# [[1]]
# [[1]]$name
# [1] "my-scope"
スカラ (プログラミング言語)
dbutils.secrets.listScopes()

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

widgets ユーティリティ (dbutils.widgets)

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

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

コマンド 説明
コンボボックス 指定された名前、既定値、選択肢を含むコンボボックス入力ウィジェットを作成します
ドロップダウン 指定された名前、既定値、選択肢を持つドロップダウン入力ウィジェット a を作成します
取得する 入力ウィジェットの現在の値を取得します。
getAll すべてのウィジェット名とその値のマップを取得します
getArgument 非推奨になりました。 get と同等
multiselect 指定された名前、既定値、選択肢を使用して、複数選択入力ウィジェットを作成します
取り去る ノートブックから入力ウィジェットを削除します
removeAll ノートブック内のすべてのウィジェットを削除します
テキスト 指定された名前と既定値を使用してテキスト入力ウィジェットを作成します

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

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

プログラム名、既定値、選択肢、ラベル (省略可能) を指定して、コンボボックス ウィジェットを作成して表示します。

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

dbutils.widgets.help("combobox")

例

この例では、プログラム名が fruits_combobox のコンボボックス ウィジェットを作成して表示します。 選択肢として apple、banana、coconut、dragon fruit を用意しており、初期値は banana に設定しています。 このコンボボックス ウィジェットには、Fruits というラベルが付加されます。 この例は、コンボボックス ウィジェットの初期値である 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
R
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
SQL
CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

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

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

プログラム名、既定値、選択肢、ラベル (省略可能) を指定して、ドロップダウン ウィジェットを作成して表示します。

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

dbutils.widgets.help("dropdown")

例

この例では、プログラム名が toys_dropdown のドロップダウン ウィジェットを作成して表示します。 選択肢として alphabet blocks、basketball、cape、doll を用意しており、初期値は basketball に設定しています。 このドロップダウン ウィジェットには、Toys というラベルが付加されます。 この例は、ドロップダウン ウィジェットの初期値である 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
R
dbutils.widgets.dropdown(
  name='toys_dropdown',
  defaultValue='basketball',
  choices=list('alphabet blocks', 'basketball', 'cape', 'doll'),
  label='Toys'
)

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

# [1] "basketball"
スカラ (プログラミング言語)
dbutils.widgets.dropdown(
  "toys_dropdown",
  "basketball",
  Array("alphabet blocks", "basketball", "cape", "doll"),
  "Toys"
)

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

// basketball
SQL
CREATE WIDGET DROPDOWN toys_dropdown DEFAULT "basketball" CHOICES SELECT * FROM (VALUES ("alphabet blocks"), ("basketball"), ("cape"), ("doll"))

SELECT :toys_dropdown

-- basketball

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

get(name: String): String

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

  • ノートブック内のカスタム ウィジェットの名前 ( fruits_combobox や toys_dropdownなど)。
  • ノートブック タスクの一部としてノートブックに渡されるカスタム パラメーターの名前 (例: name、age など)。 詳細については、ジョブ UI のノートブック タスクのパラメーターの対象範囲を参照するか、Jobs API のnotebook_params () オペレーションの POST /jobs/run-now フィールドを参照してください。

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

dbutils.widgets.help("get")

例

この例では、プログラム名が fruits_combobox であるウィジェットの値を取得します。

Python（プログラミング言語）
dbutils.widgets.get('fruits_combobox')

# banana
R
dbutils.widgets.get('fruits_combobox')

# [1] "banana"
スカラ (プログラミング言語)
dbutils.widgets.get("fruits_combobox")

// res6: String = banana
SQL
SELECT :fruits_combobox

-- banana

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

Python（プログラミング言語）
dbutils.widgets.get('age')

# 35
R
dbutils.widgets.get('age')

# [1] "35"
スカラ (プログラミング言語)
dbutils.widgets.get("age")

// res6: String = 35
SQL
SELECT :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
スカラ (プログラミング言語)
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 が返されます。

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

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

重要

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

例

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

Python（プログラミング言語）
dbutils.widgets.remove('fruits_combobox')
R
dbutils.widgets.remove('fruits_combobox')
スカラ (プログラミング言語)
dbutils.widgets.remove("fruits_combobox")
SQL
REMOVE WIDGET fruits_combobox

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

removeAll: void

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

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

dbutils.widgets.help("removeAll")

重要

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

例

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

Python（プログラミング言語）
dbutils.widgets.removeAll()
R
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 を出力して終了します。

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
R
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
SQL
CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

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

重要

Databricks Utilities API (dbutils-api) ライブラリは 非推奨です。 Databricks では、代わりに次のいずれかを使用することをお勧めします。

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

  • SBT

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

  • メーヴェン

    <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を使用するアプリケーションをローカルでコンパイルすることしかできません。アプリケーションを実行することはできません。 アプリケーションを実行するには、そのアプリケーションを Azure Databricks にデプロイする必要があります。

制限事項

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

dbutilsを使用して Executor でファイル システム操作を実行する必要がある場合は、「ファイルシステム操作の並列化」を参照してください。

実行プログラムについて詳しくは、Apache Spark の Web サイトでクラスター モードの概要に関する記事を参照してください。