Referência de Utilitários do Databricks (`dbutils`)

Artigo
11/21/2024

Este artigo é uma referência para Databricks Utilities (dbutils). Os utilitários dbutils estão disponíveis nos notebooks Python, R e Scala. Você pode usar os utilitários para:

Trabalhe com arquivos e armazenamento de objetos de forma eficiente.
Trabalhando com os segredos.

Observação

dbutils suporta apenas ambientes de computação que usam DBFS.

Como: listar utilitários, listar comandos, exibir a ajuda do comando

Utilitários: dados, fs, trabalhos, biblioteca, notebook, segredos, widgets, Biblioteca de API de utilitários

Listar utilitários disponíveis

Para listar os utilitários disponíveis juntamente com uma breve descrição de cada um, execute dbutils.help() para Python ou Scala.

Este exemplo lista os comandos disponíveis para os Utilitários do 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

Listar comandos disponíveis para um utilitário

Para listar os comandos disponíveis para um utilitário juntamente com uma breve descrição de cada comando, execute .help() após o nome programático do utilitário.

Este exemplo lista os comandos disponíveis para o utilitário DBFS (Sistema de Arquivos do Databricks).

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

Exibir a ajuda para um comando

Para exibir a ajuda de um comando, execute .help("<command-name>") após o nome do comando.

Este exemplo exibe a ajuda para o comando DBFS copy.

Python

dbutils.fs.help("cp")

R

dbutils.fs.help("cp")

Scala

dbutils.fs.help("cp")

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

Utilitário de dados (dbutils.data)

Importante

Esse recurso está em uma versão prévia.

Observação

Disponível no Databricks Runtime 9.0 e superior.

Comandos: summarize

O utilitário de dados permite que você compreenda e interprete conjuntos de dados. Para listar os comandos disponíveis, execute 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 e exibe as estatísticas de resumo de um DataFrame do Apache Spark ou do pandas. Esse comando está disponível para Python, Scala e R.

Este comando analisa o conteúdo completo do DataFrame. Executar este comando para DataFrames muito grandes pode ser muito caro.

Para exibir a ajuda desse comando, execute dbutils.data.help("summarize").

No Databricks Runtime 10.4 LTS e posteriores, você pode usar o parâmetro adicional precise para ajustar a precisão das estatísticas computadas.

Observação

Esse recurso está em uma versão prévia.

Quando precise é definido como false (o padrão), algumas estatísticas retornadas incluem aproximações para reduzir o tempo de execução.
- O número de valores distintos para colunas categóricas pode ter aproximadamente ~5% de erro relativo para colunas com alta cardinalidade.
- As contagens de valor frequentes podem ter um erro de até 0,01% quando o número de valores distintos é maior que 10000.
- Os histogramas e as estimativas de percentil podem ter um erro de até 0,01% em relação ao número total de linhas.
Quando precise é definido como true, as estatísticas são computadas com precisão mais alta. Todas as estatísticas, exceto os histogramas e os percentis de colunas numéricas, agora são exatas.
- Os histogramas e as estimativas de percentil podem ter um erro de até 0,0001% em relação ao número total de linhas.

A dica de ferramenta na parte superior da saída do resumo de dados indica o modo da execução atual.

Este exemplo mostra estatísticas de resumo para um DataFrame do Apache Spark com aproximações habilitadas por padrão. Para ver os resultados, execute este comando em um notebook. Este exemplo se baseia em Conjuntos de dados de exemplo.

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)

A visualização usa a notação SI para renderizar de forma concisa valores numéricos menores que 0,01 ou maiores que 10000. Por exemplo, o valor numérico 1.25e-15 será renderizado como 1.25f. Uma exceção: a visualização usa “B” para 1.0e9 (giga) em vez de “G”.

Utilitário de sistema de arquivos (dbutils.fs)

Aviso

A implementação do Python de todos os métodos dbutils.fs usa snake_case em vez de camelCase para formatação de palavra-chave.

Por exemplo, dbutils.fs.help() exibe a opção extraConfigs para dbutils.fs.mount(). No entanto, em Python você usaria a palavra-chave extra_configs.

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

O utilitário do sistema de arquivos permite acessar O que é DBFS?, facilitando o uso do Azure Databricks como sistema de arquivos.

Em notebooks, você pode usar o comando magic para acessar o %fs DBFS. Por exemplo, %fs ls /Volumes/main/default/my-volume/ é o mesmo que duties.fs.ls("/Volumes/main/default/my-volume/"). Veja comandos magic.

Para listar os comandos disponíveis, execute 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 um arquivo ou diretório, possivelmente entre sistemas de arquivos.

Para exibir a ajuda desse comando, execute dbutils.fs.help("cp").

Este exemplo copia o arquivo denominado data.csv do /Volumes/main/default/my-volume/ para o new-data.csv no mesmo volume.

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)

Retorna até o número máximo especificado de bytes no arquivo fornecido. Os bytes são retornados como uma cadeia de caracteres codificada em UTF-8.

Para exibir a ajuda desse comando, execute dbutils.fs.help("head").

Este exemplo exibe os primeiros 25 bytes do arquivo data.csv localizado em /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)

Lista o conteúdo de um diretório.

Para exibir a ajuda desse comando, execute dbutils.fs.help("ls").

Este exemplo exibe informações sobre o conteúdo de /Volumes/main/default/my-volume/. O campo modificationTime está disponível no Databricks Runtime 10.4 LTS e superior. Em R, modificationTime é retornado como uma cadeia de caracteres.

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)

Cria o diretório dado se ainda não existir. Também cria todos os diretórios pai necessários.

Para exibir a ajuda desse comando, execute dbutils.fs.help("mkdirs").

Este exemplo cria o diretório 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 o diretório de origem especificado no DBFS no ponto de montagem especificado.

Para exibir a ajuda desse comando, execute 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 obter exemplos de código adicionais, consulte Acessar Azure Data Lake Storage Gen2 e Armazenamento de Blobs.

comando mounts (dbutils.fs.mounts)

Exibe informações sobre o que está montado atualmente no DBFS.

Para exibir a ajuda desse comando, execute dbutils.fs.help("mounts").

Aviso

Chame dbutils.fs.refreshMounts() em todos os outros clusters em execução para propagar a nova montagem. Consultecomando refreshMounts (dbutils.fs.refreshMounts).

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Para obter exemplos de código adicionais, consulte Acessar Azure Data Lake Storage Gen2 e Armazenamento de Blobs.

comando mv (dbutils.fs.mv)

Move um arquivo ou diretório, possivelmente entre sistemas de arquivos. Uma movimentação é uma cópia seguida por uma exclusão, mesmo em movimentações entre sistemas de arquivos.

Para exibir a ajuda desse comando, execute dbutils.fs.help("mv").

Este exemplo move o arquivo rows.csv de /Volumes/main/default/my-volume/ para /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)

Grava a cadeia de caracteres especificada em um arquivo. A cadeia de caracteres é codificada em UTF-8.

Para exibir a ajuda desse comando, execute dbutils.fs.help("put").

Este exemplo grava cadeia de caracteres Hello, Databricks! em um arquivo chamado hello.txt em /Volumes/main/default/my-volume/. Se outro arquivo existir, ele será substituído.

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)

Força todos os computadores no cluster a atualizar seu cache de montagem, o que faz com que eles recebam as informações mais recentes.

Para exibir a ajuda desse comando, execute dbutils.fs.help("refreshMounts").

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Para obter exemplos de código adicionais, consulte Acessar Azure Data Lake Storage Gen2 e Armazenamento de Blobs.

comando rm (dbutils.fs.rm)

Remove um arquivo ou diretório e, opcionalmente, todo o seu conteúdo. Se um arquivo for especificado, o recurse parâmetro será ignorado. Se um diretório for especificado, ocorrerá um erro quando recurse estiver desabilitado e o diretório não estiver vazio.

Para exibir a ajuda desse comando, execute dbutils.fs.help("rm").

Este exemplo remove todo o diretório /Volumes/main/default/my-volume/my-data/ , incluindo seu conteúdo.

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)

Exclui um ponto de montagem do DBFS.

Aviso

Para evitar erros, nunca modifique um ponto de montagem enquanto outros trabalhos estiverem lendo ou gravando nele. Depois de modificar uma montagem, sempre execute dbutils.fs.refreshMounts() em todos os outros clusters em execução para propagar quaisquer atualizações de montagem. Consultecomando refreshMounts (dbutils.fs.refreshMounts).

Para exibir a ajuda desse comando, execute dbutils.fs.help("unmount").

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

Para obter exemplos de código adicionais, consulte Acessar Azure Data Lake Storage Gen2 e Armazenamento de Blobs.

Comando updateMount (dbutils.fs.updateMount)

Semelhante ao comando dbutils.fs.mount, mas atualiza um ponto de montagem existente em vez de criar outro. Retornará um erro se não houver um ponto de montagem.

Para exibir a ajuda desse comando, execute dbutils.fs.help("updateMount").

Aviso

Esse comando está disponível no Databricks Runtime 10.4 LTS e superior.

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

Utilitário de trabalhos (dbutils.jobs)

Subutilitários: taskValues

Observação

Este utilitário está disponível somente para Python.

O utilitário de trabalhos permite que você aproveite os recursos de trabalho. Para exibir a ajuda desse utilitário, execute dbutils.jobs.help().

Provides utilities for leveraging jobs features.

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

Subutilitário taskValues (dbutils.jobs.taskValues)

Comandos: get, set

Observação

Esse subutilitário está disponível somente para Python.

Fornece comandos para aproveitar os valores da tarefa de trabalho.

Use esse subutilitário para definir e obter valores arbitrários durante a execução de um trabalho. Esses valores são chamados de valores de tarefa. Qualquer tarefa pode obter valores definidos por tarefas upstream e definir valores para tarefas downstream usarem.

Cada valor de tarefa tem uma chave exclusiva dentro da mesma tarefa. Essa chave exclusiva é conhecida como a chave do valor de tarefa. Um valor de tarefa é acessado com o nome da tarefa e a chave do valor de tarefa. Você pode usar isso para passar informações downstream de tarefa para tarefa dentro da mesma execução de trabalho. Por exemplo, você pode passar identificadores ou métricas, como informações sobre a avaliação de um modelo de aprendizado de máquina, entre diferentes tarefas em uma execução de trabalho.

Para exibir a ajuda desse subutilitário, execute dbutils.jobs.taskValues.help().

Comando get (dbutils.jobs.taskValues.get)

Observação

Este comando está disponível somente para Python.

No Databricks Runtime 10.4 e anterior, se get não encontrar a tarefa, um Py4JJavaError será gerado em vez de um ValueError.

Obtém o conteúdo do valor de tarefa especificado para a tarefa especificada na execução de trabalho atual.

Para exibir a ajuda desse comando, execute dbutils.jobs.taskValues.help("get").

Por exemplo:

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

No exemplo anterior:

taskKey é o nome da tarefa que define o valor da tarefa. Se o comando não conseguir localizar essa tarefa, um ValueError será gerado.
key é o nome da chave do valor de tarefa que você definiu com o comando set (dbutils.jobs.taskValues.set). Se o comando não puder localizar essa chave de valor de tarefa, ValueError será gerado (a menos que default seja especificado).
default é um valor opcional que será retornado se key não puder ser encontrado. default não pode ser None.
debugValue é um valor opcional que será retornado se você tentar obter o valor de tarefa de dentro de um notebook que está em execução fora de um trabalho. Isso pode ser útil durante a depuração quando você deseja executar seu notebook manualmente e retornar algum valor em vez de gerar um TypeError por padrão. debugValue não pode ser None.

Se você tentar obter um valor de tarefa de dentro de um notebook que está em execução fora de um trabalho, esse comando gerará um TypeError por padrão. No entanto, se o argumento debugValue for especificado no comando, o valor de debugValue será retornado em vez de gerar um TypeError.

Comando set (dbutils.jobs.taskValues.set)

Observação

Este comando está disponível somente para Python.

Define ou atualiza um valor de tarefa. Você pode configurar até 250 valores de tarefa para uma execução de trabalho.

Para exibir a ajuda desse comando, execute dbutils.jobs.taskValues.help("set").

Alguns exemplos incluem:

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

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

Nos exemplos anteriores:

key é a chave do valor da tarefa. Essa chave deve ser exclusiva para a tarefa. Ou seja, se duas tarefas diferentes definirem um valor de tarefa com a chave K, esses serão dois valores de tarefa diferentes que têm a mesma chave K.
value é o valor dessa chave de valor de tarefa. Esse comando deve poder representar o valor internamente no formato JSON. O tamanho da representação JSON do valor não pode exceder 48 KiB.

Se você tentar definir um valor de tarefa de dentro de um notebook que está em execução fora de um trabalho, esse comando não fará nada.

Utilitário de biblioteca (dbutils.library)

A maioria dos métodos no submódulo dbutils.library foi preterida. Veja Utilitário de biblioteca (dbutils.library) (herdado).

Talvez seja necessário reiniciar programaticamente o processo do Python no Azure Databricks para garantir que as bibliotecas instaladas ou atualizadas localmente funcionem corretamente no kernel do Python para o SparkSession atual. Para fazer isso, execute o comando dbutils.library.restartPython. Confira Reiniciar o processo do Python no Azure Databricks.

Utilitário de notebook (dbutils.notebook)

Comandos: exit, run

O utilitário de notebook permite encadear notebooks e agir em relação a seus resultados. Confira Executar um notebook do Databricks por meio de outro notebook.

Para listar os comandos disponíveis, execute 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)

Sai de um notebook com um valor.

Para exibir a ajuda desse comando, execute dbutils.notebook.help("exit").

Este exemplo sai do notebook com o 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

Observação

Se a execução tiver uma consulta com o streaming estruturado em execução em segundo plano, a chamada de dbutils.notebook.exit() não terminará a execução. A execução continuará a ser executada enquanto a consulta estiver sendo executada em segundo plano. Você pode interromper a execução da consulta em segundo plano clicando em Cancelar na célula da consulta ou executando query.stop(). Quando a consulta parar, você poderá terminar a execução com dbutils.notebook.exit().

Comando run (dbutils.notebook.run)

Executa um notebook e retorna o valor de saída. O notebook será executado no cluster atual por padrão.

Observação

O tamanho máximo do valor da cadeia de caracteres retornada pelo comando run é 5 MB. Confira Obter a saída para uma execução única (GET /jobs/runs/get-output).

Para exibir a ajuda desse comando, execute dbutils.notebook.help("run").

Este exemplo executa um notebook chamado My Other Notebook no mesmo local do notebook de chamada. O notebook chamado termina com a linha de código dbutils.notebook.exit("Exiting from My Other Notebook"). Se o notebook chamado não concluir a execução dentro de 60 segundos, uma exceção será lançada.

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

Utilitário de segredos (dbutils.secrets)

Comandos: get, getBytes, list, listScopes

O utilitário de segredos permite que você armazene e acesse informações confidenciais de credenciais sem torná-las visíveis nos notebooks. Consulte Gerenciamento de segredos e Etapa 3: Usar os segredos em um notebook. Para listar os comandos disponíveis, execute 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)

Obtém a representação de cadeia de caracteres de um valor de segredo para o escopo e a chave do segredo especificados.

Aviso

Administradores, criadores de segredo e usuários que receberam permissão podem ler os segredos do Azure Databricks. Embora o Azure Databricks se esforce para remover os valores secretos que podem ser exibidos nos notebooks, não é possível impedir que esses usuários leiam os segredos. Para mais informações, confira Remoção de segredos.

Para exibir a ajuda desse comando, execute dbutils.secrets.help("get").

Este exemplo obtém a representação de cadeia de caracteres do valor do segredo para o escopo chamado my-scope e a chave chamada 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)

Obtém a representação de bytes de um valor de segredo para o escopo e a chave especificados.

Para exibir a ajuda desse comando, execute dbutils.secrets.help("getBytes").

Este exemplo obtém a representação de byte do valor do segredo (neste exemplo, a1!b2@c3#) para o escopo chamado my-scope e a chave chamada 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)

Lista os metadados de segredos dentro do escopo especificado.

Para exibir a ajuda desse comando, execute dbutils.secrets.help("list").

Este exemplo lista os metadados para segredos dentro do escopo chamado 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)

Lista os escopos disponíveis.

Para exibir a ajuda desse comando, execute dbutils.secrets.help("listScopes").

Este exemplo lista os escopos disponíveis.

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

Utilitário de widgets (dbutils.widgets)

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

O utilitário de widgets permite parametrizar notebooks. Confira Widgets do Databricks.

Para listar os comandos disponíveis, execute 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)

Cria e exibe um widget de caixa de combinação com o nome programático, o valor padrão, as opções e o rótulo opcional especificados.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("combobox").

Este exemplo cria e exibe um widget de caixa de combinação com o nome programático fruits_combobox. Ele oferece as opções apple, banana, coconut e dragon fruit e é definido com o valor inicial de banana. Esse widget de caixa de combinação vem acompanhado pelo rótulo Fruits. Este exemplo termina com a impressão do valor inicial do widget de caixa de combinação, 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

Cria e exibe um widget de lista suspensa com o nome programático, o valor padrão, as opções e o rótulo opcional especificados.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("dropdown").

Este exemplo cria e exibe um widget de lista suspensa com o nome programático toys_dropdown. Ele oferece as opções alphabet blocks, basketball, cape e doll e é definido com o valor inicial de basketball. Esse widget de lista suspensa vem acompanhado pelo rótulo Toys. Este exemplo termina com a impressão do valor inicial do widget de lista suspensa, 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)

Obtém o valor atual do widget com o nome programático especificado. Esse nome programático pode ser:

O nome de um widget personalizado no bloco de anotações, por exemplo, fruits_combobox ou toys_dropdown.
O nome de um parâmetro personalizado passado transmitido ao notebook como parte de uma tarefa de notebook, por exemplo, name ou age. Para mais informações, confira a cobertura de parâmetros para tarefas de notebook na interface do usuário de trabalhos ou no campo notebook_params na operação Acionar uma nova execução de trabalho (POST /jobs/run-now) na API de trabalhos.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("get").

Este exemplo obtém o valor do widget que tem o nome programático 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

Este exemplo obtém o valor do parâmetro de tarefa do notebook que tem o nome programático age. Esse parâmetro foi definido como 35 quando a tarefa de notebook relacionada foi executada.

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)

Obtém um mapeamento de todos os valores e nomes de widget atuais. Isso pode ser especialmente útil para passar rapidamente valores de widget para uma consulta spark.sql().

Este comando está disponível no Databricks Runtime 13.3 LTS e superior. Ele só está disponível para Python e Scala.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("getAll").

Este exemplo obtém o mapa de valores de widget e passa-o como argumentos de parâmetro em uma consulta SQL do Spark.

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)

Obtém o valor atual do widget com o nome programático especificado. Se o widget não existir, uma mensagem opcional poderá ser retornada.

Observação

Esse comando foi preterido. Use dbutils.widgets.get.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("getArgument").

Este exemplo obtém o valor do widget que tem o nome programático fruits_combobox. Se esse widget não existir, a mensagem Error: Cannot find fruits combobox será retornada.

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)

Cria e exibe um widget de multisseleção com o nome programático, o valor padrão, as opções e o rótulo opcional especificados.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("multiselect").

Este exemplo cria e exibe um widget de multisseleção com o nome programático days_multiselect. Ele oferece as opções Monday a Sunday e é definido com o valor inicial de Tuesday. Esse widget de multisseleção vem acompanhado de um rótulo Days of the Week. Este exemplo termina com a impressão do valor inicial do widget de multisseleção, 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)

Remove o widget com o nome programático especificado.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("remove").

Importante

Se você adicionar um comando para remover um widget, não poderá adicionar um comando subsequente para criar um widget na mesma célula. Você deve criar o widget em outra célula.

Este exemplo remove o widget com o nome programático 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)

Remove todos os widgets do notebook.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("removeAll").

Importante

Se você adicionar um comando para remover todos os widgets, não poderá adicionar um comando subsequente para criar um widget na mesma célula. Você precisa criar o widget em outra célula.

Este exemplo remove todos os widgets do notebook.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

Comando text (dbutils.widgets.text)

Cria e exibe um widget de texto com o nome programático, o valor padrão e o rótulo opcional especificados.

Para exibir a ajuda desse comando, execute dbutils.widgets.help("text").

Este exemplo cria e exibe um widget de texto com o nome programático your_name_text. Ele é definido como o valor inicial de Enter your name. Este widget de texto vem acompanhado de um rótulo Your name. Este exemplo termina com a impressão do valor inicial do 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 API de utilitários do Databricks

Importante

A biblioteca da API de Utilitários do Databricks (dbutils-api) foi preterida. Embora essa biblioteca ainda esteja disponível, não há planos de implementação de nenhum novo recurso do Databricks na biblioteca dbutils-api.

O Databricks recomenda que você use uma das seguintes bibliotecas:

Para acelerar o desenvolvimento de aplicativos, pode ser útil compilar e testar aplicativos antes de implantá-los como trabalhos de produção. Para que você possa compilar com Utilitários do Databricks, o Databricks fornece a biblioteca dbutils-api. Você pode baixar a biblioteca dbutils-api da página da Web da API DBUtils no site do Repositório Maven ou incluí-la adicionando uma dependência ao arquivo de build:

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'

Substitua TARGET pelo destino desejado (por exemplo, 2.12) e VERSION pela versão desejada (por exemplo, 0.0.5). Para ver uma lista de versões e destinos disponíveis, confira a página da Web API DBUtils no site do Repositório Maven.

Depois de criar seu aplicativo com essa biblioteca, você poderá implantá-lo.

Importante

A dbutils-api biblioteca só permite compilar localmente um aplicativo que usa dbutils, não para executá-lo. Para executar o aplicativo, você precisará implantá-lo Azure Databricks.

Limitações

O chamamento de dbutils dentro de executores pode produzir resultados inesperados ou possivelmente resultar em erros.

Se você precisar executar operações do sistema de arquivos em executores usando dbutils, consulte os métodos de listagem paralela e exclusão usando o Spark em Como listar e excluir arquivos mais rapidamente no Databricks.

Para saber mais sobre executores, confira Visão geral do Modo de Cluster no site do Apache Spark.

Compartilhar via

Referência de Utilitários do Databricks (dbutils)

Listar utilitários disponíveis

Python

Scala

Listar comandos disponíveis para um utilitário

Python

R

Scala

Exibir a ajuda para um comando

Python

R

Scala

Utilitário de dados (dbutils.data)

comando summarize (dbutils.data.summarize)

Python

R

Scala

Utilitário de sistema de arquivos (dbutils.fs)

comando cp (dbutils.fs.cp)

Python

R

Scala

comando head (dbutils.fs.head)

Python

R

Scala

comando ls (dbutils.fs.ls)

Python

R

Scala

Comando mkdirs (dbutils.fs.mkdirs)

Python

R

Scala

comando mount (dbutils.fs.mount)

Python

Scala

comando mounts (dbutils.fs.mounts)

Python

Scala

comando mv (dbutils.fs.mv)

Python

R

Scala

comando put (dbutils.fs.put)

Python

R

Scala

comando refreshMounts (dbutils.fs.refreshMounts)

Python

Scala

comando rm (dbutils.fs.rm)

Python

R

Scala

Comando unmount (dbutils.fs.unmount)

Comando updateMount (dbutils.fs.updateMount)

Python

Scala

Utilitário de trabalhos (dbutils.jobs)

Subutilitário taskValues (dbutils.jobs.taskValues)

Comando get (dbutils.jobs.taskValues.get)

Comando set (dbutils.jobs.taskValues.set)

Utilitário de biblioteca (dbutils.library)

Utilitário de notebook (dbutils.notebook)

Comando exit (dbutils.notebook.exit)

Python

R

Scala

Comando run (dbutils.notebook.run)

Python

Scala

Utilitário de segredos (dbutils.secrets)

Comando get (dbutils.secrets.get)

Python

R

Scala

Comando getBytes (dbutils.secrets.getBytes)

Python

Referência de Utilitários do Databricks (`dbutils`)