Справочник по служебным программам Databricks (dbutils)
Эта статья является справочником по служебным программам Databricks (dbutils). Служебные программы dbutils доступны в записных книжках Python, R и Scala. Служебные программы можно использовать для:
- Эффективная работа с файлами и хранилищем объектов.
- Работа с секретами.
Примечание.
dbutils поддерживает только вычислительные среды, использующие DBFS.
Руководство: служебные программы 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/ — это тоже самое, что и duties.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)
Удаляет файл или каталог и, при необходимости, все его содержимое. Если указан файл, 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
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)
Примечание.
Эта служебная подпрограмма доступна только для 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)
Служебная программа 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 позволяет хранить конфиденциальные учетные данные и получать к ним доступ, не делая их видимыми в записных книжках. См . раздел "Управление секретами" и шаг 3. Использование секретов в записной книжке. Чтобы получить список доступных команд, выполните 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обратитесь к параллельным методам перечисления и удаления с помощью Spark в том, как быстрее перечислять и удалять файлы в Databricks.
Сведения о исполнителях см. в разделе Обзор режима кластера на веб-сайте Apache Spark.