Pular para o conteúdo principal

Databricks utilidades (dbutils) referência

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.

nota

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()
Output
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")
Output
/**
* 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

Utilidades de credenciais (dbutils.credentials)​

Os utilitários de credenciais permitem que o senhor interaja com as credenciais no Notebook. Esse utilitário só pode ser usado em clusters com a passagem de credenciais ativada.

A tabela a seguir lista os comandos disponíveis 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​

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

# Out[1]: True

showCurrentRole comando (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​

Python
dbutils.credentials.showCurrentRole()

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

showRoles comando (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​

Python
dbutils.credentials.showRoles()

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

Utilidades de dados (dbutils.data)​

info

Visualização

Esse recurso está em Public Preview.

nota

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 os comandos disponíveis 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)​

nota

Esse recurso está em Public Preview.

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.

important

Esse comando analisa o conteúdo completo do DataFrame. A execução desse comando em DataFrames muito grandes pode ser muito cara.

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 Apache Spark DataFrame com aproximações habilitadas por default. Para ver os resultados do , execute esse comando em um Notebook. Este exemplo é baseado no conjunto de dados Sample.

Python
df = spark.read.format('csv').load(
  '/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv',
  header=True,
  inferSchema=True
)
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”.

Utilidades do sistema de arquivos (dbutils.fs)​

O sistema de arquivos utilidades permite que o senhor acesse o que é DBFS? Para acessar os arquivosworkspace, use o comando shell, como %sh ls, pois há algumas limitações ao usar o comando dbutils.fs com os arquivos workspace.

atenção

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 os comandos disponíveis 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 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.

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

# Out[4]: 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 cadeias de caracteres 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/.

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

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

ls comando (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 do site /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.

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

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 em /Volumes/main/default/my-volume/.

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

# Out[15]: 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​

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

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

Para obter exemplos de código adicionais, consulte Conectar 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​

atenção

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

Python
dbutils.fs.mounts()

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

Para obter exemplos de código adicionais, consulte Conectar 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/.

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

# Out[2]: 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.

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

# Wrote 2258987 bytes.
# Out[6]: 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​

Python
dbutils.fs.refreshMounts()

Para obter exemplos de código adicionais, consulte Conectar 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.

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

# Out[8]: True

comando unmount (dbutils.fs.unmount)​

unmount(mountPoint: String): boolean

Exclui um ponto de montagem de DBFS.

atenção

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

Para exibir a ajuda completa para esse comando, execute:

dbutils.fs.help("unmount")

Exemplo​

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

Para obter exemplos de código adicionais, consulte Conectar 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.

atenção

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

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

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

Utilidades do Jobs (dbutils.Job)​

Fornece utilidades para aproveitar o recurso Job.

nota

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

taskValues subutility (dbutils.Job.taskValues)​

nota

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

get comando (dbutils.Job.taskValues.get)​

nota

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

No Databricks Runtime 10.4 e versões anteriores, se o site get não conseguir 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:

Python
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 um ValueError.
  • key é o nome do valor da tarefa key que o senhor definiu com o comando set (dbutils.Job.taskValues.set). Se o comando não conseguir encontrar esse valor de tarefa key, será gerado um ValueError (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.

set comando (dbutils.Job.taskValues.set)​

nota

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:

Python
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.biblioteca)​

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

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

Notebook utilidades (dbutils.Notebook)​

As utilidades do Notebook permitem que o senhor encadeie o Notebook e atue com base em seus resultados. Consulte Orchestrate Notebook e modularize o código no Notebook.

A tabela a seguir lista os comandos disponíveis 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

sair do comando (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.

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

# Notebook exited: Exiting from My Other Notebook
nota

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

execução comando (dbutils.Notebook.execução)​

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.

nota

O comprimento máximo do valor das cadeias de caracteres retornado pelo comando run é de 5 MB. Consulte Obter a saída de 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.

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

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

Utilidades secretas (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 os comandos disponíveis 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.

atenção

Os administradores, criadores de segredos e usuários com permissão podem ler os segredos do Databricks. Embora o site Databricks faça um esforço para redigir valores secretos que possam ser exibidos no Notebook, não é possível impedir que esses usuários leiam os segredos. Para obter 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.

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

# Out[14]: '[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.

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

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

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.

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

# Out[10]: [SecretMetadata(key='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.

Python
dbutils.secrets.listScopes()

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

Utilidades dos widgets (dbutils.widgets)​

Os widgets utilidades permitem que o senhor parametrize o Notebook. Consulte Widgets do Databricks.

A tabela a seguir lista os comandos disponíveis 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 apple``banana, 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.

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

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

# banana

comando dropdown (dbutils.widgets.dropdown)​

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

Cria e exibe um widget dropdown 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("dropdown")

Exemplo​

Este exemplo cria e exibe um widget dropdown com o nome programático toys_dropdown. Ele oferece as opções alphabet blocks``basketball, cape, doll e é definido com o valor inicial de basketball. Esse widget dropdown tem um rótulo anexo. Toys Este exemplo termina imprimindo o valor inicial do widget dropdown, 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

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 da tarefa do Notebook na UI 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.

Python
dbutils.widgets.get('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.

Python
dbutils.widgets.get('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 os valores do 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.

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

# 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.

nota

Esse 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.

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'

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.

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

comando de remoção (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")
important

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.

Python
dbutils.widgets.remove('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")
important

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.

Python
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 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.

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

Databricks utilidades biblioteca API​

important

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

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

    Scala
    libraryDependencies += "com.databricks" % "dbutils-api_TARGET" % "VERSION"

  • Maven

    XML
    <dependency>
        <groupId>com.databricks</groupId>
        <artifactId>dbutils-api_TARGET</artifactId>
        <version>VERSION</version>
    </dependency>

  • Gradle

    Bash
    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 das metas e versões disponíveis, consulte a página da Web da API do DBUtils no site do Repositório Maven.

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

important

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 Paralelizar operações do sistema de arquivos.

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

Última atualização em