Compartir a través de

Referencia de Utilidades de Databricks (dbutils)

  • Artículo

Este artículo es una referencia para Utilidades de Databricks (dbutils). Las utilidades dbutils están disponibles en cuadernos de Python, R y Scala. Puede usar las utilidades para:

  • Trabajar con archivos y almacenamiento de objetos de forma eficaz.
  • Trabajar con secretos.

Nota:

dbutils solo admite entornos de proceso que usan DBFS.

Cómo: enumerar las utilidades, enumerar los comandos, mostrar la ayuda para los comandos

Utilidades: datos, sistema de archivos, trabajos, biblioteca, cuaderno, secretos, widgets, Biblioteca de la API de utilidades

Enumeración de las utilidades disponibles

Para enumerar las utilidades disponibles junto con una breve descripción de cada una de ellas, ejecute dbutils.help() para Python o Scala.

En este ejemplo se enumeran los comandos disponibles para las utilidades de 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

Enumeración de los comandos disponibles para una utilidad

A fin de enumerar los comandos disponibles para una utilidad junto con una breve descripción de cada uno de ellos, ejecute .help() después del nombre de programación de la utilidad.

En este ejemplo se enumeran los comandos disponibles para la utilidad del sistema de archivos de Databricks (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

Visualización de ayuda para un comando

A fin de mostrar la ayuda para un comando, ejecute .help("<command-name>") después del nombre del comando.

En este ejemplo se muestra la ayuda para el comando de copia de DBFS.

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

Utilidad de datos (dbutils.data)

Importante

Esta característica está en versión preliminar pública.

Nota:

Disponible en Databricks Runtime 9.0 y versiones posteriores.

Comandos: summarize

La utilidad de datos permite comprender e interpretar conjuntos de datos. Para enumerar los comandos disponibles, ejecute 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

Comando summarize (dbutils.data.summarize)

Calcula y muestra estadísticas de resumen de un DataFrame de Apache Spark o un DataFrame de Pandas. Este comando está disponible para Python, Scala y R.

Este comando analiza el contenido completo del dataframe. La ejecución de este comando para dataFrames muy grandes puede utilizar muchos recursos.

A fin de mostrar la ayuda para este comando, ejecute dbutils.data.help("summarize").

En Databricks Runtime 10.4 LTS y versiones posteriores, puedes usar el parámetro precise adicional para ajustar la precisión de las estadísticas calculadas.

Nota:

Esta característica está en versión preliminar pública.

  • Cuando precise se establece en False (valor predeterminado), algunas estadísticas devueltas incluyen aproximaciones para reducir el tiempo de ejecución.
    • El número de valores distintos para las columnas de categorías puede tener un error relativo de ~5 % para las columnas de alta cardinalidad.
    • Los recuentos de valores frecuentes pueden tener un error de hasta el 0,01 % cuando el número de valores distintos es mayor que 10 000.
    • Las estimaciones de percentil y los histogramas pueden tener un error de hasta un 0,01 % con respecto al número total de filas.
  • Cuando precise se establece en True, las estadísticas se calculan con mayor precisión. Ahora todas las estadísticas, excepto los histogramas y percentiles de las columnas numéricas, son exactas.
    • Las estimaciones de percentil y los histogramas pueden tener un error de hasta un 0,0001 % con respecto al número total de filas.

La información sobre herramientas en la parte superior de la salida de resumen de datos indica el modo de la ejecución actual.

En este ejemplo se muestran estadísticas de resumen de un DataFrame de Apache Spark con aproximaciones habilitadas de manera predeterminada. Para ver los resultados, ejecute este comando en un cuaderno. Este ejemplo se basa en conjuntos de datos de ejemplo.

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)

La visualización usa la notación SI para representar concisamente valores numéricos menores que 0,01 o mayores que 10000. Por ejemplo, el valor numérico 1.25e-15 se representará como 1.25f. Una excepción: la visualización usa "B" para 1.0e9 (giga) en lugar de "G".

Utilidad de sistema de archivos (dbutils.fs)

Advertencia

La implementación de Python de todos los métodos dbutils.fs usa snake_case en lugar de camelCase para el formato de palabras clave.

Por ejemplo, dbutils.fs.help() muestra la opción extraConfigs para dbutils.fs.mount(). Sin embargo, en Python usaría la palabra clave extra_configs.

Comandos: cp, head, ls, mkdirs, mount, mounts, mv, put, refreshMounts, rm, unmount, updateMount

La utilidad del sistema de archivos le permite acceder a ¿Qué es DBFS?, lo que facilita el uso de Azure Databricks como sistema de archivos.

En los cuadernos, puede usar el %fs comando magic para acceder a DBFS. Por ejemplo, %fs ls /Volumes/main/default/my-volume/ es lo mismo que duties.fs.ls("/Volumes/main/default/my-volume/"). Consulte Comandos mágicos.

Para enumerar los comandos disponibles, ejecute 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

Comando cp (dbutils.fs.cp)

Copia un archivo o un directorio, posiblemente entre sistemas de archivos.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("cp").

En este ejemplo se copia el archivo denominado data.csv de /Volumes/main/default/my-volume/ a new-data.csv en el mismo volumen.

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

Comando head (dbutils.fs.head)

Devuelve hasta el número máximo especificado de bytes en el archivo especificado. Los bytes se devuelven como una cadena codificada en UTF-8.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("head").

En este ejemplo se muestran los primeros 25 bytes del archivo data.csv ubicado en /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"

Comando ls (dbutils.fs.ls)

Enumera el contenido de un directorio.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("ls").

En este ejemplo se muestra información sobre el contenido de /Volumes/main/default/my-volume/. El campo modificationTime está disponible en Databricks Runtime 10.4 LTS y versiones posteriores. En R, modificationTime se devuelve como una cadena.

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

Comando mkdirs (dbutils.fs.mkdirs)

Crea el directorio indicado en caso de que no exista. También crea los directorios primarios necesarios.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("mkdirs").

En este ejemplo se crea el directorio my-data dentro de /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

Comando mount (dbutils.fs.mount)

Monta el directorio de origen especificado en DBFS en el punto de montaje especificado.

A fin de mostrar la ayuda para este comando, ejecute 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>")))

Para ver ejemplos de código adicionales, consulte Conectar a Azure Data Lake Storage Gen2 y Blob Storage.

Comando mounts (dbutils.fs.mounts)

Muestra información sobre lo que está montado actualmente en DBFS.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("mounts").

Advertencia

Llame a dbutils.fs.refreshMounts() en todos los demás clústeres en ejecución para propagar el nuevo montaje. Vea Comando refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Para ver ejemplos de código adicionales, consulte Conectar a Azure Data Lake Storage Gen2 y Blob Storage.

Comando mv (dbutils.fs.mv)

Mueve un archivo o un directorio, posiblemente entre sistemas de archivos. Un movimiento es una copia seguida de una eliminación, incluso para los movimientos dentro de los sistemas de archivos.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("mv").

En este ejemplo se mueve el archivo rows.csv de /Volumes/main/default/my-volume/ a /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

Comando put (dbutils.fs.put)

Escribe la cadena especificada en un archivo. La cadena está codificada en UTF-8.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("put").

En este ejemplo se escribe la cadena Hello, Databricks! en un archivo denominado hello.txt en /Volumes/main/default/my-volume/. Si el archivo existe, se sobrescribirá.

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

Comando refreshMounts (dbutils.fs.refreshMounts)

Fuerza a todas las máquinas del clúster a actualizar su caché de montaje, de modo que se asegura de que reciben la información más reciente.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Para ver ejemplos de código adicionales, consulte Conectar a Azure Data Lake Storage Gen2 y Blob Storage.

Comando rm (dbutils.fs.rm)

Quita un archivo o directorio y, opcionalmente, todo su contenido. Si se especifica un archivo, se omite el recurse parámetro . Si se especifica un directorio, se produce un error cuando recurse está deshabilitado y el directorio no está vacío.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("rm").

En este ejemplo se quita todo el directorio /Volumes/main/default/my-volume/my-data/ , incluido su contenido.

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

Comando unmount (dbutils.fs.unmount)

Elimina un punto de montaje de DBFS.

Advertencia

Para evitar errores, nunca modifique un punto de montaje mientras otros trabajos leen o escriben en él. Después de modificar un montaje, ejecute siempre dbutils.fs.refreshMounts() en todos los demás clústeres en ejecución para propagar las actualizaciones de montaje. Ver Comando refreshMounts (dbutils.fs.refreshMounts).

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("unmount").

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

Para ver ejemplos de código adicionales, consulte Conectar a Azure Data Lake Storage Gen2 y Blob Storage.

Comando updateMount (dbutils.fs.updateMount)

Es similar al comando dbutils.fs.mount, pero actualiza un punto de montaje existente en lugar de crear uno nuevo. Devuelve un error si el punto de montaje no está presente.

A fin de mostrar la ayuda para este comando, ejecute dbutils.fs.help("updateMount").

Advertencia

Para evitar errores, nunca modifique un punto de montaje mientras otros trabajos leen o escriben en él. Después de modificar un montaje, ejecute siempre dbutils.fs.refreshMounts() en todos los demás clústeres en ejecución para propagar las actualizaciones de montaje. Ver Comando refreshMounts (dbutils.fs.refreshMounts).

Este comando está disponible en Databricks Runtime 10.4 LTS y versiones posteriores.

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

Utilidad de trabajos (dbutils.jobs)

Utilidades secundarias: taskValues

Nota:

Esta utilidad solo está disponible para Python.

La utilidad de trabajos permite aprovechar las características de los trabajos. Para mostrar la ayuda de este comando, ejecute dbutils.jobs.help().

Provides utilities for leveraging jobs features.

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

Subutilidad taskValues (dbutils.jobs.taskValues)

Comandos: get, set

Nota:

Esta utilidad secundaria solo está disponible para Python.

Proporciona comandos para aprovechar los valores de las tareas del trabajo.

Use esta subconsulta para establecer y obtener valores arbitrarios durante una ejecución de trabajo. Estos valores se llaman valores de tarea. Cualquier tarea puede obtener valores establecidos por tareas ascendentes y establecer valores para las tareas de nivel inferior que se van a usar.

Cada valor de tarea tiene una clave única dentro de la misma tarea. Esta clave única se conoce como la clave del valor de tarea. Se accede a un valor de tarea con el nombre de la tarea y la clave del valor de tarea. Puede usarlo para pasar información de bajada de la tarea a la tarea dentro de la misma ejecución de trabajo. Por ejemplo, puede pasar identificadores o métricas, como información sobre la evaluación de un modelo de aprendizaje automático, entre diferentes tareas dentro de una ejecución de trabajo.

Para mostrar la ayuda de esta utilidad secundaria, ejecute dbutils.jobs.taskValues.help().

Comando get (dbutils.jobs.taskValues.get)

Nota:

Este comando solo está disponible para Python.

En Databricks Runtime 10.4 y versiones anteriores, si get no encuentra la tarea, se genera un error Py4JJavaError en lugar de ValueError.

Obtiene el contenido del valor de tarea especificado para la tarea especificada en la ejecución actual del trabajo.

A fin de mostrar la ayuda para este comando, ejecute dbutils.jobs.taskValues.help("get").

Por ejemplo:

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

En el ejemplo anterior:

  • taskKey es el nombre de la tarea que establece el valor de la tarea. Si el comando no encuentra esta tarea, se genera una excepción ValueError.
  • key es el nombre de la clave del valor de tarea que estableció con el comando set (dbutils.jobs.taskValues.set). Si el comando no encuentra la clave de este valor de tarea, se genera una excepción ValueError (a menos que se especifique default).
  • default es un valor opcional que se devuelve si no se encuentra key. default no puede ser None.
  • debugValue es un valor opcional que se devuelve si intenta obtener el valor de tarea desde un cuaderno que se ejecuta fuera de un trabajo. Esto puede ser útil durante la depuración cuando quiera ejecutar el cuaderno manualmente y devolver algún valor en lugar de generar una excepción TypeError de manera predeterminada. debugValue no puede ser None.

Si intenta obtener un valor de tarea desde un cuaderno que se ejecuta fuera de un trabajo, este comando genera una excepción TypeError de manera predeterminada. Sin embargo, si se especifica el argumento debugValue en el comando, se devuelve el valor de debugValue en lugar de generar una excepción TypeError.

Comando set (dbutils.jobs.taskValues.set)

Nota:

Este comando solo está disponible para Python.

Establece o actualiza un valor de tarea. Puede configurar hasta 250 valores de tarea para la ejecución de un trabajo.

A fin de mostrar la ayuda para este comando, ejecute dbutils.jobs.taskValues.help("set").

Estos son algunos ejemplos:

dbutils.jobs.taskValues.set(key   = "my-key", \
                            value = 5)

dbutils.jobs.taskValues.set(key   = "my-other-key", \
                            value = "my other value")

En los ejemplos anteriores:

  • key es la clave del valor de la tarea. Esta clave debe ser única en la tarea. Es decir, si dos tareas diferentes establecen un valor de tarea con clave K, son dos valores de tarea diferentes que tienen la misma clave K.
  • value es el valor de la clave de este valor de tarea. Este comando debe ser capaz de representar el valor internamente en formato JSON. El tamaño de la representación JSON del valor no puede superar los 48 KiB.

Si intenta establecer un valor de tarea desde un cuaderno que se ejecuta fuera de un trabajo, este comando no hace nada.

Utilidad de biblioteca (dbutils.library)

La mayoría de los métodos del submódulo dbutils.library están en desuso. Consulte Utilidad de biblioteca (dbutils.library) (heredado).

Es posible que deba reiniciar mediante programación el proceso de Python en Azure Databricks para asegurarse de que las bibliotecas instaladas o actualizadas localmente funcionan correctamente en el kernel de Python para la SparkSession actual. Para ello, ejecute el comando dbutils.library.restartPython. Consulte Reinicio del proceso de Python en Azure Databricks.

Utilidad de cuaderno (dbutils.notebook)

Comandos: exit, run

La utilidad de cuaderno permite encadenar cuadernos y realizar acciones en sus resultados. Consulte Ejecutar un cuaderno de Databricks desde otro cuaderno.

Para enumerar los comandos disponibles, ejecute 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.

Comando exit (dbutils.notebook.exit)

Sale de un cuaderno con un valor.

A fin de mostrar la ayuda para este comando, ejecute dbutils.notebook.help("exit").

En este ejemplo se sale del cuaderno con el valor 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

Nota:

Si la ejecución tiene una consulta con flujo estructurado que se ejecuta en segundo plano, la llamada a dbutils.notebook.exit() no finaliza la ejecución. La ejecución continuará ejecutándose mientras la consulta se ejecute en segundo plano. Para detener la consulta que se ejecuta en segundo plano, haga clic en Cancelar en la celda de la consulta o ejecute query.stop(). Cuando se detenga la consulta, podrá finalizar la ejecución con dbutils.notebook.exit().

Comando run (dbutils.notebook.run)

Ejecuta un cuaderno y devuelve su valor de salida. El cuaderno se ejecutará en el clúster actual de manera predeterminada.

Nota:

La longitud máxima del valor de cadena devuelto por el comando run es de 5 MB. Consulte Obtención de la salida de una sola ejecución (GET /jobs/runs/get-output).

A fin de mostrar la ayuda para este comando, ejecute dbutils.notebook.help("run").

En este ejemplo se ejecuta un cuaderno denominado My Other Notebook en la misma ubicación que el cuaderno que realiza la llamada. El cuaderno al que se realiza la llamada termina con la línea de código dbutils.notebook.exit("Exiting from My Other Notebook"). Si el cuaderno al que se realiza la llamada no termina de ejecutarse en 60 segundos, se produce una excepción.

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

Utilidad de secretos (dbutils.secrets)

Comandos: get, getBytes, list, listScopes

La utilidad de secretos permite almacenar información confidencial de las credenciales y acceder a ella sin hacer que sean visibles en los cuadernos. Consulte Administración de secretos y Paso 3: Uso de los secretos en un cuaderno. Para enumerar los comandos disponibles, ejecute 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

Comando get (dbutils.secrets.get)

Obtiene la representación de cadena del valor de un secreto para la clave y el ámbito de secretos especificados.

Advertencia

Los secretos de Azure Databricks pueden leerlos los administradores, los creadores de secretos y aquellos usuarios a los que se haya concedido el permiso pertinente. Aunque Azure Databricks hace un esfuerzo por redactar valores secretos que se puedan mostrar en cuadernos, no es posible impedir que estos usuarios lean secretos. Para más información, consulte el artículo sobre redacción de secretos.

A fin de mostrar la ayuda para este comando, ejecute dbutils.secrets.help("get").

En este ejemplo se obtiene la representación de cadena del valor del secreto para el ámbito denominado my-scope y la clave denominada 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]

Comando getBytes (dbutils.secrets.getBytes)

Obtiene la representación de bytes del valor de un secreto para la clave y el ámbito especificados.

A fin de mostrar la ayuda para este comando, ejecute dbutils.secrets.help("getBytes").

Este ejemplo obtiene la representación en bytes del valor del secreto (en este ejemplo, a1!b2@c3#) para el ámbito llamado my-scope y la clave llamada 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)

Comando list (dbutils.secrets.list)

Enumera los metadatos de los secretos dentro del ámbito especificado.

A fin de mostrar la ayuda para este comando, ejecute dbutils.secrets.help("list").

En este ejemplo se enumeran los metadatos de los secretos dentro del ámbito denominado 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))

Comando listScopes (dbutils.secrets.listScopes)

Enumera los ámbitos disponibles.

A fin de mostrar la ayuda para este comando, ejecute dbutils.secrets.help("listScopes").

En este ejemplo se enumeran los ámbitos disponibles.

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

Utilidad de widgets (dbutils.widgets)

Comandos: combobox, dropdown, get, getArgument, multiselect, remove, removeAll, text

La utilidad de widgets permite parametrizar cuadernos. Consulte Widgets de Databricks.

Para enumerar los comandos disponibles, ejecute 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

Comando combobox (dbutils.widgets.combobox)

Crea y muestra un widget de cuadro combinado con el nombre de programación, el valor predeterminado, las opciones y la etiqueta opcional que se especifican.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("combobox").

En este ejemplo se crea y muestra un widget de cuadro combinado con el nombre de programación fruits_combobox. Ofrece las opciones apple, banana, coconut y dragon fruit, y se establece en el valor inicial de banana. Este widget de cuadro combinado tiene una etiqueta Fruits que lo acompaña. Este ejemplo termina con la impresión del valor inicial del widget de cuadro combinado, 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

Comando dropdown (dbutils.widgets.dropdown)

Crea y muestra un widget desplegable con el nombre de programación, el valor predeterminado, las opciones y la etiqueta opcional que se especifican.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("dropdown").

En este ejemplo se crea y muestra un widget desplegable con el nombre de programación toys_dropdown. Ofrece las opciones alphabet blocks, basketball, cape y doll, y se establece en el valor inicial de basketball. Este widget desplegable tiene una etiqueta Toys que lo acompaña. Este ejemplo termina con la impresión del valor inicial del widget desplegable, 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

Comando get (dbutils.widgets.get)

Obtiene el valor actual del widget con el nombre de programación especificado. Este nombre de programación puede ser uno de los siguientes:

  • Nombre de un widget personalizado en el cuaderno, por ejemplo, fruits_combobox o toys_dropdown.
  • El nombre de un parámetro personalizado pasado al cuaderno como parte de una tarea de cuaderno, por ejemplo name o age. Para obtener más información, consulte la cobertura de parámetros para las tareas de cuadernos en la interfaz de usuario de trabajos o el campo notebook_params en la operación para desencadenar la ejecución de un trabajo nuevo (POST /jobs/run-now) de Jobs API.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("get").

En este ejemplo se obtiene el valor del widget que tiene el nombre de programación 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

En este ejemplo se obtiene el valor del parámetro de tarea del cuaderno que tiene el nombre de programación age. Este parámetro se estableció en 35 cuando se ejecutó la tarea del cuaderno relacionada.

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

comando getAll (dbutils.widgets.getAll)

Obtiene una asignación de todos los nombres y valores actuales del widget. Esto puede ser especialmente útil para pasar rápidamente valores de widget a una consulta spark.sql().

Este comando está disponible en Databricks Runtime 13.3 LTS y versiones posteriores. Solo está disponible para Python y Scala.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("getAll").

En este ejemplo se obtiene el mapa de los valores del widget y se pasa como argumentos de parámetro en una consulta de 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

Comando getArgument (dbutils.widgets.getArgument)

Obtiene el valor actual del widget con el nombre de programación especificado. Si el widget no existe, se puede devolver un mensaje opcional.

Nota:

Este comando está en desuso. Use dbutils.widgets.get en su lugar.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("getArgument").

En este ejemplo se obtiene el valor del widget que tiene el nombre de programación fruits_combobox. Si este widget no existe, se devuelve el mensaje 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

Comando multiselect (dbutils.widgets.multiselect)

Crea y muestra un widget de selección múltiple con el nombre de programación, el valor predeterminado, las opciones y la etiqueta opcional que se especifican.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("multiselect").

En este ejemplo se crea y muestra un widget de selección múltiple con el nombre de programación days_multiselect. Ofrece las opciones de Monday a Sunday y se establece en el valor inicial de Tuesday. Este widget de selección múltiple tiene una etiqueta Days of the Week que lo acompaña. Este ejemplo termina con la impresión del valor inicial del widget de selección múltiple, 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

Comando remove (dbutils.widgets.remove)

Quita el widget con el nombre de programación especificado.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("remove").

Importante

Si agrega un comando para quitar un widget, no puede agregar un comando posterior para crear un widget en la misma celda. Debe crear el widget en otra celda.

En este ejemplo se quita el widget con el nombre de programación 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

Comando removeAll (dbutils.widgets.removeAll)

Quita todos los widgets del cuaderno.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("removeAll").

Importante

Si agrega un comando para quitar todos los widgets, no puede agregar un comando posterior para crear widgets en la misma celda. Debe crear los widgets en otra celda.

En este ejemplo se quitan todos los widgets del cuaderno.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

Comando text (dbutils.widgets.text)

Crea y muestra un widget de texto con el nombre de programación, el valor predeterminado y la etiqueta opcional que se especifican.

A fin de mostrar la ayuda para este comando, ejecute dbutils.widgets.help("text").

En este ejemplo se crea y muestra un widget de texto con el nombre de programación your_name_text. Se establece en el valor inicial de Enter your name. Este widget de texto tiene una etiqueta Your name que lo acompaña. Este ejemplo termina con la impresión del valor inicial del widget de texto, 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

Biblioteca de la API de utilidades de Databricks

Importante

La biblioteca de la API de utilidades de Databricks (dbutils-api) está en desuso. Aunque esta biblioteca sigue estando disponible, Databricks no planea ningún nuevo trabajo de características para la biblioteca dbutils-api.

Databricks recomienda usar una de las siguientes bibliotecas en su lugar:

Para acelerar el desarrollo de aplicaciones, puede resultar útil compilar, crear y probar aplicaciones antes de implementarlas como trabajos de producción. Para poder compilar con las utilidades de Databricks, Databricks proporciona la biblioteca dbutils-api. Puede descargar la biblioteca dbutils-api desde la página web de la API de DBUtils en el sitio web del repositorio de Maven o incluir la biblioteca mediante la adición de una dependencia al archivo de compilación:

  • 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'

Reemplace TARGET por el destino deseado (por ejemplo, 2.12) y VERSION por la versión deseada (por ejemplo, 0.0.5). Para obtener una lista de los destinos y versiones disponibles, consulte la página web de la API de DBUtils en el sitio web del repositorio de Maven.

Una vez compilada la aplicación con esta biblioteca, puede implementarla.

Importante

La dbutils-api biblioteca solo permite compilar localmente una aplicación que usa dbutils, no para ejecutarla. Para ejecutar la aplicación, debe implementarla en Azure Databricks.

Limitaciones

Llamar a dbutils dentro de los ejecutores puede producir resultados inesperados o, potencialmente, generar errores.

Si necesita ejecutar operaciones del sistema de archivos en ejecutores mediante dbutils, consulte la lista en paralelo y elimine métodos mediante Spark en Cómo enumerar y eliminar archivos más rápido en Databricks.

Para obtener información sobre los ejecutores, consulte Información general sobre el modo de clúster en el sitio web de Apache Spark.