Databricks ユーティリティ Databricks Utilities

Databricks Utilities (DBUtils) を使用すると、タスクの強力な組み合わせを簡単に実行できます。Databricks Utilities (DBUtils) make it easy to perform powerful combinations of tasks. ユーティリティを使用して、オブジェクトストレージを効率的に操作したり、ノートブックのチェーン化とパラメーター化を行ったり、シークレットを操作したりすることができます。You can use the utilities to work with object storage efficiently, to chain and parameterize notebooks, and to work with secrets.

すべての dbutils ユーティリティは、Python、R、および拡張性のあるノートブックで利用できます。All dbutils utilities are available in Python, R, and Scala notebooks. ファイルシステムユーティリティは、R notebook では使用できません。ただし、言語マジックコマンドを使用して、R および SQL notebook でこれらの dbutils メソッドを呼び出すことができます。File system utilities are not available in R notebooks; however, you can use a language magic command to invoke those dbutils methods in R and SQL notebooks. たとえば、R または SQL notebook 内のAzure Databricks データセットDBFS フォルダーの一覧を表示するには、次のコマンドを実行します。For example, to list the Azure Databricks Datasets DBFS folder in an R or SQL notebook, run the command:

%python
dbutils.fs.ls("/databricks-datasets")

または、%fsを使用することもできます。Alternatively, you can use %fs:

%fs ls /databricks-datasets

このトピックには、次のセクションが含まれています。This topic includes the following sections:

ファイルシステムユーティリティ File system utilities

ファイルシステムユーティリティはDatabricks ファイルシステムにアクセスするため、ファイルシステムとして Azure Databricks を簡単に使用できます。The file system utilities access Databricks File System, making it easier to use Azure Databricks as a file system. 詳細については、次を実行してください。Learn more by running:

dbutils.fs.help()
cp(from: String, to: String, recurse: boolean = false): boolean -> Copies a file or directory, possibly across FileSystems
head(file: String, maxBytes: int = 65536): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
ls(dir: String): Seq -> Lists the contents of a directory
mkdirs(dir: String): boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
mv(from: String, to: String, recurse: boolean = false): boolean -> Moves a file or directory, possibly across FileSystems
put(file: String, contents: String, overwrite: boolean = false): boolean -> Writes the given String out to a file, encoded in UTF-8
rm(dir: String, recurse: boolean = false): boolean -> Removes a file or directory

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Mounts the given source directory into DBFS at the given mount point
mounts: Seq -> Displays information about what is mounted within DBFS
refreshMounts: boolean -> Forces all machines in this cluster to refresh their mount cache, ensuring they receive the most recent information
unmount(mountPoint: String): boolean -> Deletes a DBFS mount point

dbutils.fs.ls コマンドdbutils.fs.ls Command

ls コマンドによって返されるシーケンスには、次の属性が含まれています。The sequence returned by the ls command contains the following attributes:

AttributeAttribute タイプType descriptionDescription
パスpath stringstring ファイルまたはディレクトリのパス。The path of the file or directory.
名前name stringstring ファイルまたはディレクトリの名前。The name of the file or directory.
isDir ()isDir() Booleanboolean パスがディレクトリである場合は True。True if the path is a directory.
sizesize long/int64long/int64 ファイルの長さ (バイト単位)。または、パスがディレクトリの場合は0。The length of the file in bytes or zero if the path is a directory.

注意

各コマンドの詳細情報は、help を使用して取得できます。例: dbutils.fs.help("ls")You can get detailed information about each command by using help, for example: dbutils.fs.help("ls")

Notebook のワークフローユーティリティ Notebook workflow utilities

Notebook ワークフローを使用すると、ノートブックをまとめて、その結果を操作できます。Notebook workflows allow you to chain together notebooks and act on their results. Notebook ワークフロー」を参照してください。See Notebook Workflows. 詳細については、次を実行してください。Learn more by running:

dbutils.notebook.help()
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.

注意

run から返される文字列値の最大長は 5 MB です。The maximum length of the string value returned from run is 5 MB. 実行の取得」を参照してください。See Runs Get Output.

注意

各コマンドの詳細情報は、help を使用して取得できます。例: dbutils.notebook.help("exit")You can get detailed information about each command by using help, for example: dbutils.notebook.help("exit")

ウィジェットユーティリティ Widget utilities

ウィジェットを使用すると、ノートブックのパラメーター化を行うことができます。Widgets allow you to parameterize notebooks. ウィジェット」を参照してください。See Widgets. 詳細については、次を実行してください。Learn more by running:

dbutils.widgets.help()
combobox(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a combobox input widget with a given name, default value and choices
dropdown(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a dropdown input widget a with given name, default value and choices
get(name: String): String -> Retrieves current value of an input widget
getArgument(name: String, optional: String): String -> (DEPRECATED) Equivalent to get
multiselect(name: String, defaultValue: String, choices: Seq, label: String): void -> Creates a multiselect input widget with a given name, default value and choices
remove(name: String): void -> Removes an input widget from the notebook
removeAll: void -> Removes all widgets in the notebook
text(name: String, defaultValue: String, label: String): void -> Creates a text input widget with a given name and default value

注意

各コマンドの詳細情報は、help を使用して取得できます。例: dbutils.widgets.help("combobox")You can get detailed information about each command by using help, for example: dbutils.widgets.help("combobox")

シークレットユーティリティ Secrets utilities

シークレットを使用すると、ノートブックに表示されることなく、機密情報を格納してアクセスすることができます。Secrets allow you to store and access sensitive credential information without making them visible in notebooks. シークレットを参照し、ノートブックでシークレットを使用します。See Secrets and Use the secrets in a notebook. 詳細については、次を実行してください。Learn more by running:

注意

シークレットユーティリティは Databricks Runtime 4.0 以降を実行しているクラスターで使用できます。Secrets utilities are available on clusters running Databricks Runtime 4.0 and above.

dbutils.secrets.help()
get(scope: String, key: String): String -> Gets the string representation of a secret value with scope and key
getBytes(scope: String, key: String): byte[] -> Gets the bytes representation of a secret value with scope and key
list(scope: String): Seq -> Lists secret metadata for secrets within a scope
listScopes: Seq -> Lists secret scopes

注意

各コマンドの詳細情報は、help を使用して取得できます。例: dbutils.secrets.help("get")You can get detailed information about each command by using help, for example: dbutils.secrets.help("get")

ライブラリユーティリティ Library utilities

ライブラリユーティリティを使用すると、Python ライブラリをインストールし、ノートブックセッションにスコープを設定した環境を作成できます。Library utilities allow you to install Python libraries and create an environment scoped to a notebook session. ライブラリは、ドライバーと実行プログラムの両方で使用できるので、Udf で参照できます。The libraries are available both on the driver and on the executors, so you can reference them in UDFs. これにより以下のことが実現されます。This enables:

  • Notebook 内で整理される notebook のライブラリの依存関係。Library dependencies of a notebook to be organized within the notebook itself.
  • 異なるライブラリの依存関係を持つ Notebook ユーザーが、干渉なしでクラスターを共有します。Notebook users with different library dependencies to share a cluster without interference.

ノートブックをデタッチすると、この環境が破棄します。Detaching a notebook destroys this environment. ただし、notebook でライブラリ install API コマンドを再実行することによって、再作成することができます。However, you can recreate it by re-running the library install API commands in the notebook. 環境を損なうことなくノートブックの状態をリセットする方法については、restartPython API を参照してください。See the restartPython API for how you can reset your notebook state without losing your environment.

Databricks Runtime 5.1 以降を実行しているクラスターでは、ライブラリユーティリティが既定で有効になっています。Library utilities are enabled by default on clusters running Databricks Runtime 5.1 and above. したがって、既定では、各ノートブックの Python 環境は、notebook がに接続され、クラスターの既定の Python 環境を継承するときに作成される別の Python 実行可能ファイルを使用して分離されます。Therefore, by default the Python environment for each notebook is isolated by using a separate Python executable that is created when the notebook is attached to and inherits the default Python environment on the cluster. Init スクリプトによって Azure Databricks Python 環境にインストールされたライブラリは引き続き利用できます。Libraries installed through an init script into the Azure Databricks Python environment are still available. この機能を無効にするには、spark.databricks.libraryIsolation.enabledfalse に設定します。You can disable this feature by setting spark.databricks.libraryIsolation.enabled to false.

この API は、ライブラリをインストールするために推奨される方法として設計されています。This API is designed to be preferred way to install libraries. UIREST APIを通じて、既存のクラスター全体のライブラリのインストールと互換性があります。It is compatible with the existing cluster-wide library installation through the UI and REST API. ただし、この API によってインストールされるライブラリは、クラスター全体のライブラリよりも優先度が_高く_なります。However, libraries installed through this API have higher priority than cluster-wide libraries.

dbutils.library.help()
install(path: String): boolean -> Install the library within the current notebook session
installPyPI(pypiPackage: String, version: String = "", repo: String = "", extras: String = ""): boolean -> Install the PyPI library within the current notebook session
list: List -> List the isolated libraries added for the current notebook session via dbutils
restartPython: void -> Restart python process for the current notebook session

注意

各コマンドの詳細情報は、help を使用して取得できます。例: dbutils.library.help("install")You can get detailed information about each command by using help, for example: dbutils.library.help("install")

Examples

  • Notebook に PyPI ライブラリをインストールします。Install a PyPI library in a notebook. versionrepoextras は省略可能です。version, repo, and extras are optional. extras 引数を使用して、エクストラ機能(追加要件) を指定します。Use the extras argument to specify the Extras feature (extra requirements).

    dbutils.library.installPyPI("pypipackage", version="version", repo="repo", extras="extras")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    重要

    version キーと extras キーは、PyPI パッケージ文字列の一部にすることはできません。The version and extras keys cannot be part of the PyPI package string. 例: dbutils.library.installPyPI("azureml-sdk[databricks]==1.0.8") が有効ではありません。For example: dbutils.library.installPyPI("azureml-sdk[databricks]==1.0.8") is not valid. versionextras の引数を使用して、次のようにバージョンと詳細情報を指定します。Use the version and extras arguments to specify the version and extras information as follows:

    dbutils.library.installPyPI("azureml-sdk", version="1.0.8", extras="databricks")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    
  • 1つのノートブックでライブラリの要件を指定し、別の notebook の %run を使用してインストールします。Specify your library requirements in one notebook and install them through %run in the other.

    • InstallDependenciesと呼ばれる notebook にインストールするライブラリを定義します。Define the libraries to install in a notebook called InstallDependencies.

      dbutils.library.installPyPI("torch")
      dbutils.library.installPyPI("scikit-learn", version="1.19.1")
      dbutils.library.installPyPI("azureml-sdk", extras="databricks")
      dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
      
    • これらの依存関係が必要なノートブックにインストールします。Install them in the notebook that needs those dependencies.

      %run /path/to/InstallDependencies    # Install the dependencies in first cell
      
      import torch
      from sklearn.linear_model import LinearRegression
      import azureml
      # do the actual work
      
  • Notebook にインストールされているライブラリを一覧表示します。List the libraries installed in a notebook.

    dbutils.library.list()
    
  • 環境を維持しながら、Python notebook の状態をリセットします。Reset the Python notebook state while maintaining the environment. この API は Python notebook でのみ使用できます。This API is available only in Python notebooks. これは次の場合に使用できます。This can be used to:

    • 別のバージョンでプレインストールされたライブラリ Azure Databricks 再読み込みします。Reload libraries Azure Databricks preinstalled with a different version. 例えば次が挙げられます。For example:

      dbutils.library.installPyPI("numpy", version="1.15.4")
      dbutils.library.restartPython()
      
      # Make sure you start using the library in another cell.
      import numpy
      
    • プロセスの起動時に読み込む必要がある、整理されたライブラリのようなライブラリをインストールします。Install libraries like tensorflow that need to be loaded on process start up. 例えば次が挙げられます。For example:

      dbutils.library.installPyPI("tensorflow")
      dbutils.library.restartPython()
      
      # Use the library in another cell.
      import tensorflow
      
  • .egg または .whl ライブラリを notebook にインストールします。Install a .egg or .whl library in a notebook.

    重要

    すべてのライブラリインストールコマンドを notebook の最初のセルに配置し、そのセルの最後で restartPython を呼び出すことをお勧めします。We recommend that you put all your library install commands in the first cell of your notebook and call restartPython at the end of that cell. restartPythonを実行すると、Python notebook の状態がリセットされます。ノートブックは、ローカル変数、インポートされたライブラリ、およびその他の一時的な状態を含めて、すべての状態を失います。The Python notebook state is reset after running restartPython; the notebook loses all state including but not limited to local variables, imported libraries, and other ephemeral states. そのため、ライブラリをインストールし、_最初_の notebook セルでノートブックの状態をリセットすることをお勧めします。Therefore, we recommended that you install libraries and reset the notebook state in the first notebook cell.

    許可されるライブラリソースは、dbfsabfssadl、および wasbs です。The accepted library sources are dbfs, abfss, adl, and wasbs.

    dbutils.library.install("abfss:/path/to/your/library.egg")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    
    dbutils.library.install("abfss:/path/to/your/library.whl")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

DBUtils notebookDBUtils notebook

ノートブックを入手Get notebook

Databricks Utilities API ライブラリ Databricks Utilities API library

アプリケーションの開発を加速させるために、アプリケーションを運用ジョブとしてデプロイする前に、アプリケーションのコンパイル、ビルド、テストを行うと便利です。To accelerate application development, it can be helpful to compile, build, and test applications before you deploy them as production jobs. Databricks ユーティリティに対してコンパイルできるようにするために、Databricks には dbutils-api ライブラリが用意されています。To enable you to compile against Databricks Utilities, Databricks provides the dbutils-api library. Dbutils ライブラリをダウンロードするか、ビルドファイルに依存関係を追加してライブラリをインクルードできます。You can download the dbutils-api library or include the library by adding a dependency to your build file:

  • SBTSBT

    libraryDependencies += "com.databricks" % "dbutils-api_2.11" % "0.0.3"
    
  • MavenMaven

    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_2.11</artifactId>
        <version>0.0.3</version>
    </dependency>
    
  • GradleGradle

    compile 'com.databricks:dbutils-api_2.11:0.0.3'
    

このライブラリに対してアプリケーションをビルドしたら、Databricks Runtime 4.0 以降を実行しているクラスターにアプリケーションをデプロイできます。Once you build your application against this library, you can deploy the application on a cluster running Databricks Runtime 4.0 or above.

重要

dbutils-api ライブラリを使用すると、dbutilsを使用するアプリケーションをローカルでコンパイルできますが、実行することはできません。The dbutils-api library allows you to locally compile an application that uses dbutils, but not to run it. アプリケーションを実行するには、アプリケーションを Azure Databricks に展開する必要があります。To run the application, you must deploy it in Azure Databricks.

サンプルプロジェクトExample projects

次に示すのは、3つの共通ビルドツールの dbutils-api ライブラリを使用してコンパイルする方法を示す、最小限のサンプルプロジェクトを含むアーカイブの例です。Here is an example archive containing minimal example projects that show you how to compile using the dbutils-api library for 3 common build tools:

  • sbt: sbt packagesbt: sbt package
  • Maven: mvn installMaven: mvn install
  • Gradle: gradle buildGradle: gradle build

これらのコマンドは、次の場所に出力 Jar を作成します。These commands create output JARs in the locations:

  • sbt: target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jarsbt: target/scala-2.11/dbutils-api-example_2.11-0.0.1-SNAPSHOT.jar
  • Maven: target/dbutils-api-example-0.0.1-SNAPSHOT.jarMaven: target/dbutils-api-example-0.0.1-SNAPSHOT.jar
  • Gradle: build/libs/dbutils-api-example-0.0.1-SNAPSHOT.jarGradle: build/libs/dbutils-api-example-0.0.1-SNAPSHOT.jar

この JAR をライブラリとしてクラスターにアタッチし、クラスターを再起動して (Databricks Runtime 4.0 を使用して行う必要があります)、次のように実行できます。You can attach this JAR to your cluster as a library, restart the cluster, (which you must do using Databricks Runtime 4.0), and then run:

example.Test()

このステートメントでは、 Hello: というラベルと初期値の_ワールド_を含むテキスト入力ウィジェットが作成されます。This statement creates a text input widget with the label Hello: and the initial value World.

他のすべての dbutils Api も同じ方法で使用できます。You can use all the other dbutils APIs the same way.

Databricks の外部で dbutils オブジェクトを使用するアプリケーションをテストするには、次のようにを呼び出して、dbutils オブジェクトをモックアップします。To test an application that uses the dbutils object outside Databricks, you can mock up the dbutils object by calling:

com.databricks.dbutils_v1.DBUtilsHolder.dbutils0.set(
  new com.databricks.dbutils_v1.DBUtilsV1{
    ...
  }
)

インターフェイスメソッドを実装する独自の DBUtilsV1 インスタンスを使用します。たとえば、dbutils.fs のローカルファイルシステムモックアップを提供します。Substitute your own DBUtilsV1 instance in which you implement the interface methods however you like, for example providing a local filesystem mockup for dbutils.fs.