Поделиться через

Справочник по служебным программам Databricks (dbutils)

  • Статья

Эта статья является справочником по служебным программам Databricks (dbutils). Служебные программы dbutils доступны в записных книжках Python, R и Scala. Служебные программы можно использовать для:

  • Эффективная работа с файлами и хранилищем объектов.
  • Работа с секретами.

Руководство: служебные программы List, команды list, отображение справки по команде

Служебные программы: данные, файловая система, задания, библиотека, записная книжка, секреты, мини-приложения, библиотека API служебных программ

Список доступных служебных программ

Чтобы получить список доступных служебных программ вместе с кратким описанием каждой программы, выполните команду dbutils.help() для Python или Scala.

В этом примере перечислены доступные команды для служебных программ Databricks.

Python

dbutils.help()

Scala

dbutils.help()

This module provides various utilities for users to interact with the rest of Databricks.

credentials: DatabricksCredentialUtils -> Utilities for interacting with credentials within notebooks
data: DataUtils -> Utilities for understanding and interacting with datasets (EXPERIMENTAL)
fs: DbfsUtils -> Manipulates the Databricks filesystem (DBFS) from the console
jobs: JobsUtils -> Utilities for leveraging jobs features
library: LibraryUtils -> Utilities for session isolated libraries
meta: MetaUtils -> Methods to hook into the compiler (EXPERIMENTAL)
notebook: NotebookUtils -> Utilities for the control flow of a notebook (EXPERIMENTAL)
preview: Preview -> Utilities under preview category
secrets: SecretUtils -> Provides utilities for leveraging secrets within notebooks
widgets: WidgetsUtils -> Methods to create and get bound value of input widgets inside notebooks

Список доступных команд для служебной программы

Чтобы получить список доступных команд для служебной программы вместе с кратким описанием каждой команды, запустите .help() после программного имени служебной программы.

В этом примере перечислены доступные команды для служебной программы Databricks File System (DBFS).

Python

dbutils.fs.help()

R

dbutils.fs.help()

Scala

dbutils.fs.help()

dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".

fsutils

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

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
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one

Отображение справки по команде

Чтобы отобразить справку по команде, выполните .help("<command-name>") после имени команды.

В этом примере отображается справка для команды DBFS Copy.

Python

dbutils.fs.help("cp")

R

dbutils.fs.help("cp")

Scala

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.data)

Внимание

Эта функция предоставляется в режиме общедоступной предварительной версии.

Примечание.

Доступно в Databricks Runtime 9.0 и более поздних версиях.

Команды: сводные данные

Служебная программа по работе с данными позволяет анализировать и интерпретировать наборы данных. Чтобы получить список доступных команд, выполните dbutils.data.help().

dbutils.data provides utilities for understanding and interpreting datasets. This module is currently in preview and may be unstable. For more info about a method, use dbutils.data.help("methodName").

summarize(df: Object, precise: boolean): void -> Summarize a Spark DataFrame and visualize the statistics to get quick insights

Команда получения сводных данных (dbutils.data.summarize)

Вычисляет и отображает статистику по сводным данным Apache Spark DataFrame или Pandas DataFrame. Эта команда доступна для Python, Scala и R.

Эта команда анализирует полное содержимое кадра данных. Выполнение этой команды для очень больших кадров данных может быть очень дорогостоящим.

Чтобы отобразить справку для этой команды, выполните 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)

Scala

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 (giga) вместо "G".

Служебная программа файловой системы (dbutils.fs)

Предупреждение

Реализация Python всех dbutils.fs методов используется snake_case вместо camelCase форматирования ключевых слов.

Например: при отображении dbutils.fs.help() параметра extraConfigs в dbutils.fs.mount()Python используется ключевое слово extra_configs.

Команды: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount

Служебная программа файловой системы позволяет получить доступ к DBFS?, что упрощает использование Azure Databricks в качестве файловой системы.

В записных книжках можно также использовать магическую %fs команду для доступа к DBFS. %fs ls /Volumes/main/default/my-volume/ Например, то же самое, что dbutils.fs.ls("/Volumes/main/default/my-volume/")и . См . волшебные команды.

Чтобы получить список доступных команд, выполните dbutils.fs.help().

dbutils.fs provides utilities for working with FileSystems. Most methods in this package can take either a DBFS path (e.g., "/foo" or "dbfs:/foo"), or another FileSystem URI. For more info about a method, use dbutils.fs.help("methodName"). In notebooks, you can also use the %fs shorthand to access DBFS. The %fs shorthand maps straightforwardly onto dbutils calls. For example, "%fs head --maxBytes=10000 /file/path" translates into "dbutils.fs.head("/file/path", maxBytes = 10000)".

fsutils

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

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
updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean -> Similar to mount(), but updates an existing mount point instead of creating a new one

Команда cp (dbutils.fs.cp)

Копирует файла или каталог, возможно, между файловыми системами.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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)

Возвращает указанное максимальное число байт заданного файла. Байты возвращаются в виде строки символов в кодировке UTF-8.

Чтобы отобразить справку для этой команды, выполните dbutils.fs.help("head").

В этом примере отображаются первые 25 байт файла data.csv, расположенного в /Volumes/main/default/my-volume/.

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"

Scala

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)

Вывод в виде списка содержимого каталога.

Чтобы отобразить справку для этой команды, выполните 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"

Scala

dbutils.fs.ls("/tmp")

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

Команда mkdir (dbutils.fs.mkdirs)

Создает данный каталог, если он не существует. Также создает все необходимые родительские каталоги.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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

// res7: Boolean = true

Команда mount (dbutils.fs.mount)

Подключает указанный исходный каталог 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>")})

Scala

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 2-го поколения и хранилищу BLOB-объектов".

Команда mounts (dbutils.fs.mounts)

Отображает сведения о том, что в настоящее время подключено в DBFS.

Чтобы отобразить справку для этой команды, выполните dbutils.fs.help("mounts").

Предупреждение

Вызовите dbutils.fs.refreshMounts() все остальные запущенные кластеры для распространения нового подключения. См. команду refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Дополнительные примеры кода см. в разделе "Подключение к Azure Data Lake Storage 2-го поколения и хранилищу BLOB-объектов".

Команда mv (dbutils.fs.mv)

Перемещает файл или каталог, возможно, между файловыми системами. Перемещение — это копирование, за которым следует удаление, даже при перемещении внутри файловой системы.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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

// res1: Boolean = true

Команда put (dbutils.fs.put)

Записывает указанную строку в файл. Строка содержит символы в кодировке 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

Scala

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

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

Команда refreshMounts (dbutils.fs.refreshMounts)

Заставляет все компьютеры в кластере обновить свой кэш подключения, гарантируя, что они получат самую последнюю информацию.

Чтобы отобразить справку для этой команды, выполните dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Примеры кода надстройки см. в разделе "Подключение к Azure Data Lake Storage 2-го поколения и хранилищу BLOB-объектов".

Команда rm (dbutils.fs.rm)

Удаляет файл или каталог и при необходимости все его содержимое. Если указан файл, параметр рекурсии игнорируется. Если указан каталог, ошибка возникает при отключении рекурсии, а каталог не пуст.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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

// res6: Boolean = true

Команда unmount (dbutils.fs.unmount)

Удаляет точку подключения DBFS.

Предупреждение

Чтобы избежать ошибок, никогда не изменяйте точку подключения во время чтения или записи в нее других заданий. После изменения подключения всегда запустите dbutils.fs.refreshMounts() все остальные запущенные кластеры для распространения обновлений подключения. См. команду refreshMounts (dbutils.fs.refreshMounts).

Чтобы отобразить справку для этой команды, выполните dbutils.fs.help("unmount").

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

Дополнительные примеры кода см. в разделе "Подключение к Azure Data Lake Storage 2-го поколения и хранилищу BLOB-объектов".

Команда updateMount (dbutils.fs.updateMount)

Аналогично команде dbutils.fs.mount, но обновляет существующую точку подключения вместо создания новой. Возвращает ошибку, если точка подключения отсутствует.

Чтобы отобразить справку для этой команды, выполните dbutils.fs.help("updateMount").

Предупреждение

Чтобы избежать ошибок, никогда не изменяйте точку подключения во время чтения или записи в нее других заданий. После изменения подключения всегда запустите dbutils.fs.refreshMounts() все остальные запущенные кластеры для распространения обновлений подключения. См. команду refreshMounts (dbutils.fs.refreshMounts).

Эта команда доступна в Databricks Runtime 10.4 LTS и выше.

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

Scala

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

Служебная программа для заданий (dbutils.jobs)

Служебные подпрограммы: taskValues

Примечание.

Эта служебная программа доступна только для Python.

Служебная программа для заданий позволяет использовать возможности заданий. Чтобы отобразить справку для этой служебной программы, выполните dbutils.jobs.help().

Provides utilities for leveraging jobs features.

taskValues: TaskValuesUtils -> Provides utilities for leveraging job task values

Служебная подпрограмма taskValues (dbutils.jobs.taskValues)

Команды: get, set

Примечание.

Эта служебная подпрограмма доступна только для Python.

Предоставляет команды для использования значений задач в задании.

Используйте эту служебную подпрограмму, чтобы задать и получить произвольные значения во время выполнения задания. Эти значения называются значениями задач. Вы можете получить доступ к значениям в подчиненных задачах одного и того же выполняемого задания. Например, вы можете передавать идентификаторы или метрики, включая сведения об оценке модели машинного обучения, между разными задачами в выполняемом задании. В каждой задаче можно задать и (или) получить несколько значений задач. У каждого значения есть ключ, уникальный в пределах задачи. Этот уникальный ключ называется ключом значения задачи. Для получения доступа к значению задачи используется имя задачи и ключ ее значения.

Чтобы отобразить справку для этой служебной подпрограммы, выполните dbutils.jobs.taskValues.help().

Команда get (dbutils.jobs.taskValues.get)

Примечание.

Эта команда доступна только для Python.

До версии Databricks Runtime 10.4, если get не может найти задачу, возникает ошибка Py4JJavaError, а не ValueError.

Возвращает содержимое указанного значения для указанной задачи в текущем выполнении задания.

Чтобы отобразить справку для этой команды, выполните 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, вместо ошибки TypeError возвращается значение debugValue.

Команда set (dbutils.jobs.taskValues.set)

Примечание.

Эта команда доступна только для Python.

Задает или обновляет значение задачи. Для выполнения задания вы можете задать до 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 — это ключ значения задачи. Этот ключ должен быть уникальным для задачи. То есть, если две разные задачи задают значение задачи с ключом K, это два разных значения задач, которые имеют один и тот же ключ K.
  • value — значение для этого ключа значения задачи. Эта команда должна иметь возможность представлять значение внутри в формате JSON. Размер представления JSON не может превышать 48 КиБ.

При попытке задать значение задачи из записной книжки, выполняющейся за пределами задания, команда ничего не выполнит.

Служебная программа Library (dbutils.library)

Большинство методов в подмодуле dbutils.library устарели. См. служебную программу библиотеки (dbutils.library) (устаревшую версию).

Возможно, потребуется программно перезапустить процесс Python в Azure Databricks, чтобы обеспечить правильную работу локально установленных или обновленных библиотек в ядре Python для текущего SparkSession. Для этого выполните следующую командуdbutils.library.restartPython. См . статью "Перезапуск процесса Python" в Azure Databricks.

Служебная программа notebook (dbutils.notebook)

Команды: exit, run

Служебная программа notebook позволяет объединять записные книжки в цепочки и оказывать влияние на их результаты. См. статью "Запуск записной книжки Databricks" из другой записной книжки.

Чтобы получить список доступных команд, выполните 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.

Команда exit (dbutils.notebook.exit)

Выход из записной книжки со значением.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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, равна 5 МБ. См. раздел Получение выходных данных для одного выполнения (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'

Scala

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

// res2: String = Exiting from My Other Notebook

Служебная программа Secrets (dbutils.secrets)

Команды: get, getBytes, list, listScopes

Служебная программа secrets позволяет хранить конфиденциальные учетные данные и получать к ним доступ, не делая их видимыми в записных книжках. См. раздел Управление секретами и Использование секретов в записной книжке. Чтобы получить список доступных команд, выполните 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

Команда get (dbutils.secrets.get)

Возвращает строковое представление значения секрета для указанной области действия секретов и ключа.

Предупреждение

Администраторы, создатели секретов и пользователи с соответствующим разрешением, могут читать секреты 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]"

Scala

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

// res0: String = [REDACTED]

Команда getBytes (dbutils.secrets.getBytes)

Возвращает строковое представление значения секрета для указанной области действия и ключа.

Чтобы отобразить справку для этой команды, выполните 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

Scala

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)

Перечисляет метаданные для секретов в указанной области действия.

Чтобы отобразить справку для этой команды, выполните 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"

Scala

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

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

Команда listScopes (dbutils.secrets.listScopes)

Выводит список доступных областей действия.

Чтобы отобразить справку для этой команды, выполните dbutils.secrets.help("listScopes").

В этом примере перечислены доступные области действия.

Python

dbutils.secrets.listScopes()

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

R

dbutils.secrets.listScopes()

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

Scala

dbutils.secrets.listScopes()

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

Служебная программа Widgets (dbutils.widgets)

Команды: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text

Служебная программа Widgets позволяет параметризовать записные книжки. См. статью Мини-приложения.

Чтобы получить список доступных команд, выполните 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
getAll: map -> Retrieves a map of all widget names and their values
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

Команда combobox (dbutils.widgets.combobox)

Создает и отображает мини-приложение ComboBox с указанным программным именем, значением по умолчанию, вариантами выбора и необязательной меткой.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("combobox").

В этом примере создается и отображается мини-приложение ComboBox с программным именем fruits_combobox. Оно предлагает варианты выбора apple, banana, coconut и dragon fruit и устанавливает начальное значение banana. Это мини-приложение ComboBox имеет сопроводительную метку Fruits. Данный пример завершается печатью начального значения мини-приложения ComboBox banana.

Python

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

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

# banana

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"

Scala

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 с указанным программным именем, значением по умолчанию, вариантами выбора и необязательной меткой.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("dropdown").

В этом примере создается и отображается мини-приложение Dropdown с программным именем toys_dropdown. Оно предлагает варианты выбора alphabet blocks, basketball, cape и doll и устанавливает начальное значение basketball. Это мини-приложение Dropdown имеет сопроводительную метку Toys. Данный пример завершается печатью начального значения мини-приложения Dropdown basketball.

Python

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

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

# basketball

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"

Scala

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)

Возвращает текущее значение мини-приложения с указанным программным именем. Это программное имя может быть одним из следующих:

  • Имя пользовательского мини-приложения в записной книжке, например fruits_combobox или toys_dropdown.
  • Имя настраиваемого параметра, передаваемого записной книжке в составе задачи записной книжки, например name или age. Дополнительные сведения см. в разделе о охвате параметров для задач записной книжки в пользовательском интерфейсе заданий или notebook_params поле в операции запуска нового задания (POST /jobs/run-now) в API заданий.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("get").

В этом примере возвращается значение мини-приложения с программным именем fruits_combobox.

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala

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"

Scala

dbutils.widgets.get("age")

// res6: String = 35

SQL

SELECT :age

-- 35

команда getAll (dbutils.widgets.getAll)

Возвращает сопоставление всех текущих имен и значений мини-приложений. Это может быть особенно полезно для быстрого передачи значений мини-приложений 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

Scala

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

// res6: Query output

Команда getArgument (dbutils.widgets.getArgument)

Возвращает текущее значение мини-приложения с указанным программным именем. Если мини-приложение не существует, может быть возвращено необязательное сообщение.

Примечание.

Эта команда отключена. Используйте вместо него 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"

Scala

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 с указанным программным именем, значением по умолчанию, вариантами выбора и необязательной меткой.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("multiselect").

В этом примере создается и отображается мини-приложение Multiselect с программным именем days_multiselect. Оно предлагает варианты выбора с Monday по Sunday и устанавливает начальное значение Tuesday. Это мини-приложение Multiselect имеет сопроводительную метку Days of the Week. Данный пример завершается печатью начального значения мини-приложения Multiselect 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"

Scala

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)

Удаляет мини-приложение с указанным программным именем.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("remove").

Внимание

При добавлении команды для удаления мини-приложения невозможно добавить последующую команду для создания мини-приложения в той же ячейке. Мини-приложение необходимо создать в другой ячейке.

В этом примере удаляется мини-приложение с программным именем fruits_combobox.

Python

dbutils.widgets.remove('fruits_combobox')

R

dbutils.widgets.remove('fruits_combobox')

Scala

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

Команда removeAll (dbutils.widgets.removeAll)

Удаляет все мини-приложения из записной книжки.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("removeAll").

Внимание

При добавлении команды для удаления всех мини-приложений невозможно добавить последующую команду для создания мини-приложения в той же ячейке. Мини-приложения необходимо создать в другой ячейке.

В этом примере удаляются все мини-приложения из записной книжки.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

Команда text (dbutils.widgets.text)

Создает и отображает мини-приложение Text с указанным программным именем, значением по умолчанию, вариантами выбора и необязательной меткой.

Чтобы отобразить справку для этой команды, выполните dbutils.widgets.help("text").

В этом примере создается и отображается мини-приложение Text с программным именем your_name_text. Ему присваивается начальное значение Enter your name. Мини-приложение Text имеет сопроводительную метку Your name. Данный пример завершается печатью начального значения мини-приложения Text 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"

Scala

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

Библиотека API служебных программ Databricks

Внимание

Библиотека API служебных программ Databricks (dbutils-api) устарела. Хотя эта библиотека по-прежнему доступна, Databricks не планирует новую функцию для библиотеки dbutils-api .

Databricks рекомендует использовать одну из следующих библиотек:

Для ускорения разработки приложений может быть полезно компилировать, собирать и тестировать приложения перед их развертыванием в качестве рабочих заданий. Чтобы обеспечить компиляцию с помощью служебных программ Databricks, Databricks предоставляют библиотеку dbutils-api. Вы можете скачать библиотеку dbutils-api с веб-страницы DBUtils API на сайте репозитория Maven или подключить библиотеку, добавив зависимость в файл сборки:

  • 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). Список доступных целевых объектов и версий см. на веб-странице DBUtils API на сайте репозитория Maven.

После сборки приложения для этой библиотеки можно развернуть приложение.

Внимание

Библиотека dbutils-api позволяет локально компилировать приложение, которое использует dbutils, но не запускает его. Чтобы запустить приложение, необходимо развернуть его в Azure Databricks.

Ограничения

Вызов dbutils внутри исполнителей может привести к непредвиденным результатам или к ошибкам.

Если необходимо выполнять операции файловой системы в исполнителях с помощью dbutils, можно использовать несколько более быстрых и масштабируемых альтернативных вариантов:

Сведения о исполнителях см. в разделе Обзор режима кластера на веб-сайте Apache Spark.