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

Статья
01/02/2025

В этой статье содержится справочник по служебным программам Databricks (dbutils). Служебные программы предоставляют команды, позволяющие работать с средой Databricks из записных книжек. Например, можно управлять файлами и хранилищем объектов и работать с секретами. dbutils доступны в записных книжках Python, R и Scala.

Примечание.

dbutils поддерживает только вычислительные среды, использующие DBFS.

Вспомогательные модули

В следующем table указаны модули Databricks Utilities, которые можно получить с помощью dbutils.help().

Модуль	Описание
данных	Инструменты для анализа и взаимодействия с наборами данных (ЭКСПЕРИМЕНТАЛЬНО)
fs	Служебные программы для доступа к файловой системе Databricks (DBFS)
задания	Служебные программы для использования возможностей рабочих задач
библиотека	Устарело. Утилиты для управления библиотеками с сеансовой областью видимости
записная книжка	Утилиты для управления последовательностью выполнения в интерфейсе ноутбука (ЭКСПЕРИМЕНТАЛЬНО)
секреты	Служебные программы для использования секретов в записных книжках
мини-приложения	Служебные программы для параметризации записных книжек.
API (интерфейс программирования приложений)	Служебные программы для управления сборками приложений

Справка по команде

Для того чтобы list выполнить команды для модуля служебных функций, а также краткое описание каждой команды, добавьте .help() после имени модуля служебных функций. В следующем примере перечислены доступные команды для служебной программы записной книжки:

dbutils.notebook.help()

The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value

Чтобы вывести справку по команде, выполните dbutils.<utility-name>.help("<command-name>"). В следующем примере показана справка по команде копирования служебных программ файловой системы, dbutils.fs.cp:

dbutils.fs.help("cp")

/**
* Copies a file or directory, possibly across FileSystems.
*
* Example: cp("/mnt/my-folder/a", "dbfs:/a/b")
*
* @param from FileSystem URI of the source file or directory
* @param to FileSystem URI of the destination file or directory
* @param recurse if true, all files and directories will be recursively copied
* @return true if all files were successfully copied
*/
cp(from: java.lang.String, to: java.lang.String, recurse: boolean = false): boolean

Служебная работа для работы с данными (dbutils.data)

Внимание

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

Примечание.

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

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

В следующем table перечислены доступные команды для этой служебной программы, которые можно получить с помощью dbutils.data.help().

Команда	Описание
резюмировать	Суммируйте Spark DataFrame и визуализируйте статистику для get быстрых выводов

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

Примечание.

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

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

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

Внимание

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

Чтобы отобразить полную справку по этой команде, выполните следующую операцию:

dbutils.data.help("summarize")

В Databricks Runtime 10.4 LTS и более поздних версиях можно использовать дополнительный precise параметр для настройки точности вычисляемой статистики.

Если precise установлено в set false (по умолчанию), некоторые возвращаемые статистические данные содержат приближенные оценки для уменьшения времени выполнения.
- Число уникальных values для категориальных columns может иметь ~5% относительную ошибку для высокой кардинальности columns.
- Частые числа значений могут иметь погрешность до 0,01%, если число различных values превышает 10000.
- Гистограммы и процентные оценки могут иметь ошибку до 0,01% относительно общего числа строк.
Когда precise устанавливается в set true, статистика вычисляется с более высокой точностью. Все статистические данные, кроме гистограмм и процентилей для числовых columns, теперь точные.
- Гистограммы и процентные оценки могут иметь ошибку до 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 для краткой отрисовки числовых values меньше 0,01 или больше 10000. Например, числовое значение 1.25e-15 будет отображаться как 1.25f. Одно исключение: визуализация использует "B" для 1.0e9 (giga) вместо "G".

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

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

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

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

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

В следующем table перечислены доступные команды для этой служебной программы, которые можно получить с помощью dbutils.fs.help().

Приказ	Описание
cp	Копирует файл или каталог, возможно даже между различными файловыми системами.
головы	Возвращает до первых байтов maxBytes заданного файла в виде строки, закодированной в UTF-8.
ls	Список содержимого каталога
mkdirs	Создает указанный каталог, если он не существует, а также создает все необходимые родительские каталоги.
подключение	Подключает указанный исходный каталог к DBFS в заданной точке подключения.
крепления	Отображает сведения о том, что подключено в DBFS
mv	Перемещает файл или каталог, возможно, между различными файловыми системами.
положить	Записывает указанную строку в файл, закодированный в UTF-8
обновить крепления	Принудительно refresh кэш подключения всех компьютеров в этом кластере, обеспечивая получение последних сведений
rm	Удаляет файл или каталог
размонтировать	Удаляет точку подключения DBFS
updateMount	Аналогично mount(), но обновляет существующую точку подключения вместо создания новой.

Совет

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

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

cp(from: String, to: String, recurse: boolean = false): boolean

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("cp")

Пример

В этом примере файл с именем data.csv в /Volumes/main/default/my-volume/new-data.csv том же томе копируется.

Python

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

# Out[4]: True

R

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

# [1] TRUE

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)

head(file: String, maxBytes: int = 65536): String

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

ls(dir: String): Seq

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.fs.help("ls")

Пример

В этом примере отображаются сведения о содержимом /Volumes/main/default/my-volume/. Поле modificationTime доступно в Databricks Runtime 10.4 LTS и выше. В языке R modificationTime возвращается в виде строки.

Python

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

# Out[13]: [FileInfo(path='dbfs:/Volumes/main/default/my-volume/data.csv', name='data.csv', size=2258987, modificationTime=1711357839000)]

R

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

# For prettier results from dbutils.fs.ls(<dir>), please use `%fs ls <dir>`

# [[1]]
# [[1]]$path
# [1] "/Volumes/main/default/my-volume/data.csv"

# [[1]]$name
# [1] "data.csv"

# [[1]]$size
# [1] 2258987

# [[1]]$isDir
# [1] FALSE

# [[1]]$isFile
# [1] TRUE

# [[1]]$modificationTime
# [1] "1711357839000"

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)

mkdirs(dir: String): boolean

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("mkdirs")

Пример

В этом примере создается каталог my-data внутри /Volumes/main/default/my-volume/.

Python

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

# Out[15]: True

R

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

# [1] TRUE

Scala

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

// res7: Boolean = true

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

mount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

Подключает указанный исходный каталог DBFS к указанной точке подключения.

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("mount")

Пример

Python

dbutils.fs.mount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})

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)

mounts: Seq

Отображает сведения о том, что в настоящее время подключено в 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)

mv(from: String, to: String, recurse: boolean = false): boolean

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("mv")

Пример

В данном примере перемещается файл с именем rows.csv из /Volumes/main/default/my-volume/ в /Volumes/main/default/my-volume/my-data/.

Python

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

# Out[2]: True

R

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

# [1] TRUE

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)

put(file: String, contents: String, overwrite: boolean = false): boolean

Записывает указанную строку в файл. Строка содержит символы в кодировке UTF-8.

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.fs.help("put")

Пример

В этом примере строка Hello, Databricks! записывается в файл с именем hello.txt в папку /Volumes/main/default/my-volume/. Если файл уже существует, он будет перезаписан.

Python

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

# Wrote 2258987 bytes.
# Out[6]: True

R

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

# [1] TRUE

Scala

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

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

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

refreshMounts: boolean

Принудительно refresh кэш подключения всех компьютеров в кластере, обеспечивая получение последних сведений.

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("refreshMounts")

Пример

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

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

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

rm(dir: String, recurse: boolean = false): boolean

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("rm")

Пример

В этом примере удаляется весь каталог /Volumes/main/default/my-volume/my-data/ , включая его содержимое.

Python

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

# Out[8]: True

R

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

# [1] TRUE

Scala

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

// res6: Boolean = true

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

unmount(mountPoint: String): boolean

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

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

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.fs.help("unmount")

Пример

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

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

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

updateMount(source: String, mountPoint: String, encryptionType: String = "", owner: String = null, extraConfigs: Map = Map.empty[String, String]): boolean

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

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

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.fs.help("updateMount")

Пример

Python

dbutils.fs.updateMount(
  source = "wasbs://<container-name>@<storage-account-name>.blob.core.windows.net",
  mount_point = "/mnt/<mount-name>",
  extra_configs = {"<conf-key>":dbutils.secrets.get(scope = "<scope-name>", key = "<key-name>")})

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)

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

Примечание.

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

В следующем table перечислены доступные модули для этой служебной программы, которые можно получить с помощью dbutils.jobs.help().

Подмодул	Описание
taskValues	Предоставляет служебные программы для использования задачи задания values

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

Примечание.

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

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

Используйте эту вспомогательную утилиту для set и get произвольных values во время выполнения задания. Эти values называются задачами values. Любая задача может getvaluesset выполняться вышестоящими задачами и setvalues для использования последующими задачами.

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

В следующих table перечислены доступные команды для этой подзаготовки, которые можно получить с помощью dbutils.jobs.taskValues.help().

Приказ	Описание
get	Возвращает содержимое указанного значения для указанной задачи в текущем выполнении задания.
set	Задает или обновляет значение задачи. Для выполнения задания set можно выполнить до 250 задач values.

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

Примечание.

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

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

get(taskKey: String, key: String, default: int, debugValue: int): Seq

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.jobs.taskValues.help("get")

Пример

Например:

dbutils.jobs.taskValues.get(taskKey    = "my-task", \
                            key        = "my-key", \
                            default    = 7, \
                            debugValue = 42)

В предыдущем примере:

taskKey — имя задачи, задающей значение задачи. Если команда не может найти эту задачу, возникает ошибка ValueError.
key — это имя ключа значения задачи, set с помощью команды set (dbutils.jobs.taskValues.set). Если команда не может найти этот ключ значения задачи, появляется ошибка ValueError (если не указано default).
default — необязательное значение, которое возвращается, если key не удается найти. default не может иметь значение None.
debugValue является необязательным значением, которое возвращается, если вы пытаетесь get значение задачи из записной книжки, выполняемой вне задания. Это может быть полезно во время отладки, если нужно запустить записную книжку вручную и вернуть какое-либо значение вместо появления TypeError по умолчанию. debugValue не может иметь значение None.

Если вы пытаетесь get значение переменной задачи из ноутбука, выполняемого вне контекста задания, эта команда вызывает по умолчанию TypeError. Однако если в команде указан аргумент debugValue, вместо ошибки debugValue возвращается значение TypeError.

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

Примечание.

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

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

Задает или обновляет значение задачи. Можно set до 250 заданий для выполнения values работы.

Чтобы отобразить полную справку для этой команды, выполните команду:

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

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

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

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

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

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

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

В следующем table перечислены доступные команды для этой служебной программы, которые можно получить с помощью dbutils.notebook.help().

Команда	Описание
выход	Выходит из блокнота с заданным значением
запуск	Запускает ноутбук и возвращает код выхода

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

exit(value: String): void

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.notebook.help("exit")

Пример

В этом примере выполняется выход из записной книжки со значением Exiting from My Other Notebook.

Python

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

R

dbutils.notebook.exit("Exiting from My Other Notebook")

# Notebook exited: Exiting from My Other Notebook

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(path: String, timeoutSeconds: int, arguments: Map): String

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

Примечание.

Максимальная длина строкового значения, возвращаемого командой run, равна 5 МБ. См. Get выходные данные для одного запуска (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)

Служебная программа secrets позволяет хранить конфиденциальные учетные данные и получать к ним доступ, не делая их видимыми в записных книжках. См . раздел "Управление секретами" и шаг 3. Использование секретов в записной книжке.

В следующем table перечислены доступные команды для этой служебной программы, которые можно получить с помощью dbutils.secrets.help().

Команда	Описание
get	Возвращает строковое представление значения секрета с областью и ключом
getBytes	Возвращает байтовое представление секретного значения с указанием области действия и ключа
list	Перечисляет метаданные для секретов в пределах области
listScopes	Список секретных областей

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

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

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

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

Администраторы, создатели секретов и пользователи с соответствующим разрешением, могут читать секреты Azure Databricks. Хотя Azure Databricks предпринимает усилия по редактированию секретов values, которые могут отображаться в записных книжках, невозможно запретить таким пользователям читать секреты. Дополнительные сведения см. в статье Скрытие секретов.

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

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)

getBytes(scope: String, key: String): byte[]

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.secrets.help("getBytes")

Пример

В этом примере возвращается байтовое представление значения секрета (в этом примере a1!b2@c3#) для области с именем my-scope и именем my-keyключа.

Python

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

# Out[1]: b'a1!b2@c3#'

R

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

# [1] 61 31 21 62 32 40 63 33 23

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)

list(scope: String): Seq

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.secrets.help("list")

Пример

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

Python

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

# Out[10]: [SecretMetadata(key='my-key')]

R

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

# [[1]]
# [[1]]$key
# [1] "my-key"

Scala

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

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

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

listScopes: Seq

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.secrets.help("listScopes")

Пример

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

Python

dbutils.secrets.listScopes()

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

R

dbutils.secrets.listScopes()

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

Scala

dbutils.secrets.listScopes()

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

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

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

В следующем table перечислены доступные команды для этой служебной программы, которые можно получить с помощью dbutils.widgets.help().

Команда	Описание
комбобокс	Создает элемент ввода "выпадающий список" с заданным именем, значением по умолчанию и вариантами
выпадающее меню	Создает элемент управления выпадающим списком с заданным именем, значением по умолчанию и вариантами выбора
get	Извлекает текущее значение виджета ввода
getAll	Извлекает карту всех имен виджетов и их values
getArgument	Устаревшее. Эквивалент get
множественный выбор	Создает поле ввода с возможностью множественного выбора с заданным именем, значением по умолчанию и вариантами выбора
remove	Удаляет виджет из блокнота
removeAll	Удаляет все мини-приложения в записной книжке
текст	Создает мини-приложение ввода текста с заданным именем и значением по умолчанию

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

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

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("combobox")

Пример

В этом примере создается и отображается мини-приложение ComboBox с программным именем fruits_combobox. Он предлагает варианты apple, banana, coconutи dragon fruitset и set начальному значению 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(name: String, defaultValue: String, choices: Seq, label: String): void

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("dropdown")

Пример

В этом примере создается и отображается мини-приложение Dropdown с программным именем toys_dropdown. Он предлагает варианты alphabet blocks, basketball, capeи doll и set начальному значению 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.widgetsget)

get(name: String): String

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

Имя пользовательского мини-приложения в записной книжке, например fruits_combobox или toys_dropdown.
Имя настраиваемого параметра, передаваемого записной книжке в составе задачи записной книжки, например name или age. Дополнительные сведения см. в разделе о покрытии parameters задач записной книжки в пользовательском интерфейсе заданий или в поле 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. Этот параметр изменился с set до 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)

getAll: map

Возвращает сопоставление всех текущих имен виджетов и values. Это может быть особенно полезно, чтобы быстро передать виджет values в запрос spark.sql().

Эта команда доступна в Databricks Runtime 13.3 LTS и выше. Он доступен только для Python и Scala.

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("getAll")

Пример

Этот пример получает карту мини-приложения values и передает ее в качестве аргументов параметров в запросе 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)

getArgument(name: String, optional: String): String

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

Примечание.

Эта команда отключена. Вместо этого используйте dbutils.widgets.get.

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("getArgument")

Пример

В этом примере возвращается значение мини-приложения с программным именем fruits_combobox. Если это мини-приложение не существует, возвращается сообщение Error: Cannot find fruits combobox.

Python

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# Out[3]: 'banana'

R

dbutils.widgets.getArgument('fruits_combobox', 'Error: Cannot find fruits combobox')

# Deprecation warning: Use dbutils.widgets.text() or dbutils.widgets.dropdown() to create a widget and dbutils.widgets.get() to get its bound value.
# [1] "banana"

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(name: String, defaultValue: String, choices: Seq, label: String): void

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("multiselect")

Пример

В этом примере создается и отображается мини-приложение Multiselect с программным именем days_multiselect. Предлагаются варианты с Monday по Sunday, и set задаётся начальному значению 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)

remove(name: String): void

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("remove")

Внимание

При добавлении команды для 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)

removeAll: void

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

Чтобы отобразить полную справку для этой команды, выполните команду:

dbutils.widgets.help("removeAll")

Внимание

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

Пример

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

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

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

text(name: String, defaultValue: String, label: String): void

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

Чтобы отобразить полную справку для этой команды, выполните следующую команду:

dbutils.widgets.help("text")

Пример

В этом примере создается и отображается мини-приложение Text с программным именем your_name_text. Оно равно set начальному значению 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 рекомендует использовать один из следующих вариантов:

Для ускорения разработки приложений может быть полезно компилировать, собирать и тестировать приложения перед их развертыванием в качестве рабочих заданий. Чтобы обеспечить компиляцию с помощью служебных программ 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). См. веб-страницу API DBUtils на веб-сайте репозитория Maven для получения сведений о доступных целевых объектов и версий.

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

Внимание

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

Ограничения

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

Если необходимо выполнить операции файловой системы с исполнителями с помощью dbutils, обратитесь к методам для параллельного перечисления и удаления с помощью Spark в , чтобы быстрее list и удалять файлы в Databricks.

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

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

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

Вспомогательные модули

Справка по команде

Служебная работа для работы с данными (dbutils.data)

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

Пример

Python

R

Scala

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

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

Пример

Python

R

Scala

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

Пример

Python

R

Scala

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

Пример

Python

R

Scala

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

Пример

Python

R

Scala

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

Пример

Python

Scala

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

Пример

Python

Scala

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

Пример

Python

R

Scala

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

Пример

Python

R

Scala

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

Пример

Python

Scala

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

Пример

Python

R

Scala

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

Пример

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

Пример

Python

Scala

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

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

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

Пример

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

Пример

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

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

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

Пример

Python

R

Scala

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

Пример

Python

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