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

Artigo
12/18/2024

Este artigo contém referência para Databricks Utilities (dbutils). Os utilitários fornecem comandos que permitem que você trabalhe com seu ambiente Databricks a partir de blocos de anotações. Por exemplo, você pode gerenciar arquivos e armazenamento de objetos e trabalhar com segredos. dbutils estão disponíveis em notebooks Python, R e Scala.

Nota

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

módulos utilitários

A tabela a seguir lista os módulos Databricks Utilities, que você pode recuperar usando dbutils.help().

Módulo	Descrição
Dados	Utilitários para compreender e interagir com conjuntos de dados (EXPERIMENTAL)
fs	Utilitários para acessar o sistema de arquivos Databricks (DBFS)
empregos	Ferramentas para aproveitar as funcionalidades do trabalho
biblioteca	Preterido. Utilitários para gerenciar bibliotecas com escopo de sessão
portátil	Utilitários para gerenciar o fluxo de controle de notebooks (EXPERIMENTAL)
segredos	Ferramentas para gerir dados confidenciais em blocos de notas
widgets	Utilitários para parametrização de notebooks.
api	Utilitários para gerenciar compilações de aplicativos

Ajuda do Comando

Para listar comandos para um módulo utilitário juntamente com uma breve descrição de cada comando, acrescente .help() após o nome do módulo utilitário. O exemplo a seguir lista os comandos disponíveis para o utilitário 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 gerar ajuda para um comando, execute dbutils.<utility-name>.help("<command-name>"). O exemplo a seguir exibe ajuda para o comando copy dos utilitários do sistema de arquivos, 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

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.

O utilitário de dados permite que você compreenda e interaja com conjuntos de dados.

A tabela a seguir lista os comandos disponíveis para este utilitário, que você pode recuperar usando dbutils.data.help().

Comando	Descrição
resumir	Resuma um Spark DataFrame e visualize as estatísticas para obter insights rápidos

comando summarize (dbutils.data.summarize)

Nota

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

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

Calcula e exibe estatísticas resumidas de um Apache Spark DataFrame ou pandas DataFrame. Este comando está disponível para Python, Scala e R.

Importante

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

Para exibir a ajuda completa 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.

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.

Exemplo

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)

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.

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.

A tabela a seguir lista os comandos disponíveis para este utilitário, que você pode recuperar usando dbutils.fs.help().

Comando	Descrição
cp	Copia um ficheiro ou diretório, possivelmente entre sistemas de ficheiros
cabeça	Retorna até aos primeiros 'maxBytes' bytes do ficheiro fornecido como uma string codificada em UTF-8.
ls	Lista o conteúdo de um diretório
mkdirs	Cria o diretório fornecido caso este não exista, criando também os diretórios pai necessários.
montar	Monta o diretório de origem dado no DBFS no ponto de montagem dado
monta	Exibe informações sobre o que é montado no DBFS
MV	Move um arquivo ou diretório, possivelmente através de FileSystems
colocar	Grava a String dada em um arquivo, codificado em UTF-8
atualizarMontagens	Força todas as máquinas desse cluster a atualizar seu cache de montagem, garantindo que recebam as informações mais recentes
rm	Remove um arquivo ou diretório
desmontar	Exclui um ponto de montagem DBFS
atualizaçãoMonte	Semelhante a mount(), mas atualiza um ponto de montagem existente em vez de criar um novo

Dica

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 dbutils.fs.ls("/Volumes/main/default/my-volume/"). Veja comandos mágicos.

comando cp (dbutils.fs.cp)

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

Copia um arquivo ou diretório, possivelmente entre sistemas de arquivos.

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("cp")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.fs.help("head")

Exemplo

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)

ls(dir: String): Seq

Lista o conteúdo de um diretório.

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("ls")

Exemplo

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)

mkdirs(dir: String): boolean

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

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("mkdirs")

Exemplo

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)

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

Monta o diretório de origem especificado no DBFS no ponto de montagem especificado.

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("mount")

Exemplo

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)

mounts: Seq

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

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("mounts")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.fs.help("mv")

Exemplo

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)

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

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

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("put")

Exemplo

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)

refreshMounts: boolean

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 completa para este comando, execute:

dbutils.fs.help("refreshMounts")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.fs.help("rm")

Exemplo

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)

unmount(mountPoint: String): boolean

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 completa para este comando, execute:

dbutils.fs.help("unmount")

Exemplo

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)

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

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.

Aviso

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

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("updateMount")

Exemplo

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)

Proporciona utilitários para tirar partido das funcionalidades de tarefas.

Nota

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

A tabela a seguir lista os módulos disponíveis para esse utilitário, que você pode recuperar usando dbutils.jobs.help().

Submódulo	Descrição
taskValues	Fornece ferramentas para aproveitar os valores das tarefas de trabalho

subutilitário taskValues (dbutils.jobs.taskValues)

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.

A tabela a seguir lista os comandos disponíveis para esse subutilitário, que você pode recuperar usando dbutils.jobs.taskValues.help().

Comando	Descrição
obter	Obtém o conteúdo do valor da tarefa especificada para a tarefa especificada na execução do trabalho atual.
definido	Define ou atualiza um valor de tarefa. Você pode configurar até 250 valores de tarefa para uma execução de trabalho.

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 .

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

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

Para exibir a ajuda completa para este comando, execute:

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

Exemplo

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.

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

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 completa para este comando, execute:

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

Exemplo

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)

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.

A tabela a seguir lista os comandos disponíveis para este utilitário, que você pode recuperar usando dbutils.notebook.help().

Comando	Descrição
saída	Sai de um bloco de notas com um valor
executar	Executa um bloco de notas e devolve o respetivo valor de saída

comando exit (dbutils.notebook.exit)

exit(value: String): void

Sai de um bloco de notas com um valor.

Para exibir a ajuda completa para este comando, execute:

dbutils.notebook.help("exit")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.notebook.help("run")

Exemplo

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)

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 Passo 3: Utilizar os segredos num bloco de notas.

A tabela a seguir lista os comandos disponíveis para este utilitário, que você pode recuperar usando dbutils.secrets.help().

Comando	Descrição
obter	Obtém a representação de cadeia de caracteres de um valor secreto com escopo e chave
getBytes	Obtém a representação em bytes de um valor secreto associada a escopo e chave.
lista	Lista metadados secretos para segredos dentro de um escopo
listScopes	Lista escopos secretos

comando get (dbutils.secrets.get)

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

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 completa para este comando, execute:

dbutils.secrets.help("get")

Exemplo

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)

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

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

Para exibir a ajuda completa para este comando, execute:

dbutils.secrets.help("getBytes")

Exemplo

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)

list(scope: String): Seq

Lista os metadados para segredos dentro do escopo especificado.

Para exibir a ajuda completa para este comando, execute:

dbutils.secrets.help("list")

Exemplo

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)

listScopes: Seq

Lista os escopos disponíveis.

Para exibir a ajuda completa para este comando, execute:

dbutils.secrets.help("listScopes")

Exemplo

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)

O utilitário widgets permite parametrizar notebooks. Consulte Widgets Databricks.

A tabela a seguir lista os comandos disponíveis para este utilitário, que você pode recuperar usando dbutils.widgets.help().

Comando	Descrição
caixa de combinação	Cria um widget de entrada de caixa de combinação com um determinado nome, valor padrão e opções
lista suspensa	Cria um widget de entrada suspenso com o nome fornecido, valor padrão e opções.
obter	Recupera o valor atual de um widget de entrada
getAll	Recupera um mapa de todos os nomes de widgets e seus valores
getArgument	Descontinuado. Equivalente a obter
selecção múltipla	Cria um widget de entrada de seleção múltipla com um determinado nome, valor padrão e opções
remover	Remove um widget de entrada do bloco de anotações
removerTudo	Remove todos os widgets do bloco de notas
texto	Cria um widget de entrada de texto com um determinado nome e valor padrão

comando combobox (dbutils.widgets.combobox)

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

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 completa para este comando, execute:

dbutils.widgets.help("combobox")

Exemplo

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

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

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 completa para este comando, execute:

dbutils.widgets.help("dropdown")

Exemplo

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)

get(name: String): String

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 campo na notebook_params de trabalho (POST /jobs/run-now) na API de trabalhos.

Para exibir a ajuda completa para este comando, execute:

dbutils.widgets.help("get")

Exemplo

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)

getAll: map

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 completa para este comando, execute:

dbutils.widgets.help("getAll")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.widgets.help("getArgument")

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.widgets.help("multiselect")

Exemplo

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(name: String): void

Remove o widget com o nome programático especificado.

Para exibir a ajuda completa 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.

Exemplo

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)

removeAll: void

Remove todos os widgets do bloco de anotações.

Para exibir a ajuda completa 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.

Exemplo

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)

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

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 completa para este comando, execute:

dbutils.widgets.help("text")

Exemplo

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) está obsoleta. 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 dos executores pode produzir resultados ou erros inesperados.

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)

módulos utilitários

Ajuda do Comando

Utilitário de dados (dbutils.data)

comando summarize (dbutils.data.summarize)

Exemplo

Python

R

Scala

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

comando cp (dbutils.fs.cp)

Exemplo

Python

R

Scala

comando head (dbutils.fs.head)

Exemplo

Python

R

Scala

Comando ls (dbutils.fs.ls)

Exemplo

Python

R

Scala

comando mkdirs (dbutils.fs.mkdirs)

Exemplo

Python

R

Scala

comando mount (dbutils.fs.mount)

Exemplo

Python

Scala

comando mounts (dbutils.fs.mounts)

Exemplo

Python

Scala

comando mv (dbutils.fs.mv)

Exemplo

Python

R

Scala

comando put (dbutils.fs.put)

Exemplo

Python

R

Scala

comando refreshMounts (dbutils.fs.refreshMounts)

Exemplo

Python

Scala

comando rm (dbutils.fs.rm)

Exemplo

Python

R

Scala

comando unmount (dbutils.fs.unmount)

Exemplo

comando updateMount (dbutils.fs.updateMount)

Exemplo

Python

Scala

Utilitário de empregos (dbutils.jobs)

subutilitário taskValues (dbutils.jobs.taskValues)

comando get (dbutils.jobs.taskValues.get)

Exemplo

comando set (dbutils.jobs.taskValues.set)

Exemplo

Utilitário de biblioteca (dbutils.library)

Utilitário de notebook (dbutils.notebook)

comando exit (dbutils.notebook.exit)

Exemplo

Python

R

Scala

Executar comando (dbutils.notebook.run)

Exemplo

Python

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