Referência de databricks russas (dbutils)

Este artigo contém referência para Databricks utilidades (dbutils). As utilidades fornecem comandos que permitem que o senhor trabalhe com seu ambiente Databricks a partir do Notebook. Por exemplo, o senhor pode gerenciar arquivos e armazenamento de objetos e trabalhar com segredos. dbutils estão disponíveis em Python, R e Scala Notebook.

Observação

dbutils O senhor só é compatível com ambientes compute que usam DBFS.

módulos de utilidades

A tabela a seguir lista os módulos Databricks utilidades, que o senhor pode recuperar usando dbutils.help().

Módulo

Descrição

credenciais

Utilidades para interagir com credenciais no Notebook

dados

utilidades para entender e interagir com o conjunto de dados (EXPERIMENTAL)

fs

utilidades para acessar o sistema de arquivos Databricks (DBFS)

empregos

utilidades para alavancar o Job recurso

Biblioteca

Obsoleto. utilidades para gerenciar biblioteca com escopo de sessão

meta

utilidades para conectar ao compilador (EXPERIMENTAL)

notebook

utilidades para gerenciar o fluxo de controle do Notebook (EXPERIMENTAL)

Prévia

utilidades em pré-visualização

segredos

utilidades para aproveitar segredos no Notebook

Widgets

utilidades para parametrizar o Notebook.

API

utilitários para gerenciar compilações de aplicativos

Ajuda do comando

Para listar o comando de um módulo de utilidades junto com uma breve descrição de cada comando, acrescente .help() após o nome do módulo de utilidades. O exemplo a seguir lista os comandos disponíveis para as utilidades do 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 sistema de arquivos utilidades copy comando, 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

Utilidade de credenciais (dbutils.credentials)

A utilidade de credenciais permite interagir com credenciais em notebooks. Essa utilidade só pode ser usada em clusters com passagem de credenciais habilitada.

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.credentials.help().

Comando

Descrição

Assuma um papel

Define a função que o ARN deve assumir ao procurar credenciais para autenticação no S3.

Mostrar função atual

Mostra a função atualmente definida.

Mostrar funções

Mostra o conjunto de possíveis funções assumidas.

comando AssumeRole (dbutils.credentials.assumeRole)

assumeRole(role: String): boolean

Define o Amazon Resource Name (ARN) para a função do AWS Identity and Access Management (IAM) a ser assumida ao procurar credenciais para autenticação no Amazon S3. Depois de executar esse comando, você pode executar comandos de acesso do S3, como sc.textFile("s3a://my-bucket/my-file.csv"), para acessar um objeto.

Para exibir a ajuda completa para esse comando, execute:

dbutils.credentials.help("assumeRole")

Exemplo 

dbutils.credentials.assumeRole("arn:aws:iam::123456789012:roles/my-role")

# Out[1]: True

dbutils.credentials.assumeRole("arn:aws:iam::123456789012:roles/my-role")

# TRUE

dbutils.credentials.assumeRole("arn:aws:iam::123456789012:roles/my-role")

// res0: Boolean = true

Comando showCurrentRole (dbutils.credentials.showCurrentRole)

showCurrentRole: List

Lista a função atualmente definida do AWS Identity and Access Management (IAM).

Para exibir a ajuda completa para esse comando, execute:

dbutils.credentials.help("showCurrentRole")

Exemplo 

dbutils.credentials.showCurrentRole()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a']

dbutils.credentials.showCurrentRole()

# [[1]]
# [1] "arn:aws:iam::123456789012:role/my-role-a"

dbutils.credentials.showCurrentRole()

// res0: java.util.List[String] = [arn:aws:iam::123456789012:role/my-role-a]

Comando showRoles (dbutils.credentials.showRoles)

showRoles: List

Lista o conjunto de possíveis funções assumidas do AWS Identity and Access Management (IAM).

Para exibir a ajuda completa para esse comando, execute:

dbutils.credentials.help("showRoles")

Exemplo 

dbutils.credentials.showRoles()

# Out[1]: ['arn:aws:iam::123456789012:role/my-role-a', 'arn:aws:iam::123456789012:role/my-role-b']

dbutils.credentials.showRoles()

# [[1]]
# [1] "arn:aws:iam::123456789012:role/my-role-a"
#
# [[2]]
# [1] "arn:aws:iam::123456789012:role/my-role-b"

dbutils.credentials.showRoles()

// res0: java.util.List[String] = [arn:aws:iam::123456789012:role/my-role-a, arn:aws:iam::123456789012:role/my-role-b]

Utilidade de dados (dbutils.data)

Visualização

Esse recurso está na Visualização pública.

Observação

Disponível no Databricks Runtime 9.0e acima.

Os utilitários de dados permitem que o senhor compreenda e interaja com o conjunto de dados.

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.data.help().

Comando

Descrição

resumem

Resuma um Spark DataFrame e visualize as estatísticas para obter percepções rápidas

Comando summarize (dbutils.data.summarize)

Observação

Esse recurso está na Visualização pública.

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

Calcula e exibe estatísticas resumidas de um DataFrame do Apache Spark ou DataFrame do pandas. Este comando está disponível para o 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 esse comando, execute:

dbutils.data.help("summarize")

Em Databricks Runtime 10.4 LTS e acima, o senhor pode usar o parâmetro adicional precise para ajustar a precisão das estatísticas de computação.

  • 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 10.000.

    • Os histogramas e estimativas de percentis podem apresentar um erro de até 0,01% em relação ao número total de linhas.

  • Quando o precise está configurado como true (verdadeiro), 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 as 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 resumidas para um DataFrame do Apache Spark com aproximações habilitadas por default. Para ver os resultados, execute esse comando em um notebook. Este exemplo é baseado em amostras de datasets.

df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
dbutils.data.summarize(df)

df <- read.df("/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", source = "csv", header="true", inferSchema = "true")
dbutils.data.summarize(df)

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. Como 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”.

Utilidade do sistema de arquivos (dbutils.fs)

O sistema de arquivos utilidades permite que o senhor acesse o What is DBFS?, facilitando o uso do Databricks como um sistema de arquivos.

Aviso

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

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

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.fs.help().

Comando

Descrição

copo

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

cabeça

Retorna até os primeiros bytes 'maxBytes' do arquivo fornecido como uma cadeia de caracteres codificada em UTF-8

ls

Lista o conteúdo de um diretório

mkdirs

Cria o diretório fornecido se ele não existir, criando também os diretórios principais necessários

montar

Monta o diretório de origem fornecido no DBFS no ponto de montagem fornecido

monta

Exibe informações sobre o que está montado dentro do DBFS

mv

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

colocar

Grava as cadeias de caracteres fornecidas em um arquivo, codificadas em UTF-8

Montagens de atualização

Força todas as máquinas desse clustering a refresh seu cache de montagem, garantindo que elas recebam as informações mais recentes

braço

Remove um arquivo ou diretório

unmount

Exclui um ponto de montagem DBFS

Montagem da atualização

Semelhante a mount (), mas atualiza um ponto de montagem existente em vez de criar um novo

Dica

No Notebook, o senhor pode usar o comando mágico %fs para acessar DBFS. Por exemplo, %fs ls /Volumes/main/default/my-volume/ é o mesmo que dbutils.fs.ls("/Volumes/main/default/my-volume/"). Ver comando mágico.

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 esse comando, execute:

dbutils.fs.help("cp")

Exemplo

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

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

# Out[4]: True

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

# [1] TRUE

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 strings codificadas em UTF-8.

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

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

# [Truncated to first 25 bytes]
# Out[12]: 'Year,First Name,County,Se'

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

# [1] "Year,First Name,County,Se"

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 esse 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 em Databricks Runtime 10.4 LTS e acima. No R, modificationTime é retornado como uma cadeia de caracteres.

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

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"

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. Cria também quaisquer diretórios pai necessários.

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("mkdirs")

Exemplo

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

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

# Out[15]: True

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

# [1] TRUE

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 esse comando, execute:

dbutils.fs.help("mount")

Exemplo 

aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.mount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

val AwsBucketName = "my-bucket"
val MountName = "s3-my-bucket"

dbutils.fs.mount(s"s3a://$AwsBucketName", s"/mnt/$MountName")

Para obter exemplos de código adicionais, consulte Conectar-se ao Amazon S3.

comando mounts (dbutils.fs.mounts)

mounts: Seq

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

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("mounts")

Exemplo

Aviso

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

dbutils.fs.mounts()

# Out[11]: [MountInfo(mountPoint='/mnt/databricks-results', source='databricks-results', encryptionType='sse-s3')]

dbutils.fs.mounts()

Para obter exemplos de código adicionais, consulte Conectar-se ao Amazon S3.

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 esse 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/.

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

# Out[2]: True

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

# [1] TRUE

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

Escreve a string especificada em um arquivo. A string é codificada em UTF-8.

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("put")

Exemplo

Este exemplo grava a string Hello, Databricks! em um arquivo denominado hello.txt no /Volumes/main/default/my-volume/. Se o arquivo existir, ele será substituído.

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", True)

# Wrote 2258987 bytes.
# Out[6]: True

dbutils.fs.put("/Volumes/main/default/my-volume/hello.txt", "Hello, Databricks!", TRUE)

# [1] TRUE

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 o cache de montagem, garantindo que elas recebam as informações mais recentes.

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("refreshMounts")

Exemplo 

dbutils.fs.refreshMounts()

dbutils.fs.refreshMounts()

Para obter exemplos de código adicionais, consulte Conectar-se ao Amazon S3.

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 parâmetro recurse 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 esse 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.

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

# Out[8]: True

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

# [1] TRUE

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 de DBFS.

Aviso

Para evitar erros, nunca modifique um ponto de montagem enquanto outro Job estiver 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 esse comando, execute:

dbutils.fs.help("unmount")

Exemplo 

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

Para obter exemplos de código adicionais, consulte Conectar-se ao Amazon S3.

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 um novo. Retorna um erro se o ponto de montagem não estiver presente.

Aviso

Para evitar erros, nunca modifique um ponto de montagem enquanto outro Job estiver 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).

Esse comando está disponível em Databricks Runtime 10.4 LTS e acima.

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("updateMount")

Exemplo 

aws_bucket_name = "my-bucket"
mount_name = "s3-my-bucket"

dbutils.fs.updateMount("s3a://%s" % aws_bucket_name, "/mnt/%s" % mount_name)

val AwsBucketName = "my-bucket"
val MountName = "s3-my-bucket"

dbutils.fs.updateMount(s"s3a://$AwsBucketName", s"/mnt/$MountName")

Utilitário de jobs (dbutils.jobs)

Fornece utilidades para aproveitar o recurso Job.

Observação

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

A tabela a seguir lista os módulos disponíveis para esse utilidades, que o senhor pode recuperar usando dbutils.jobs.help().

Submódulo

Descrição

Valores da tarefa

Fornece utilidades para aproveitar os valores da tarefa de trabalho

subutilitário taskValues (dbutils.jobs.taskValues)

Observação

Este subutilitário está disponível somente para o Python.

Fornece comandos para aproveitar os valores das tarefas de jobs.

Use essas subutilidades 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 os valores definidos pela tarefa upstream e definir os valores a serem usados pela tarefa downstream.

Cada valor de tarefa tem um key exclusivo dentro da mesma tarefa. Esse exclusivo key é conhecido como key do valor da tarefa. Um valor de tarefa é acessado com o nome da tarefa e o endereço key do valor da tarefa. O senhor pode usar isso para passar informações downstream de tarefa para tarefa dentro da mesma execução de trabalho. Por exemplo, o senhor pode passar identificadores ou métricas, como informações sobre a avaliação de um modelo do machine learning, entre diferentes tarefas dentro da execução de um trabalho.

A tabela a seguir lista o comando disponível para essa subutilidade, que o senhor pode recuperar usando dbutils.jobs.taskValues.help().

Comando

Descrição

Get

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

conjunto

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

comando get (dbutils.jobs.taskValues.get)

Observação

Este comando está disponível apenas para o Python.

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

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 job atual.

Para exibir a ajuda completa para esse 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, será exibido o endereço ValueError.

  • key é o nome da key do valor da tarefa que você definiu com o comando set (dbutils.Job.taskValues.set). Se o comando não puder localizar key desse valor de tarefa, um ValueError será levantado (a menos que default seja especificado).

  • default é um valor opcional 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 notebook que está sendo executado fora de um job. Isso pode ser útil durante a depuração quando você quiser executar o 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 em um notebook que esteja sendo executado fora de um job, esse comando exibirá um TypeError por padrão. No entanto, se o argumento debugValue for especificado no comando, o valor de debugValue será retornado em vez de gerar um TypeError.

comando set (dbutils.jobs.taskValues.set)

Observação

Este comando está disponível apenas para o Python.

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

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

Para exibir a ajuda completa para esse 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 da tarefa. Ou seja, se duas tarefas diferentes definirem um valor de tarefa com a chave K, esses são dois valores de tarefa diferentes que têm a mesma chave K.

  • value é o valor para a chave desse 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 notebook que está sendo executado fora de um job, esse comando não fará nada.

Utilidades da biblioteca (dbutils.library)

A maioria dos métodos do submódulo dbutils.library está obsoleta. Consulte biblioteca utilidades (dbutils.library) (legado).

Talvez seja necessário reiniciar programaticamente o processo Python no Databricks para garantir que a biblioteca instalada ou atualizada localmente funcione corretamente no kernel Python para sua SparkSession atual. Para fazer isso, execute o comando dbutils.library.restartPython . Consulte Reiniciar o processo Python no Databricks.

Utilitário de notebook (dbutils.notebook)

O utilitário de notebook permite que você encadeie notebooks e atue com base em seus resultados. Consulte Executar um notebook Databricks a partir de outro notebook.

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.notebook.help().

Comando

Descrição

sair

Sai de um Notebook com um valor

Executar

executa um Notebook e retorna seu valor de saída

comando exit (dbutils.notebook.exit)

exit(value: String): void

Sai de um notebook com um valor.

Para exibir a ajuda completa para esse comando, execute:

dbutils.notebook.help("exit")

Exemplo

Este exemplo sai do notebook com o valor Exiting from My Other Notebook.

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

# Notebook exited: Exiting from My Other Notebook

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

# Notebook exited: Exiting from My Other Notebook

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

// Notebook exited: Exiting from My Other Notebook

Observação

Se a execução tiver uma consulta com transmissão estruturada em execução em segundo plano, a chamada para dbutils.notebook.exit() não encerrará a execução. A execução continuará a ser feita enquanto a consulta estiver sendo executada em segundo plano. Você pode interromper a execução da consulta em segundo plano clicando em Cancelar na célula da consulta ou executando query.stop(). Quando a consulta parar, o senhor pode encerrar a execução com dbutils.notebook.exit().

comando run (dbutils.notebook.run)

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

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

Observação

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

Para exibir a ajuda completa para esse comando, execute:

dbutils.notebook.help("run")

Exemplo

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

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

# Out[14]: 'Exiting from My Other Notebook'

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

// res2: String = Exiting from My Other Notebook

Utilitário de segredos (dbutils.secrets)

As utilidades de segredos permitem que o senhor armazene e acesse informações confidenciais de credenciais sem torná-las visíveis no Notebook. Consulte Gerenciamento de segredos e Etapa 3: Use os segredos em um Notebook.

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.secrets.help().

Comando

Descrição

Get

Obtém a representação de strings de um valor secreto com escopo e key

Obter bytes

Obtém a representação em bytes de um valor secreto com escopo e key

Lista

Lista metadados secretos para segredos dentro de um escopo

Listar escopos

Listas Escopo secreto

comando get (dbutils.secrets.get)

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

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

Aviso

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

Para exibir a ajuda completa para esse comando, execute:

dbutils.secrets.help("get")

Exemplo

Este exemplo obtém a representação da string do valor secreto para o escopo chamado my-scope e a chave chamada my-key.

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

# Out[14]: '[REDACTED]'

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

# [1] "[REDACTED]"

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 chave especificados.

Para exibir a ajuda completa para esse comando, execute:

dbutils.secrets.help("getBytes")

Exemplo

Este exemplo obtém a representação em bytes do valor secreto (neste exemplo, a1!b2@c3#) para o escopo denominado my-scope e a chave denominada my-key.

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

# Out[1]: b'a1!b2@c3#'

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

# [1] 61 31 21 62 32 40 63 33 23

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 esse comando, execute:

dbutils.secrets.help("list")

Exemplo

Este exemplo lista os metadados para segredos dentro do escopo denominado my-scope.

dbutils.secrets.list("my-scope")

# Out[10]: [SecretMetadata(key='my-key')]

dbutils.secrets.list("my-scope")

# [[1]]
# [[1]]$key
# [1] "my-key"

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 esse comando, execute:

dbutils.secrets.help("listScopes")

Exemplo

Este exemplo lista os escopos disponíveis.

dbutils.secrets.listScopes()

# Out[14]: [SecretScope(name='my-scope')]

dbutils.secrets.listScopes()

# [[1]]
# [[1]]$name
# [1] "my-scope"

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 a você parameterizar notebooks. Consulte Widgets Databricks.

A tabela a seguir lista o comando disponível para essas utilidades, que o senhor pode recuperar usando dbutils.widgets.help().

Comando

Descrição

caixa de combinação

Cria um widget de entrada combobox com um determinado nome, valor default e opções

dropdown

Cria um widget de entrada dropdown a com o nome, o valor default e as opções fornecidos

Get

Recupera o valor atual de um widget de entrada

Obtenha tudo

Recupera um mapa de todos os nomes de widgets e seus valores

Obter argumento

Obsoleto. Equivalente a obter

seleção múltipla

Cria um widget de entrada multisseleção com um determinado nome, valor default e opções

remover

Remove um widget de entrada do Notebook

Remover tudo

Remove todos os widgets do Notebook

TEXT

Cria um widget de entrada de texto com um determinado nome e o valor default

comando combobox (dbutils.widgets.combobox)

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

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

Para exibir a ajuda completa para esse comando, execute:

dbutils.widgets.help("combobox")

Exemplo

Este exemplo cria e exibe um widget combobox com o nome programático fruits_combobox. Ele oferece as opções applebanana, coconut, dragon fruit e é definido com o valor inicial de banana. Este widget combobox tem um rótulo anexo. Fruits Este exemplo termina imprimindo o valor inicial do widget combobox, banana.

dbutils.widgets.combobox(
  name='fruits_combobox',
  defaultValue='banana',
  choices=['apple', 'banana', 'coconut', 'dragon fruit'],
  label='Fruits'
)

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

# banana

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"

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

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

// banana

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

SELECT :fruits_combobox

-- banana

comando get (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 Notebook, por exemplo, fruits_combobox ou toys_dropdown.

  • O nome de um parâmetro personalizado passado para o Notebook como parte de uma tarefa do Notebook, por exemplo, name ou age. Para obter mais informações, consulte a cobertura dos parâmetros para a tarefa do Notebook na interface do usuário do Job ou o campo notebook_params nas operações Trigger a new Job execution (POST /jobs/run-now) no Jobs API.

Para exibir a ajuda completa para esse comando, execute:

dbutils.widgets.help("get")

Exemplo

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

dbutils.widgets.get('fruits_combobox')

# banana

dbutils.widgets.get('fruits_combobox')

# [1] "banana"

dbutils.widgets.get("fruits_combobox")

// res6: String = banana

SELECT :fruits_combobox

-- banana

Este exemplo obtém o valor do parâmetro da tarefa do notebook que tem o nome programático age. Este parâmetro foi configurado para 35 quando a tarefa do notebook relacionada foi executada.

dbutils.widgets.get('age')

# 35

dbutils.widgets.get('age')

# [1] "35"

dbutils.widgets.get("age")

// res6: String = 35

SELECT :age

-- 35

comando getAll (dbutils.widgets.getAll)

getAll: map

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

Esse comando está disponível em Databricks Runtime 13.3 LTS e acima. Ele só está disponível para Python e Scala.

Para exibir a ajuda completa para esse 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 Spark SQL.

df = spark.sql("SELECT * FROM table where col1 = :param", dbutils.widgets.getAll())
df.show()

# Query output

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.

Observação

Este comando está obsoleto. Em vez disso, use dbutils.widgets.get .

Para exibir a ajuda completa para esse comando, execute:

dbutils.widgets.help("getArgument")

Exemplo

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

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'

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"

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 esse comando, execute:

dbutils.widgets.help("multiselect")

Exemplo

Este exemplo cria e exibe um widget de seleção múltipla com o nome programático days_multiselect. Ele oferece as opções Monday a Sunday e é definido com o valor inicial de Tuesday. Este widget de seleção múltipla possui um rótulo Days of the Week. Este exemplo termina imprimindo o valor inicial do widget de seleção múltipla, Tuesday.

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

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"

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

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 esse 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 programático fruits_combobox.

dbutils.widgets.remove('fruits_combobox')

dbutils.widgets.remove('fruits_combobox')

dbutils.widgets.remove("fruits_combobox")

REMOVE WIDGET fruits_combobox

comando removeAll (dbutils.widgets.removeAll)

removeAll: void

Remove todos os widgets do notebook.

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

Exemplo

Este exemplo remove todos os widgets do notebook.

dbutils.widgets.removeAll()

dbutils.widgets.removeAll()

dbutils.widgets.removeAll()

comando text (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 esse comando, execute:

dbutils.widgets.help("text")

Exemplo

Este exemplo cria e exibe um widget de texto com o nome programático your_name_text. É definido com o valor inicial de Enter your name. Este widget de texto possui um rótulo Your name. Este exemplo termina imprimindo o valor inicial do widget de texto, Enter your name.

dbutils.widgets.text(
  name='your_name_text',
  defaultValue='Enter your name',
  label='Your name'
)

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

# Enter your name

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"

dbutils.widgets.text(
  "your_name_text",
  "Enter your name",
  "Your name"
)

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

// Enter your name

CREATE WIDGET TEXT your_name_text DEFAULT "Enter your name"

SELECT :your_name_text

-- Enter your name

Biblioteca de APIs de utilitários do Databricks

Importante

A biblioteca Databricks utilidades API (dbutils-api) está obsoleta. Databricks recomenda que o senhor use uma das seguintes bibliotecas:

Para acelerar o desenvolvimento de aplicativos, pode ser útil compilar, criar e testar aplicativos antes de implantá-los como jobs de produção. Para que você possa compilar em relação aos utilitários do Databricks, o Databricks fornece a biblioteca dbutils-api. Você pode fazer o download da biblioteca dbutils-api na página da web 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 alvos e versões disponíveis, consulte a página da Web do DBUtils API no site do repositório Maven.

Depois de criar seu aplicativo com base nessa biblioteca, você pode implantar o aplicativo.

Importante

A biblioteca dbutils-api permite apenas que o senhor compile localmente um aplicativo que use o dbutils, não que o execute. Para executar o aplicativo, o senhor deve implantá-lo em Databricks.

Limitações

Chamar dbutils dentro de um executor pode produzir resultados inesperados ou erros.

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

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