Desenvolver código em notebooks Databricks

Esta página descreve como desenvolver código no Databricks Notebook, incluindo preenchimento automático, formatação automática para Python e SQL, combinação de Python e SQL em um Notebook e acompanhamento da versão Notebook história.

Para obter mais detalhes sobre funcionalidades avançadas disponíveis no editor, como autocompletar, seleção de variáveis, suporte a múltiplos cursores e comparações lado a lado, consulte Usar o bloco de anotações e o editor de arquivos Databricks.

Quando o senhor usa o site Notebook ou o editor de arquivos, o Databricks Assistant está disponível para ajudá-lo a gerar, explicar e depurar o código. Consulte Usar o Databricks Assistant para obter mais informações.

O Databricks Notebook também inclui um depurador interativo integrado para o Python Notebook. Consulte Usar o depurador interativo do Databricks.

Obtenha ajuda de codificação do Databricks Assistant

O Databricks Assistant é um assistente de IA com reconhecimento de contexto com o qual o senhor pode interagir usando uma interface de conversação, tornando-o mais produtivo dentro da Databricks. O senhor pode descrever sua tarefa em inglês e deixar que o assistente gere código Python ou consultas SQL, explique códigos complexos e corrija erros automaticamente. O assistente usa os metadados do Unity Catalog para entender suas tabelas, colunas, descrições e dados populares ativos em sua empresa para fornecer respostas personalizadas.

O Databricks Assistant pode ajudar o senhor com as seguintes tarefas:

Gerar código.
Depurar código, inclusive identificando e sugerindo correções para erros.
Transformar e otimizar o código.
Explicar o código.
Ajudar o senhor a encontrar informações relevantes na documentação da Databricks.

Para obter informações sobre como usar o Databricks Assistant para ajudá-lo a codificar com mais eficiência, consulte Usar o Databricks Assistant. Para obter informações gerais sobre o Databricks Assistant, consulte Recurso alimentado pelo DatabricksIQ.

Acesse o notebook para edição

Para abrir um notebook, use a função Search do workspace ou use o navegador do workspace para navegar até o notebook e clique no nome ou ícone do notebook.

Navegue pelos dados

Use o navegador de esquema para explorar tabelas e volumes disponíveis para o Notebook. Clique no lado esquerdo do Notebook para abrir o navegador de esquema.

O botão For you (Para você) exibe apenas as tabelas que você usou na sessão atual ou que marcou anteriormente como Favorite (Favorita).

Conforme você digita texto na caixa Filtro , a exibição muda para mostrar apenas os itens que contêm o texto digitado. Somente os itens que estão abertos no momento ou que foram abertos na sessão atual são exibidos. A caixa Filtro não faz uma pesquisa completa dos catálogos, esquemas e tabelas disponíveis para o notebook.

Para abrir o menu kebab, passe o cursor sobre o nome do item como mostrado:

Se o item for uma tabela, você pode fazer o seguinte:

Crie automaticamente e execute uma célula para exibir uma prévia dos dados na tabela. Selecione Visualizar em uma nova célula no menu kebab da tabela.
view um catálogo, esquema ou tabela no Catalog Explorer. Selecione Abrir no Catalog Explorer no menu kebab. Uma nova tab é aberta mostrando o item selecionado.
Obtenha o caminho para um catálogo, esquema ou tabela. Selecione Copiar… caminho no menu kebab do item.
Adicione uma tabela aos Favoritos. Selecione Adicionar mesa aos favoritos no menu kebab da mesa.

Se o item for um catálogo, esquema ou volume, você poderá copiar o caminho do item ou abri-lo no Catalog Explorer.

Para inserir um nome de tabela ou coluna diretamente em uma célula:

Clique com o cursor na célula no local em que deseja inserir o nome.
Mova o cursor sobre o nome da tabela ou da coluna no navegador de esquemas.
Clique na seta dupla que aparece à direita do nome do item.

Atalhos de teclado

Para exibir atalhos de teclado, selecione Ajuda > Atalhos de teclado. Os atalhos de teclado disponíveis dependem de se o cursor está em uma célula de código (modo de edição) ou não (modo de comando).

Localizar e substituir texto

Para localizar e substituir texto em um notebook, selecione Edit > Find and Replace. A partida atual é destacada em laranja e todas as outras partidas são destacadas em amarelo.

Para substituir a correspondência atual, clique em Substituir. Para substituir todas as correspondências no notebook, clique em Substituir Tudo.

Para alternar entre correspondências, clique nos botões Anterior e Avançar. Você também pode pressionar shift+enter e enter para ir para as partidas anteriores e seguintes, respectivamente.

Para fechar a ferramenta localizar e substituir, clique em ou pressione esc.

Explorador variável

O senhor pode observar diretamente as variáveis Python, Scala e R na UI Notebook. Para Python em Databricks Runtime 12.2 LTS e acima, as variáveis são atualizadas como uma execução de célula. Para Scala, R e Python no Databricks Runtime 11.3 LTS e abaixo, as variáveis são atualizadas após o término da execução de uma célula.

Para abrir o explorador de variáveis, clique em na barra lateral direita. O explorador de variáveis é aberto, mostrando o valor e o tipo de dados, incluindo a forma, para cada variável atualmente definida no Notebook. (A forma de um quadro de dados PySpark é '?', porque o cálculo da forma pode ser computacionalmente caro.)

Para filtrar a exibição, digite o texto na caixa de pesquisa. A lista é filtrada automaticamente à medida que o senhor digita.

Os valores das variáveis são atualizados automaticamente à medida que você executa as células do notebook.

exemplo de painel do explorador de variáveis

execução de células selecionadas

Você pode executar uma única célula ou uma coleção de células. Para selecionar uma única célula, clique em qualquer lugar da célula. Para selecionar várias células, mantenha pressionada a key Command no MacOS ou a key Ctrl no Windows e clique na célula fora da área de texto, conforme mostrado na captura de tela.

Para executar as células selecionadas, selecione execução > execução célula(s) selecionada(s).

O comportamento deste comando depende dos clusters aos quais o Notebook está conectado.

Em clusters que executam o Databricks Runtime 13.3 LTS ou abaixo, as células selecionadas são executadas individualmente. Se ocorrer um erro em uma célula, a execução continua nas células subsequentes.
Em clusters que executam o Databricks Runtime 14.0 ou acima, ou em um SQL warehouse, as células selecionadas são executadas como lotes. Qualquer erro interrompe a execução e você não pode cancelar a execução de células individuais. Você pode usar o botão Interromper para interromper a execução de todas as células.

Modularize seu código

Visualização

Esse recurso está em visualização pública.

Com o Databricks Runtime 11.3 LTS e o acima, o senhor pode criar e gerenciar arquivos de código-fonte no Databricks workspace e, em seguida, importar esses arquivos para o Notebook, conforme necessário.

Para obter mais informações sobre como trabalhar com arquivos de código fonte, consulte Compartilhar código entre cadernos de dados e Trabalhar com módulos Python e R.

Executar texto selecionado

Você pode destacar código ou instruções SQL em uma célula do notebook e executar somente essa seleção. Isso é útil quando você deseja iterar rapidamente códigos e consultas.

Destaque as linhas que você deseja executar.
Selecione Executar > Executar o texto selecionado ou use o atalho de teclado Ctrl+Shift+Enter. Se nenhum texto estiver destacado, Executar texto selecionado executa a linha atual.

Se você estiver usando idiomas mistos em uma célula, deverá incluir a linha %<language> na seleção.

Executar o texto selecionado também executa o código recolhido, se houver algum na seleção destacada.

Comandos de célula especiais como %run, %pip e %sh são suportados.

Não é possível usar Executar texto selecionado em células que tenham várias guias de saída (ou seja, células nas quais você definiu um perfil de dados ou visualização).

Formatar células de código

O Databricks fornece ferramentas que permitem formatar código Python e SQL em células de bloco de anotações de forma rápida e fácil. Essas ferramentas reduzem o esforço necessário para manter o formato do seu código e auxiliam na aplicação das mesmas normas de codificação em seus notebooks.

Formatar células Python

Visualização

Esse recurso está em visualização pública.

O Databricks oferece suporte à formatação de código Python usando o Black dentro do notebook. O notebook deve ser anexado a um cluster com os pacotes Python black e tokenize-rt e o formatador Black é executado no cluster ao qual o notebook está conectado.

Em Databricks Runtime 11.3 LTS e acima, Databricks pré-instala black e tokenize-rt. O senhor pode usar o formatador diretamente sem precisar instalar essas bibliotecas.

Em Databricks Runtime 10.4 LTS e abaixo, o senhor deve instalar black==22.3.0 e tokenize-rt==4.2.1 de PyPI em seu Notebook ou cluster para usar o formatador Python. O senhor pode executar o seguinte comando em seu Notebook:

%pip install black==22.3.0 tokenize-rt==4.2.1

ou instalar a biblioteca em seu cluster.

Para obter mais detalhes sobre a instalação de bibliotecas, consulte gerenciamento de ambiente Python.

Para arquivos e Notebook nas pastas Git do Databricks, o senhor pode configurar o formatador Python com base no arquivo pyproject.toml. Para usar esse recurso, crie um arquivo pyproject.toml no diretório raiz da pasta Git e configure-o de acordo com o formato de configuração do Black. Edite o [tool.black]. no arquivo. A configuração é aplicada quando o senhor formata qualquer arquivo e Notebook nessa pasta Git.

Como formatar células Python e SQL

O senhor deve ter permissão CAN EDIT no site Notebook para formatar o código.

Você pode ativar o formatador das seguintes maneiras:

Formatar uma única célula
- Atalho de teclado: pressione Cmd+Shift+F.
- Menu de contexto do comando:
  - Formatar célula SQL: Selecione Formatar SQL no menu dropdown de contexto de comando de uma célula SQL. Este item de menu é visível apenas nas células do SQL Notebook ou naquelas com %sql language magic.
  - Formatar célula Python: selecione Formatar Python no menu dropdown de contexto de comando de uma célula Python. Este item de menu é visível apenas nas células do Python Notebook ou naquelas com %python language magic.
- Menu Editar do Notebook: selecione uma célula Python ou SQL e selecione Editar > Formatar célula(s).
Formatar múltiplas células

Selecione várias células e selecione Editar > Formatar célula(s). Se você selecionar células de mais de um idioma, somente as células SQL e Python serão formatadas. Isso inclui aqueles que usam %sql e %python.
Formate todas as células Python e SQL no notebook

Selecione Editar > Formatar notebook. Se o seu notebook tiver mais de uma linguagem, somente as células SQL e Python serão formatadas. Isto inclui aqueles que utilizam %sql e %python.

Limitações da formatação de código

A Black aplica os padrões PEP 8 para a indentação de 4 espaços A indentação não é configurável.
Não há suporte para a formatação de strings Python incorporadas em um UDF SQL. Da mesma forma, a formatação de strings do SQL dentro de uma UDF Python não tem suporte.

Histórico de versões

Os notebooks Databricks mantêm um histórico das versões do notebook, permitindo que você visualize e restaure instantâneos anteriores do notebook. Você pode realizar as seguintes ações nas versões: adicionar comentários, restaurar e excluir versões e limpar o histórico de versões.

Você também pode sincronizar seu trabalho no Databricks com um repositório Git remoto.

Para acessar as versões Notebook , clique em versão história ícone na barra lateral direita. A versão Notebook história aparece. Você também pode selecionar Arquivo > Versão história.

Adicionar um comentário

Para adicionar um comentário à versão mais recente:

Clique na versão.
Clique em Salvar agora.
Na caixa de diálogo Salvar versão Notebook , insira um comentário.
Clique em Salvar. A versão do notebook é salva com o comentário inserido.

Restaurar uma versão

Para restaurar uma versão:

Clique na versão.
Clique em Restaurar esta versão.
Clique em Confirmar. A versão selecionada torna-se a versão mais recente do bloco de anotações.

Excluir uma versão

Para excluir uma entrada de versão:

Clique na versão.
Clique no ícone da lixeira .
Clique em "Sim, apagar". A versão selecionada é excluída do histórico.

Apagar o histórico de versões

Uma vez que tenha sido apagado, o histórico de versões não pode ser recuperado.

Para apagar o histórico de versões de um notebook:

Selecione "Arquivo > Apagar histórico de versões".
Clique em "Sim, apagar. O histórico de versões do notebook está apagado.

Idiomas do código em notebooks

Definir idioma padrão

O idioma padrão do notebook aparece próximo do nome do notebook.

Para alterar o idioma padrão, clique no botão "Idioma" e selecione o novo idioma no dropdown. Para garantir que os comandos existentes continuem funcionando, os comandos do idioma padrão anterior são automaticamente prefixados com um comando mágico de idioma.

Misture idiomas

Por padrão, as células utilizam o idioma padrão do notebook. Você pode substituir o idioma padrão em uma célula clicando no botão "Idioma" e selecionando um idioma no dropdown.

De forma alternativa, você pode utilizar o comando mágico de idioma %<language> no início de uma célula. Os seguintes comandos mágicos estão disponíveis: %python, %r, %scala e %sql.

Observação

Quando você usa um comando mágico de idioma, o comando é enviado para o REPL no contexto de execução para o notebook. As variáveis definidas em um idioma (e, portanto, no REPL desse idioma) não estão disponíveis no REPL de outro idioma. Os REPLs podem compartilhar seu estado por meio de recursos externos, tais como arquivos em DBFS ou objetos em sistemas de armazenamento de objeto.

Os notebooks também fornecem suporte para alguns comandos mágicos auxiliares:

%sh: permite executar código shell em seu notebook. Para falhar na célula se o comando shell tiver um status de saída diferente de zero, adicione a opção -e. Este comando é executado somente no driver Apache Spark e não nos workers. Para executar um comando shell em todos os nós, use um script de inicialização.
%fs: permite que você use o comando do sistema de arquivos dbutils . Por exemplo, para executar o comando dbutils.fs.ls para listar arquivos, você pode especificar %fs ls . Para obter mais informações, consulte Trabalhar com arquivos no Databricks.
%md: Permite incluir vários tipos de documentação, incluindo texto, imagens e fórmulas e equações matemáticas. Veja a próxima seção.

Destaque de sintaxe do SQL e preenchimento automático em comandos Python

O realce de sintaxe e o preenchimento automático de SQL estão disponíveis quando você usa SQL dentro de um comando Python, como em um comando spark.sql .

Explore os resultados de células SQL em notebooks Python usando Python

É possível que você queira carregar dados usando SQL e explorá-los com Python.Em um notebook Python Databricks, os resultados da tabela de uma célula de idioma SQL são disponibilizados automaticamente como um DataFrame do Python atribuído à variável _sqldf.

Em Databricks Runtime 13.3 LTS e acima, o senhor também pode acessar o resultado de DataFrame usando o sistema de cache de saída do IPython. O contador do prompt aparece na mensagem de saída exibida na parte inferior dos resultados da célula. No exemplo mostrado, o senhor faria referência ao resultado como Out[2].

Observação

A variável _sqldf pode ser redesignada sempre que uma célula %sql é executada. Para evitar perder a referência ao resultado do DataFrame, faça a atribuição a um novo nome de variável antes de executar a próxima célula %sql:
```
new_dataframe_name = _sqldf
```
Se a consulta usar um widget para parametrização, os resultados não estarão disponíveis como um DataFrame em Python.
Se a consulta utilizar as palavras-chave CACHE TABLE ou UNCACHE TABLE, os resultados não estarão disponíveis como um DataFrame em Python.

A captura de tela mostra um exemplo:

Executar células SQL em paralelo

Enquanto um comando estiver em execução e o notebook estiver conectado a um cluster interativo, você pode executar uma célula SQL simultaneamente com o comando atual. A célula SQL é executada em uma nova sessão paralela.

Para executar uma célula em paralelo:

Execute a célula.
Clique em "Executar agora". A célula é executada imediatamente.

Como a célula é executada em uma nova sessão, view temporária, UDFs e o DataFrame implícito do Python (_sqldf) não são suportados para células executadas em paralelo. Além disso, os nomes default do catálogo e do banco de dados são usados durante a execução paralela. Se o seu código se referir a uma tabela em um catálogo ou banco de dados diferente, você deverá especificar o nome da tabela usando o namespace de três níveis (catalog.schema.table).

Exibir imagens

Para exibir as imagens armazenadas no FileStore, use a sintaxe:

%md
![test](files/image.png)

Por exemplo, suponha que você tenha o arquivo de imagem do logotipo Databricks no FileStore:

dbfs ls dbfs:/FileStore/

databricks-logo-mobile.png

Quando você inclui o seguinte código em uma célula Markdown:

a imagem é renderizada na célula:

Exibir equações matemáticas

Os notebooks tem suporte KaTeX para exibir fórmulas e equações matemáticas. Por exemplo,

%md
\\(c = \\pm\\sqrt{a^2 + b^2} \\)

\\(A{_i}{_j}=B{_i}{_j}\\)

$$c = \\pm\\sqrt{a^2 + b^2}$$

\\[A{_i}{_j}=B{_i}{_j}\\]

é exibido como:

e

%md
\\( f(\beta)= -Y_t^T X_t \beta + \sum log( 1+{e}^{X_t\bullet\beta}) + \frac{1}{2}\delta^t S_t^{-1}\delta\\)

where \\(\delta=(\beta - \mu_{t-1})\\)

é exibido como:

Incluir HTML

Você pode incluir HTML em um notebook utilizando a função displayHTML. Consulte HTML, D3 e SVG em notebooks para obter um exemplo de como fazer isso.

Observação

O iframe do displayHTML é proveniente do domínio databricksusercontent.com e o sandbox do iframe inclui o atributo allow-same-origin. databricksusercontent.com tem de estar acessível a partir do seu navegador. Se ele estiver atualmente bloqueado pela sua rede corporativa, ele deverá ser adicionado a uma lista de permissões.

Link para outros notebooks

Você pode vincular a outros notebooks ou pastas nas células do Markdown usando caminhos relativos. Especifique o atributo href de uma tag de âncora como o caminho relativo, começando com $ e, em seguida, siga o mesmo padrão dos sistemas de arquivos Unix:

%md
<a href="$./myNotebook">Link to notebook in same folder as current notebook</a>
<a href="$../myFolder">Link to folder in parent folder of current notebook</a>
<a href="$./myFolder2/myNotebook2">Link to nested notebook</a>