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

Este artigo contém uma referência dos Utilitários do Databricks (dbutils). Os utilitários fornecem comandos que permitem que você trabalhe com seu ambiente do Databricks a partir de notebooks. Por exemplo, você pode gerenciar arquivos e armazenamento de objetos e trabalhar com segredos. dbutils estão disponíveis nos notebooks Python, R e Scala.

Módulos utilitários

A tabela a seguir lista os módulos de Utilitários do Databricks, que você pode recuperar usando dbutils.help().

Ajuda de comando

Para listar comandos para um módulo de utilitário, juntamente com uma breve descrição de cada comando, acrescente .help() após o nome do módulo do utilitário. O exemplo a seguir lista os comandos disponíveis para o utilitário de 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 a ajuda para o comando de cópia 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)

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

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

resumir comando (dbutils.data.summarize)

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

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

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

• 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 da ferramenta na parte superior da saída do resumo de dados indica o modo de execução atual.

Exemplo

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 (linguagem de programação)

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)

O utilitário do sistema de arquivos permite que você acesse o que é DBFS?. Para acessar arquivos de workspace, use comandos de shell, como %sh ls, pois existem algumas limitações ao usar comandos dbutils.fs com arquivos de workspace.

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

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 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 (linguagem de programação)

dbutils.fs.cp("/Volumes/main/default/my-volume/data.csv", "/Volumes/main/default/my-volume/new-data.csv")

// res3: Boolean = true

comando principal (dbutils.fs.head)

head(file: String, max_bytes: 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 em 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 (linguagem de programação)

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 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 (linguagem de programação)

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 dado se ainda 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 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 (linguagem de programação)

dbutils.fs.mkdirs("/Volumes/main/default/my-volume/my-data")

// res7: Boolean = true

comando de montagem (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 (linguagem de programação)

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 Armazenamento do Azure Data Lake e ao Armazenamento de Blobs.

Comando mounts (dbutils.fs.mounts)

mounts: Seq

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

Para exibir a ajuda completa para este comando, execute:

dbutils.fs.help("mounts")

Exemplo

Python

dbutils.fs.mounts()

Scala (linguagem de programação)

dbutils.fs.mounts()

Para obter exemplos de código adicionais, consulte Conectar-se ao Armazenamento do Azure Data Lake e ao Armazenamento de Blobs.

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 por uma exclusão, mesmo em movimentações entre 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 (linguagem de programação)

dbutils.fs.mv("/Volumes/main/default/my-volume/rows.csv", "/Volumes/main/default/my-volume/my-data/")

// res1: Boolean = true

colocar comando (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 cadeia de caracteres Hello, Databricks! em um arquivo chamado hello.txt em /Volumes/main/default/my-volume/. Se existir outro arquivo, 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 (linguagem de programação)

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

dbutils.fs.help("refreshMounts")

Exemplo

Python

dbutils.fs.refreshMounts()

Scala (linguagem de programação)

dbutils.fs.refreshMounts()

Para obter mais exemplos de código, confira Conectar ao Azure Data Lake Storage e Armazenamento de Blobs.

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 desabilitado 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 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 (linguagem de programação)

dbutils.fs.rm("/Volumes/main/default/my-volume/my-data/", true)

// res6: Boolean = true

comando de desmontar (dbutils.fs.unmount)

unmount(mountPoint: String): boolean

Exclui um ponto de montagem do DBFS.

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 Armazenamento do Azure Data Lake e ao Armazenamento de Blobs.

Comando updateMount (dbutils.fs.updateMount)

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

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.

Esse 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 (linguagem de programação)

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)

Fornece utilitários para aproveitar os recursos de trabalhos.

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

subutilitário taskValues (dbutils.jobs.taskValues)

Fornece comandos para aproveitar os valores de tarefa do 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 anteriores e definir valores para tarefas posteriores usarem.

Cada valor de tarefa tem uma chave exclusiva dentro da mesma tarefa. Essa chave exclusiva é conhecida como a 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 do 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.

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

obter comando (dbutils.jobs.taskValues.get)

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

Obtém o conteúdo do valor da tarefa especificado 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 localizar 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 localizar a chave desse valor de tarefa, será gerado um ValueError (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 da tarefa em um notebook que está em execução fora de um trabalho. Isso pode ser útil durante a depuração quando você quiser 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.

definir comando (dbutils.jobs.taskValues.set)

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 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 da chave desse 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 da biblioteca (dbutils.library)

A maioria dos métodos no submódulo dbutils.library foi preterida. Consulte Utilitário da 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 do notebook (dbutils.notebook)

O utilitário do notebook permite que você encadeie notebooks e atue com base nos seus resultados. Consulte Orquestrar notebooks e modularizar o código nos notebooks.

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

comando de saída (dbutils.notebook.exit)

exit(value: String): void

Sai de um notebook com um valor.

Para exibir a ajuda completa para este comando, execute:

dbutils.notebook.help("exit")

Exemplo

Esse 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 (linguagem de programação)

dbutils.notebook.exit("Exiting from My Other Notebook")

// Notebook exited: Exiting from My Other Notebook

Comando run (dbutils.notebook.run)

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

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

Para exibir a ajuda completa para este comando, execute:

dbutils.notebook.help("run")

Exemplo

Este exemplo executa um notebook chamado My Other Notebook no mesmo local do notebook de chamada. O notebook chamado termina com a linha do 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 (linguagem de programação)

dbutils.notebook.run("My Other Notebook", 60)

// res2: String = Exiting from My Other Notebook

Utilitário de segredos (dbutils.secrets)

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.

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

Comando get (dbutils.secrets.get)

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

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

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 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 (linguagem de programação)

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 de segredo 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 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 (linguagem de programação)

dbutils.secrets.getBytes(scope="my-scope", key="my-key")

// res1: Array[Byte] = Array(97, 49, 33, 98, 50, 64, 99, 51, 35)

lista de comandos (dbutils.secrets.list)

list(scope: String): Seq

Lista os metadados de 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 (linguagem de programação)

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 (linguagem de programação)

dbutils.secrets.listScopes()

// res3: Seq[com.databricks.dbutils_v1.SecretScope] = ArrayBuffer(SecretScope(my-scope))

Utilitário de widgets (dbutils.widgets)

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

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

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 combobox 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. Este widget de caixa de combinação tem um rótulo Fruits associado. Esse exemplo termina com a impressão do valor inicial do widget da 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 (linguagem de programação)

dbutils.widgets.combobox(
  "fruits_combobox",
  "banana",
  Array("apple", "banana", "coconut", "dragon fruit"),
  "Fruits"
)

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

// banana

SQL

CREATE WIDGET COMBOBOX fruits_combobox DEFAULT "banana" CHOICES SELECT * FROM (VALUES ("apple"), ("banana"), ("coconut"), ("dragon fruit"))

SELECT :fruits_combobox

-- banana

comando da lista suspensa (dbutils.widgets.dropdown)

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

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

dbutils.widgets.help("dropdown")

Exemplo

Esse exemplo cria e exibe um widget da 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 da lista suspensa vem acompanhado pelo rótulo Toys. Esse exemplo termina com a impressão do valor inicial do widget da 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 (linguagem de programação)

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

obter comando (dbutils.widgets.get)

get(name: String): String

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 transmitido ao notebook em uma tarefa, por exemplo, name ou age. Para obter mais informações, consulte a cobertura dos parâmetros das tarefas do notebook na interface do usuário dos trabalhos ou no campo notebook_params na operação Disparar uma nova execução 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 programático fruits_combobox.

Python

dbutils.widgets.get('fruits_combobox')

# banana

R

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

Scala (linguagem de programação)

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 (linguagem de programação)

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

dbutils.widgets.help("getAll")

Exemplo

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 (linguagem de programação)

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 poderá ser retornada.

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 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 (linguagem de programação)

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 de seleção múltipla (dbutils.widgets.multiselect)

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

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

dbutils.widgets.help("multiselect")

Exemplo

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 seleção múltipla 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 (linguagem de programação)

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

remover comando (dbutils.widgets.remove)

remove(name: String): void

Remova o widget com o nome programático especificado.

Para exibir a ajuda completa para este comando, execute:

dbutils.widgets.help("remove")

Exemplo

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 (linguagem de programação)

dbutils.widgets.remove("fruits_combobox")

SQL

REMOVE WIDGET fruits_combobox

comando removeAll (dbutils.widgets.removeAll)

removeAll: void

Remove todos os widgets do notebook.

Para exibir a ajuda completa para este comando, execute:

dbutils.widgets.help("removeAll")

Exemplo

Este exemplo remove todos os widgets do notebook.

Python

dbutils.widgets.removeAll()

R

dbutils.widgets.removeAll()

Scala (linguagem de programação)

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, o valor padrão e o rótulo opcional especificados.

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 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 (linguagem de programação)

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

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

• Especialista

  <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 destinos e versões disponíveis, confira a página API DBUtils no site Maven Repository.

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

Limitações

A chamada dbutils dentro de executores pode produzir resultados ou erros inesperados.

Se você precisar executar operações do sistema de arquivos em executores usando dbutils, consulte Paralelizar operações do sistema de arquivos.

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