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

Статья
01/07/2025

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

Примечание.

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

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

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

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

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

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

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

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

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

Команда получения сводных данных (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 задано значение false (по умолчанию), некоторые возвращаемые статистические данные включают приближения для уменьшения времени выполнения.
- Количество различных значений для категориальных столбцов может иметь около 5% относительной ошибки для столбцов с высокой кардинальностью.
- Частота значений может иметь погрешность до 0,01%, если число уникальных значений больше 10000.
- Гистограммы и процентные оценки могут иметь ошибку до 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 или больше 10 000. Например, числовое значение 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.

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

Команда	Описание
cp	Копирует файл или каталог, возможно даже между различными файловыми системами.
головы	Возвращает до первых байтов maxBytes заданного файла в виде строки, закодированной в UTF-8.
ls	Список содержимого каталога
mkdirs	Создает указанный каталог, если он не существует, а также создает все необходимые родительские каталоги.
подключение	Подключает указанный исходный каталог к DBFS в заданной точке подключения.
крепления	Отображает сведения о том, что подключено в DBFS
mv	Перемещает файл или каталог, возможно, между различными файловыми системами.
положить	Записывает указанную строку в файл, закодированный в UTF-8
обновить крепления	Принудительно обновляет кэш точек монтирования всех машин в этом кластере, обеспечивая получение актуальной информации.
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

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

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

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.

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

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

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

Примечание.

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

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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

команду get (dbutils.secret.get)

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

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

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

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

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)

команда списка (dbutils.secret.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 позволяет параметризовать записные книжки. См. статью Мини-приложения.

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

Команда	Описание
комбобокс	Создает элемент ввода "выпадающий список" с заданным именем, значением по умолчанию и вариантами
выпадающее меню	Создает элемент управления выпадающим списком с заданным именем, значением по умолчанию и вариантами выбора
получить	Извлекает текущее значение виджета ввода
getAll	Извлекает карту всех имен мини-приложений и их значений
getArgument	Устарело. Эквивалент получения
множественный выбор	Создает поле ввода с возможностью множественного выбора с заданным именем, значением по умолчанию и вариантами выбора
удалить	Удаляет виджет из блокнота
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 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(name: String, defaultValue: String, choices: Seq, label: String): void

Создает и отображает мини-приложение 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)

get(name: String): String

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

Имя пользовательского мини-приложения в записной книжке, например 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)

getAll: map

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

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 и установлено начальное значение 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

удалить команду (dbutils.widgets.remove)

remove(name: String): void

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

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

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)

removeAll: void

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

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

dbutils.widgets.help("removeAll")

Внимание

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

Пример

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

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. Для него задано начальное значение 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 в разделе "Как быстрее перечислять и удалять файлы в 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`)