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 はノートブックの外部ではサポートされていません。DBUtils are not supported outside of notebooks.

すべて dbutils のユーティリティは、Python、R、および拡張性のあるノートブックで利用できます。All dbutils utilities are available in Python, R, and Scala notebooks.

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

ファイルシステムユーティリティは、 Databricks File system (DBFS)にアクセスして、ファイルシステムとして Azure Databricks を簡単に使用できるようにします。The file system utilities access Databricks File System (DBFS), 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:

属性Attribute TypeType [説明]Description
pathpath stringstring ファイルまたはディレクトリのパス。The path of the file or directory.
namename 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")

例:For example:

PythonPython

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

RR

dbutils.fs.ls("/databricks-datasets/")
dbutils.fs.head("/databricks-datasets/Rdatasets/data-001/datasets.csv")

ScalaScala

dbutils.fs.ls("/databricks-datasets/adult")
dbutils.fs.head("/databricks-datasets/adult/adult.data")

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 Secret management and Use the secrets in a notebook. 詳細については、次を実行してください。Learn more by running:

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 でライブラリ API コマンドを再実行することによって、再作成することができ install ます。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 ML または Databricks Runtime for Genomics では使用できません。Library utilities are not available on Databricks Runtime ML or Databricks Runtime for Genomics. 代わりに、 ノートブックスコープの Python ライブラリを参照してください。Instead, refer to Notebook-scoped Python libraries.

Databricks Runtime 7.2 以降では、Databricks はマジックコマンドを使用して notebook スコープのライブラリをインストールすることを推奨して %pip います。For Databricks Runtime 7.2 and above, Databricks recommends using %pip magic commands to install notebook-scoped libraries. ノートブック スコープの Python ライブラリ」を参照してください。See Notebook-scoped Python libraries.

ライブラリユーティリティは、既定で有効になっています。Library utilities are enabled by default. したがって、既定では、各ノートブックの 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.enabled をに設定し false ます。You can disable this feature by setting spark.databricks.libraryIsolation.enabled to false.

この API は、 UIREST APIを通じて、既存のクラスター全体のライブラリのインストールと互換性があります。This API is compatible with the existing cluster-wide library installation through the UI and REST API. この API によってインストールされるライブラリは、クラスター全体のライブラリよりも優先度が 高く なります。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.19.0") が有効ではありません。For example: dbutils.library.installPyPI("azureml-sdk[databricks]==1.19.0") is not valid. 次のよう version に、引数と引数を使用し extras て、バージョンと詳細情報を指定します。Use the version and extras arguments to specify the version and extras information as follows:

    dbutils.library.installPyPI("azureml-sdk", version="1.19.0", extras="databricks")
    dbutils.library.restartPython()  # Removes Python state, but some libraries might not work without calling this function
    

    注意

    コマンド dbutils.library.installPyPI をコマンドで置き換えると %pip 、Python インタープリターが自動的に再起動されます。When replacing dbutils.library.installPyPI commands with %pip commands, the Python interpreter is automatically restarted. 次のようにインストールコマンドを実行できます。You can run the install command as follows:

    %pip install azureml-sdk[databricks]==1.19.0
    
  • 1つのノートブックでライブラリの要件を指定し、 %run 別の notebook にインストールします。Specify your library requirements in one notebook and install them through %run in the other.

    • という notebook にインストールするライブラリを定義 InstallDependencies します。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()
    

    注意

    を使用したこのコマンドに相当するもの %pip は次のとおりです。The equivalent of this command using %pip is:

    %pip freeze
    
  • 環境を維持しながら、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 ライブラリをノートブックにインストールします。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. Python notebook の状態は、実行後にリセットされ restartPython ます。ノートブックは、ローカル変数、インポートされたライブラリ、およびその他の一時的な状態を含めて、すべての状態を失います。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.

    受け入れられるライブラリソースは、、、 dbfs abfss adl 、および 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
    

    注意

    カスタムホイールファイルは、を使用して直接インストールでき %pip ます。You can directly install custom wheel files using %pip. 次の例では、DBFS にライブラリホイールファイルがアップロードされていることを前提としています。In the following example we are assuming you have uploaded your library wheel file to DBFS:

    %pip install /dbfs/path/to/your/library.whl
    

    卵ファイルは pip ではサポートされていません。また、ホイールは Python 用のビルドおよびバイナリパッケージの標準と見なされます。Egg files are not supported by pip, and wheel is considered the standard for build and binary packaging for Python. 詳細については、「 ホイールと卵 」を参照してください。See Wheel vs Egg for more details. ただし、と互換性のある方法で卵ファイルを使用する場合は、 %pip 次の回避策を使用できます。However, if you want to use an egg file in a way that’s compatible with %pip, you can use the following workaround:

    # This step is only needed if no %pip commands have been executed yet.
    # It will trigger setting up the isolated notebook environment
    %pip install <any-lib>  # This doesn't need to be a real lib, eg - "%pip install foo" would work
    
    import sys
    # Assuming the preceding step was completed, the following command
    # adds the egg file to the current notebook environment
    sys.path.append("/local/path/to/library.egg")
    

DBUtils notebookDBUtils notebook

ノートブックを入手Get notebook

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

注意

Databricks Runtime 7.0 以降を実行しているクラスターにデプロイする場合は、このライブラリを使用して配置前テストを実行することはできません。これは、2.12 をサポートするライブラリのバージョンがないためです。You cannot use this library to run pre-deployment tests if you are deploying to a cluster running Databricks Runtime 7.0 or above, because there is no version of the library that supports Scala 2.12.

アプリケーションの開発を加速させるために、アプリケーションを運用ジョブとしてデプロイする前に、アプリケーションのコンパイル、ビルド、テストを行うと便利です。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.4"
    
  • MavenMaven

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

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

このライブラリに対してアプリケーションをビルドしたら、アプリケーションをデプロイできます。Once you build your application against this library, you can deploy the application.

重要

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.

成果物のスケールを表現する %%Express the artifact’s Scala version with %%

の代わりに成果物のバージョンを表現した場合 groupID %% artifactID % revision groupID % artifactID % revision (相違点が %% の後の double groupID )、sbt はプロジェクトのバージョンを成果物の名前に追加します。If you express the artifact version as groupID %% artifactID % revision instead of groupID % artifactID % revision (the difference is the double %% after the groupID), SBT will add your project’s Scala version to the artifact name.

Example

ビルドのがであるとし scalaVersion 2.9.1 ます。Suppose the scalaVersion for your build is 2.9.1. 次のように、を使用して成果物のバージョンを記述でき % ます。You could write the artifact version with % as follows:

val appDependencies = Seq(
  "org.scala-tools" % "scala-stm_2.9.1" % "0.3"
)

次の using %% は同じです。The following using %% is identical:

val appDependencies = Seq(
  "org.scala-tools" %% "scala-stm" % "0.3"
)

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

次に示すのは、 dbutils-api 3 つの共通ビルドツールのライブラリを使用してコンパイルする方法を示す最小限のサンプルプロジェクトを含むアーカイブの例です。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/examples/dbutils-api-example-0.0.1-SNAPSHOT.jarGradle: build/examples/dbutils-api-example-0.0.1-SNAPSHOT.jar

この JAR をライブラリとしてクラスターにアタッチし、クラスターを再起動して、次のように実行できます。You can attach this JAR to your cluster as a library, restart the cluster, and then run:

example.Test()

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

他のすべての api を dbutils 同じ方法で使用できます。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.