Referencia de Utilidades de Databricks (`dbutils`)

2025-05-07

Este artículo contiene una referencia para las utilidades de Databricks (dbutils). Las utilidades proporcionan comandos que permiten trabajar con el entorno de Databricks desde cuadernos. Por ejemplo, puede administrar archivos y almacenamiento de objetos y trabajar con secretos. dbutils están disponibles en cuadernos de Python, R y Scala.

Nota:

dbutils solo admite entornos de proceso que usan DBFS.

Módulos de utilidad

En la tabla siguiente se enumeran los módulos utilidades de Databricks, que puede recuperar mediante dbutils.help().

Módulo	Descripción
datos	Utilidades para comprender e interactuar con conjuntos de datos (EXPERIMENTAL)
Fs	Utilidades para acceder al sistema de archivos de Databricks (DBFS)
empleos	Utilidades para aprovechar las características del trabajo
biblioteca	Obsolescente. Utilidades para administrar bibliotecas con ámbito de sesión
cuaderno de notas	Utilidades para administrar el flujo de control de cuadernos (EXPERIMENTAL)
secretos	Utilidades para aprovechar secretos en cuadernos
Widgets	Utilidades para parametrizar cuadernos.
API	Utilidades para administrar compilaciones de aplicaciones

Ayuda de comandos

Para enumerar los comandos de un módulo de utilidad junto con una breve descripción de cada comando, anexe .help() después del nombre del módulo de utilidad. En el ejemplo siguiente se enumeran los comandos disponibles para la utilidad notebook:

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

Para generar ayuda para un comando, ejecute dbutils.<utility-name>.help("<command-name>"). En el ejemplo siguiente se muestra ayuda para el comando de copia de utilidades del sistema de archivos, 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

Herramienta 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.

La utilidad de datos permite comprender e interactuar con conjuntos de datos.

En la tabla siguiente se enumeran los comandos disponibles para esta utilidad, que puede recuperar mediante dbutils.data.help().

Comando	Descripción
resumir	Resumir un dataframe de Spark y visualizar las estadísticas para obtener información rápida

Comando summarize (dbutils.data.summarize)

Nota:

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

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

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

Importante

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

Para mostrar la ayuda completa de 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.

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.

Ejemplo

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.

Pitón

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)

La utilidad del sistema de archivos le permite acceder a ¿Qué es DBFS?. Para acceder a los archivos del área de trabajo, use comandos de shell como %sh ls, ya que hay algunas limitaciones al usar dbutils.fs comandos con archivos del área de trabajo.

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.

En la tabla siguiente se enumeran los comandos disponibles para esta utilidad, que puede recuperar mediante dbutils.fs.help().

Comando	Descripción
Cp	Copia un archivo o directorio, potencialmente entre sistemas de archivos.
encabezado	Devuelve hasta los primeros bytes "maxBytes" del archivo especificado como una cadena codificada en UTF-8
ls	Enumera el contenido de un directorio
mkdirs	Crea el directorio especificado si no existe, sino que también crea directorios primarios necesarios.
montar	Monta el directorio de origen especificado en DBFS en el punto de montaje especificado.
Montajes	Muestra información sobre lo que se monta en DBFS
Mv	Mueve un archivo o directorio, posiblemente a través de FileSystems
poner	Escribe la cadena especificada en un archivo, codificado en UTF-8.
refreshMounts	Obliga a todas las máquinas de este clúster a actualizar su caché de montaje, lo que garantiza que reciben la información más reciente.
micrómetro	Quita un archivo o directorio
Desmontar	Elimina un punto de montaje de DBFS.
updateMount	Similar a mount(), pero actualiza un punto de montaje existente en lugar de crear uno nuevo.

Sugerencia

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

Comando cp (dbutils.fs.cp)

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("cp")

Ejemplo

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

Pitón

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)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("head")

Ejemplo

En este ejemplo se muestran los primeros 25 bytes del archivo data.csv ubicado en /Volumes/main/default/my-volume/.

Pitón

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)

ls(dir: String): Seq

Enumera el contenido de un directorio.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("ls")

Ejemplo

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.

Pitón

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)

mkdirs(dir: String): boolean

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("mkdirs")

Ejemplo

En este ejemplo se crea el directorio my-data dentro de /Volumes/main/default/my-volume/.

Pitón

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)

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("mount")

Ejemplo

Pitón

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 obtener ejemplos de código adicionales, consulte Connect to Azure Data Lake Storage and Blob Storage.

Comando mounts (dbutils.fs.mounts)

mounts: Seq

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("mounts")

Ejemplo

Advertencia

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

Pitón

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Para obtener ejemplos de código adicionales, consulte Connect to Azure Data Lake Storage and Blob Storage.

comando mv (dbutils.fs.mv)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("mv")

Ejemplo

En este ejemplo se mueve el archivo rows.csv de /Volumes/main/default/my-volume/ a /Volumes/main/default/my-volume/my-data/.

Pitón

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)

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("put")

Ejemplo

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á.

Pitón

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)

refreshMounts: boolean

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("refreshMounts")

Ejemplo

Pitón

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

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

comando rm (dbutils.fs.rm)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("rm")

Ejemplo

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

Pitón

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)

unmount(mountPoint: String): boolean

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. Vea el comando refreshMounts (dbutils.fs.refreshMounts).

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("unmount")

Ejemplo

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

Para obtener ejemplos de código adicionales, consulte Connect to Azure Data Lake Storage and Blob Storage.

Comando updateMount (dbutils.fs.updateMount)

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

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.

Advertencia

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.fs.help("updateMount")

Ejemplo

Pitón

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)

Proporciona utilidades para aprovechar las características de los trabajos.

Nota:

Esta utilidad solo está disponible para Python.

En la tabla siguiente se enumeran los módulos disponibles para esta utilidad, que puede recuperar mediante dbutils.jobs.help().

Submódulo	Descripción
taskValues	Proporciona utilidades para aprovechar los valores de tarea de trabajo

Subutilidad de taskValues (dbutils.jobs.taskValues)

Nota:

Esta utilidad secundaria solo está disponible para Python.

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

Use esta subutilidad para establecer y obtener valores arbitrarios durante la ejecución de un trabajo. Estos valores se llaman valores de tarea. Cualquier tarea puede obtener valores establecidos por tareas anteriores y establecer valores para que las tareas posteriores los utilicen.

Cada valor de tarea tiene una clave única dentro de la misma tarea. Esta clave única se conoce como clave del valor de la tarea. Se tiene acceso a un valor de tarea con el nombre de la tarea y la clave del valor de la tarea. Puede utilizar esto para transferir información de una tarea a otra dentro de la misma ejecución del 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.

En la tabla siguiente se enumeran los comandos disponibles para esta subutilidad, que puede recuperar mediante dbutils.jobs.taskValues.help().

Comando	Descripción
Obtener	Obtiene el contenido del valor de tarea especificado para la tarea especificada en la ejecución actual del trabajo.
ajustar	Establece o actualiza un valor de tarea. Puede configurar hasta 250 valores de tarea para la ejecución de un trabajo.

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.

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

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

Para mostrar la ayuda completa de este comando, ejecute:

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

Ejemplo

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.
keyes 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 produce un 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.

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

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

Para mostrar la ayuda completa de este comando, ejecute:

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

Ejemplo

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

La utilidad de cuaderno permite encadenar cuadernos y realizar acciones en sus resultados. Consulte Organización de cuadernos y modularización de código en cuadernos.

En la tabla siguiente se enumeran los comandos disponibles para esta utilidad, que puede recuperar mediante dbutils.notebook.help().

Comando	Descripción
salir	Sale de un cuaderno con un valor
correr	Ejecuta un cuaderno y devuelve su valor de salida

comando exit (dbutils.notebook.exit)

exit(value: String): void

Sale de un cuaderno con un valor.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.notebook.help("exit")

Ejemplo

En este ejemplo se sale del cuaderno con el valor Exiting from My Other Notebook.

Pitón

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)

run(path: String, timeoutSeconds: int, arguments: Map): String

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.notebook.help("run")

Ejemplo

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.

Pitón

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)

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.

En la tabla siguiente se enumeran los comandos disponibles para esta utilidad, que puede recuperar mediante dbutils.secrets.help().

Comando	Descripción
Obtener	Obtiene la representación de cadena de un valor secreto con ámbito y clave.
getBytes	Obtiene la representación de bytes de un valor secreto con ámbito y clave
lista	Enumera los metadatos secretos de los secretos dentro de un ámbito
listScopes	Enumera los ámbitos secretos

comando get (dbutils.secrets.get)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.secrets.help("get")

Ejemplo

En este ejemplo, obtiene la representación de cadena del valor secreto del ámbito denominado my-scope y la clave denominada my-key.

Pitón

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)

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.secrets.help("getBytes")

Ejemplo

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.

Pitón

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)

list(scope: String): Seq

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.secrets.help("list")

Ejemplo

En este ejemplo se enumeran los metadatos de los secretos dentro del ámbito denominado my-scope.

Pitón

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)

listScopes: Seq

Enumera los ámbitos disponibles.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.secrets.help("listScopes")

Ejemplo

En este ejemplo se enumeran los ámbitos disponibles.

Pitón

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)

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

En la tabla siguiente se enumeran los comandos disponibles para esta utilidad, que puede recuperar mediante dbutils.widgets.help().

Comando	Descripción
cuadro combinado	Crea un widget de entrada de cuadro combinado con un nombre determinado, un valor predeterminado y opciones
desplegable	Crea un widget de entrada desplegable con un nombre determinado, un valor predeterminado y opciones.
Obtener	Recupera el valor actual de un widget de entrada.
getAll	Recupera un mapa de todos los nombres de widget y sus valores
getArgument	Obsolescente. Equivalente para obtener
selección múltiple	Crea un widget de entrada de selección múltiple con un nombre determinado, un valor predeterminado y opciones.
eliminar	Quita un widget de entrada del cuaderno.
removeAll	Quita todos los widgets del cuaderno.
Mensaje de texto	Crea un widget de entrada de texto con un nombre determinado y un valor predeterminado

comando combobox (dbutils.widgets.combobox)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("combobox")

Ejemplo

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.

Pitón

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("dropdown")

Ejemplo

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.

Pitón

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)

get(name: String): String

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 tareas de cuaderno en la interfaz de usuario de trabajos o el campo notebook_params en la operación Activar una nueva ejecución de trabajo (POST /jobs/run-now) en la API de trabajos.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("get")

Ejemplo

En este ejemplo se obtiene el valor del widget que tiene el nombre de programación fruits_combobox.

Pitón

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.

Pitón

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)

getAll: map

Obtiene un mapa de todos los nombres y valores actuales de los widgets. 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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("getAll")

Ejemplo

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.

Pitón

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)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("getArgument")

Ejemplo

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.

Pitón

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)

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

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.

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("multiselect")

Ejemplo

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.

Pitón

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)

remove(name: String): void

Elimina el widget con el nombre programático especificado.

Para mostrar la ayuda completa de 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.

Ejemplo

En este ejemplo se quita el widget con el nombre de programación fruits_combobox.

Pitón

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)

removeAll: void

Quita todos los widgets del cuaderno.

Para mostrar la ayuda completa de 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.

Ejemplo

En este ejemplo se quitan todos los widgets del cuaderno.

Pitón

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

comando text (dbutils.widgets.text)

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

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

Para mostrar la ayuda completa de este comando, ejecute:

dbutils.widgets.help("text")

Ejemplo

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.

Pitón

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 utilidades de Databricks (dbutils-api) está en desuso. Databricks recomienda usar una de las siguientes opciones:

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"

Experto

<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 o errores inesperados.

Si necesita ejecutar operaciones del sistema de archivos en ejecutores mediante dbutils, consulte Paralelizar operaciones del sistema de archivos.

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

Compartir a través de

Referencia de Utilidades de Databricks (dbutils)

Módulos de utilidad

Ayuda de comandos

Herramienta de datos (dbutils.data)

Comando summarize (dbutils.data.summarize)

Ejemplo

Pitón

R

Scala

Utilidad de sistema de archivos (dbutils.fs)

Comando cp (dbutils.fs.cp)

Ejemplo

Pitón

R

Scala

comando head (dbutils.fs.head)

Ejemplo

Pitón

R

Scala

Comando ls (dbutils.fs.ls)

Ejemplo

Pitón

R

Scala

comando mkdirs (dbutils.fs.mkdirs)

Ejemplo

Pitón

R

Scala

comando mount (dbutils.fs.mount)

Ejemplo

Pitón

Scala

Comando mounts (dbutils.fs.mounts)

Ejemplo

Pitón

Scala

comando mv (dbutils.fs.mv)

Ejemplo

Pitón

R

Scala

comando put (dbutils.fs.put)

Ejemplo

Pitón

R

Scala

comando refreshMounts (dbutils.fs.refreshMounts)

Ejemplo

Pitón

Scala

comando rm (dbutils.fs.rm)

Ejemplo

Pitón

R

Scala

comando unmount (dbutils.fs.unmount)

Ejemplo

Comando updateMount (dbutils.fs.updateMount)

Ejemplo

Pitón

Scala

Utilidad de trabajos (dbutils.jobs)

Subutilidad de taskValues (dbutils.jobs.taskValues)

comando get (dbutils.jobs.taskValues.get)

Ejemplo

comando set (dbutils.jobs.taskValues.set)

Ejemplo

Utilidad de biblioteca (dbutils.library)

Utilidad de cuaderno (dbutils.notebook)

comando exit (dbutils.notebook.exit)

Ejemplo

Pitón

R

Scala

comando run (dbutils.notebook.run)

Ejemplo

Pitón

Referencia de Utilidades de Databricks (`dbutils`)