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

Artigo
11/14/2024

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

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

Nota

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

Como: Listar utilitários, comandos de lista, exibir ajuda de comando

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

Listar utilitários disponíveis

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

Este exemplo lista os comandos disponíveis para os utilitários 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 Databricks File System (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

Exibir 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

Esta funcionalidade está em Pré-visualização Pública.

Nota

Disponível no Databricks Runtime 9.0 e superior.

Comandos: resumir

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 estatísticas resumidas de um Apache Spark DataFrame ou pandas DataFrame. Este 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 para este comando, execute dbutils.data.help("summarize").

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

Nota

Esta funcionalidade está em Pré-visualização Pública.

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 ~5% de erro relativo para colunas de alta cardinalidade.
- As contagens de valores frequentes podem ter um erro de até 0,01% quando o número de valores distintos é maior que 10000.
- Os histogramas e estimativas de percentis 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 calculadas com maior precisão. Todas as estatísticas, exceto os histogramas e percentis para colunas numéricas, agora são exatas.
- Os histogramas e estimativas de percentis 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 exibe estatísticas de resumo para um Apache Spark DataFrame com aproximações habilitadas por padrão. Para ver os resultados, execute este comando num bloco de notas. Este exemplo é baseado 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 processar de forma concisa valores numéricos menores que 0,01 ou maiores que 10000. Como exemplo, o valor 1.25e-15 numérico será renderizado como 1.25f. Uma exceção: a visualização usa "B" para 1.0e9 (giga) em vez de "G".

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

Aviso

A implementação Python de todos os dbutils.fs métodos usa snake_case em vez de para formatação de camelCase palavras-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 que você acesse O que é DBFS?, facilitando o uso do Azure Databricks como um sistema de arquivos.

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

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 para este comando, execute dbutils.fs.help("cp").

Este exemplo copia o arquivo nomeado data.csv de /Volumes/main/default/my-volume/ para 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 UTF-8.

Para exibir a ajuda para este 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 para este comando, execute dbutils.fs.help("ls").

Este exemplo exibe informações sobre o conteúdo do /Volumes/main/default/my-volume/. O modificationTime campo está disponível em 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 fornecido se ele não existir. Também cria todos os diretórios pai necessários.

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

Este exemplo cria o diretório my-data dentro /Volumes/main/default/my-volume/do .

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 para este 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 Conectar-se ao Azure Data Lake Storage Gen2 e Blob Storage.

comando mounts (dbutils.fs.mounts)

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

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

Aviso

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

Python

dbutils.fs.mounts()

Scala

dbutils.fs.mounts()

Para obter exemplos de código adicionais, consulte Conectar-se ao Azure Data Lake Storage Gen2 e Blob Storage.

comando mv (dbutils.fs.mv)

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

Para exibir a ajuda para este 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 para este comando, execute dbutils.fs.help("put").

Este exemplo grava a cadeia de caracteres Hello, Databricks! em um arquivo chamado hello.txt em /Volumes/main/default/my-volume/. Se o 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 todas as máquinas no cluster a atualizar seu cache de montagem, garantindo que recebam as informações mais recentes.

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

Python

dbutils.fs.refreshMounts()

Scala

dbutils.fs.refreshMounts()

Para obter exemplos de código adicional, consulte Conectar-se ao Azure Data Lake Storage Gen2 e Blob Storage.

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 desativado e o diretório não estiver vazio.

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

Este exemplo remove o diretório /Volumes/main/default/my-volume/my-data/ inteiro, 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 DBFS.

Aviso

Para evitar erros, nunca modifique um ponto de montagem enquanto outros trabalhos estão 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. Consulte o comando refreshMounts (dbutils.fs.refreshMounts).

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

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

Para obter exemplos de código adicionais, consulte Conectar-se ao Azure Data Lake Storage Gen2 e Blob Storage.

comando updateMount (dbutils.fs.updateMount)

Semelhante ao dbutils.fs.mount comando, mas atualiza um ponto de montagem existente em vez de criar um novo. Retorna um erro se o ponto de montagem não estiver presente.

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

Aviso

Este 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 empregos (dbutils.jobs)

Subutilitários: taskValues

Nota

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

O utilitário de trabalhos permite que você aproveite os recursos de trabalhos. Para exibir a ajuda para este 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

Nota

Este subutilitário está disponível apenas para Python.

Fornece comandos para alavancar valores de tarefas de trabalho.

Use este 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 a serem usadas.

Cada valor de tarefa tem uma chave exclusiva dentro da mesma tarefa. Essa chave exclusiva é conhecida como chave do valor da tarefa. Um valor de tarefa é acessado com o nome da tarefa e a chave do valor da 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 dentro de uma execução de trabalho.

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

comando get (dbutils.jobs.taskValues.get)

Nota

Este comando está disponível apenas para Python.

No Databricks Runtime 10.4 e anteriores, se get não for possível localizar a tarefa, um Py4JJavaError será gerado em vez de um ValueErrorarquivo .

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

Para exibir a ajuda para este 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 encontrar essa tarefa, um ValueError será gerado.
keyé o nome da chave do valor da tarefa que você define com o comando set (dbutils.jobs.taskValues.set). Se o comando não conseguir encontrar a chave desse valor de tarefa, um será gerado (a ValueError menos que default seja especificado).
default é um valor opcional que é retornado se key não puder ser encontrado. default não pode ser None.
debugValue é um valor opcional que é retornado se você tentar obter o valor da tarefa de dentro de um bloco de anotações que está sendo executado fora de um trabalho. Isso pode ser útil durante a depuração quando você deseja executar seu bloco de anotações 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 bloco de anotações que esteja sendo executado fora de um trabalho, esse comando gerará um TypeError por padrão. No entanto, se o debugValue argumento for especificado no comando, o valor de debugValue é retornado em vez de gerar um TypeErrorarquivo .

comando set (dbutils.jobs.taskValues.set)

Nota

Este comando está disponível apenas 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 para este 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 cada uma um valor de tarefa com chave K, estes são dois valores de tarefa diferentes que têm a mesma chave K.
value é o valor da chave deste valor de tarefa. Este comando deve ser capaz de 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 bloco de anotações que esteja sendo executado fora de um trabalho, esse comando não fará nada.

Utilitário de biblioteca (dbutils.library)

A maioria dos métodos no dbutils.library submódulo são preteridos. Consulte Utilitário de biblioteca (dbutils.library) (legado).

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

Utilitário de notebook (dbutils.notebook)

Comandos: sair, executar

O utilitário de notebook permite que você encadeie notebooks e aja de acordo com seus resultados. Consulte Executar um bloco de notas Databricks a partir de outro bloco de notas.

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 bloco de notas com um valor.

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

Este exemplo sai do bloco de anotações 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

Nota

Se a execução tiver uma consulta com streaming estruturado em execução em segundo plano, a chamada dbutils.notebook.exit() não encerrará 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 for interrompida, você poderá encerrar a execução com dbutils.notebook.exit().

Executar comando (dbutils.notebook.run)

Executa um bloco de anotações e retorna seu valor de saída. O bloco de anotações será executado no cluster atual por padrão.

Nota

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

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

Este exemplo executa um bloco de anotações nomeado My Other Notebook no mesmo local que o bloco de anotações de chamada. O chamado caderno termina com a linha de código dbutils.notebook.exit("Exiting from My Other Notebook"). Se o bloco de anotações chamado não terminar de ser executado em 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 Segredos (dbutils.secrets)

Comandos: get, getBytes, list, listScopes

O utilitário secrets permite armazenar e acessar informações confidenciais de credenciais sem torná-las visíveis em blocos de anotações. Consulte Gestão de segredos e Utilizar os segredos num bloco de notas. 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 secreto para o escopo e a chave de segredos especificados.

Aviso

Administradores, criadores de segredos e usuários com permissão podem ler segredos do Azure Databricks. Embora o Azure Databricks faça um esforço para redigir valores secretos que podem ser exibidos em blocos de anotações, não é possível impedir que esses usuários leiam segredos. Para obter mais informações, consulte Redação secreta.

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

Este exemplo obtém a representação de cadeia de caracteres do valor secreto para o escopo nomeado 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 secreto para o escopo e a chave especificados.

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

Este exemplo obtém a representação de bytes do valor secreto (neste exemplo, a1!b2@c3#) para o escopo nomeado 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 para segredos dentro do escopo especificado.

Para exibir a ajuda para este 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 para este 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 Widgets (dbutils.widgets)

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

O utilitário widgets permite parametrizar notebooks. Consulte Widgets 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 especificado, valor padrão, opções e rótulo opcional.

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

Este exemplo cria e exibe um widget de caixa de combinação com o nome fruits_comboboxprogramático . Ele oferece as opções apple, banana, coconut, e dragon fruit é definido como o valor inicial de banana. Este widget de caixa de combinação tem um rótulo Fruitsque o acompanha. Este exemplo termina imprimindo o 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 suspenso com o nome programático especificado, valor padrão, opções e rótulo opcional.

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

Este exemplo cria e exibe um widget suspenso com o nome toys_dropdownprogramático . Ele oferece as opções alphabet blocks, basketball, cape, e doll é definido como o valor inicial de basketball. Este widget suspenso tem um rótulo Toysque acompanha . Este exemplo termina imprimindo o valor inicial do widget suspenso, 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. Este 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 para o bloco de anotações como parte de uma tarefa do bloco de anotações, por exemplo name ou age. Para obter mais informações, consulte a cobertura de parâmetros para tarefas de bloco de anotações na interface do usuário de trabalhos ou o notebook_params campo na operação Acionar uma nova execução de trabalho (POST /jobs/run-now) na API de trabalhos.

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

Este exemplo obtém o valor do widget que tem o nome fruits_comboboxprogramático .

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 bloco de anotações que tem o nome ageprogramático . Esse parâmetro foi definido como 35 quando a tarefa de bloco de anotações 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 nomes e valores atuais do widget. Isso pode ser especialmente útil para passar rapidamente valores de widget para uma spark.sql() consulta.

Este comando está disponível no Databricks Runtime 13.3 LTS e superior. Está disponível apenas para Python e Scala.

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

Este exemplo obtém o mapa de valores de widget e o passa 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 pode ser retornada.

Nota

Este comando foi preterido. Use dbutils.widgets.get em vez disso.

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

Este exemplo obtém o valor do widget que tem o nome fruits_comboboxprogramático . 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 seleção múltipla com o nome programático especificado, valor padrão, opções e rótulo opcional.

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

Este exemplo cria e exibe um widget de seleção múltipla com o nome days_multiselectprogramático . Ele oferece as opções Monday através Sunday e é definido para o valor inicial de Tuesday. Este widget multiselect tem uma etiqueta Days of the Weekque o acompanha. Este exemplo termina imprimindo o valor inicial do widget multiselect, Tuesday.

Python

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=['Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'],
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# Tuesday

R

dbutils.widgets.multiselect(
  name='days_multiselect',
  defaultValue='Tuesday',
  choices=list('Monday', 'Tuesday', 'Wednesday', 'Thursday',
    'Friday', 'Saturday', 'Sunday'),
  label='Days of the Week'
)

print(dbutils.widgets.get("days_multiselect"))

# [1] "Tuesday"

Scala

dbutils.widgets.multiselect(
  "days_multiselect",
  "Tuesday",
  Array("Monday", "Tuesday", "Wednesday", "Thursday",
    "Friday", "Saturday", "Sunday"),
  "Days of the Week"
)

print(dbutils.widgets.get("days_multiselect"))

// Tuesday

SQL

CREATE WIDGET MULTISELECT days_multiselect DEFAULT "Tuesday" CHOICES SELECT * FROM (VALUES ("Monday"), ("Tuesday"), ("Wednesday"), ("Thursday"), ("Friday"), ("Saturday"), ("Sunday"))

SELECT :days_multiselect

-- Tuesday

comando remove (dbutils.widgets.remove)

Remove o widget com o nome programático especificado.

Para exibir a ajuda para este 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 fruits_comboboxprogramático .

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 bloco de anotações.

Para exibir a ajuda para este 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 widgets na mesma célula. Você deve criar os widgets em outra célula.

Este exemplo remove todos os widgets do bloco de anotações.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala

dbutils.widgets.removeAll()

comando de texto (dbutils.widgets.text)

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

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

Este exemplo cria e exibe um widget de texto com o nome your_name_textprogramático . É definido como o valor inicial de Enter your name. Este widget de texto tem um rótulo Your nameque o acompanha. Este exemplo termina imprimindo o 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 da API do Databricks Utilities

Importante

A biblioteca Databricks Utilities API (dbutils-api) foi preterida. Embora essa biblioteca ainda esteja disponível, o Databricks não planeja nenhum novo trabalho de recurso para a dbutils-api biblioteca.

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

Para acelerar o desenvolvimento de aplicativos, pode ser útil compilar, criar e testar aplicativos antes de implantá-los como trabalhos de produção. Para permitir que você compile em relação aos utilitários Databricks, o Databricks fornece a dbutils-api biblioteca. Você pode baixar a dbutils-api biblioteca da página da API DBUtils no site do repositório Maven ou incluir a biblioteca adicionando uma dependência ao seu arquivo de compilação:

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 obter uma lista de destinos e versões disponíveis, consulte a página da API DBUtils no site do repositório Maven.

Depois de compilar seu aplicativo em relação a essa biblioteca, você pode implantar o aplicativo.

Importante

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

Limitações

Chamar dbutils dentro de executores pode produzir resultados inesperados ou potencialmente resultar em erros.

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

Para obter informações sobre executores, consulte Visão geral do modo de cluster no site do Apache Spark.

Partilhar via

Referência de Utilitários Databricks (dbutils)

Listar utilitários disponíveis

Python

Scala

Listar comandos disponíveis para um utilitário

Python

R

Scala

Exibir ajuda para um comando

Python

R

Scala

Utilitário de dados (dbutils.data)

comando summarize (dbutils.data.summarize)

Python

R

Scala

Utilitário do 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 empregos (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

Executar comando (dbutils.notebook.run)

Python

Scala

Utilitário Segredos (dbutils.secrets)

comando get (dbutils.secrets.get)

Python

R

Scala

comando getBytes (dbutils.secrets.getBytes)

Python

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