Desenvolver código em notebooks do Databricks

Esta página descreve como desenvolver código em blocos de anotações do Databricks, incluindo formatação de código, preenchimento automático, idiomas de combinação e comandos mágicos.

Para obter mais detalhes sobre a funcionalidade avançada disponível com o editor, como preenchimento automático, seleção de variável, suporte a vários cursores e diferenças lado a lado, confira Navegar pelo notebook e editor de arquivos do Databricks.

Quando você usa o notebook ou o editor de arquivos, o Genie Code está disponível para ajudá-lo a gerar, explicar e depurar código. Consulte Usar o Genie Code para obter mais informações.

Os notebooks do Databricks também incluem um depurador interativo interno para notebooks Python. Confira Notebooks de depuração.

Importante

O notebook deve ser anexado a uma sessão ativa de computação para recursos de assistência de código, incluindo preenchimento automático, formatação de código Python e o depurador.

Modularizar seu código

Com o Databricks Runtime 11.3 LTS e posteriores, você pode criar e gerenciar arquivos de código-fonte no workspace Azure Databricks e importar esses arquivos para seus notebooks conforme necessário.

Para obter mais informações sobre como trabalhar com arquivos de código-fonte, consulte Compartilhar código entre blocos de anotações do Databricks e Trabalhe com módulos Python e R.

Formatar células de código

Azure Databricks fornece ferramentas que permitem formatar Python e código SQL em células de notebook. Essas ferramentas reduzem o esforço para manter seu código formatado e ajudam a impor os mesmos padrões de codificação em seus notebooks.

biblioteca de formatadores pretos Python

Importante

Esse recurso está em uma versão prévia.

Azure Databricks dá suporte à formatação de código Python usando black no notebook. O notebook deve ser anexado a um cluster com pacotes black e tokenize-rt Python instalados.

No Databricks Runtime 11.3 LTS e posteriores, Azure Databricks pré-instala black e tokenize-rt. Você pode usar o formatador diretamente, sem a necessidade de instalar essas bibliotecas.

No Databricks Runtime 10.4 LTS e abaixo, você deve instalar black==22.3.0 e tokenize-rt==4.2.1 do PyPI em seu notebook ou cluster para usar o formatador Python. Execute o comando a seguir no seu notebook:

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

ou instale a biblioteca em seu cluster.

Para obter mais detalhes sobre como instalar bibliotecas, consulte Python gerenciamento de ambiente.

Para arquivos e notebooks em pastas Git do Databricks, você pode configurar o formatador do 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 Black. Edite a seção [tool.black] no arquivo. A configuração é aplicada quando você formata qualquer arquivo e bloco de anotações nessa pasta Git.

Como formatar células Python e SQL

Você precisa ter a permissão CAN EDIT no notebook para formatar código.

Azure Databricks usa um formatador SQL personalizado para formatar o SQL e o black formatador de código para Python.

Você pode disparar o formatador das seguintes maneiras:

• Formatar uma única célula

  • Atalho de teclado: pressione CMD+SHIFT+F.
  • Menu de contexto de comando:
    • Formatar célula SQL: selecione Formatar SQL no menu suspenso de contexto de comando de uma célula SQL. Esse item de menu é visível somente em células SQL de notebook e aquelas com um %sqlmagic de linguagem.
    • Formatar célula Python: selecione Format Python no menu suspenso de contexto de comando da célula Python. Este item de menu é visível apenas em células de bloco de anotações Python ou aquelas com um %pythonlanguage magic.
  • Menu Edit: selecione uma célula Python ou SQL e, em seguida, selecione Edit > Formatar Célula(s).

• Formatar várias células

  Selecione várias células e, em seguida, selecione Editar > Formatar Células. Se você selecionar células de mais de um idioma, apenas as células de SQL e Python serão formatadas. Isso inclui aquelas que usam %sql e %python.

• Formar todas as células Python e SQL no notebook

  Selecione >. Se o caderno contiver mais de um idioma, somente as células de linguagens SQL e Python serão formatadas. Isso inclui aquelas que usam %sql e %python.

Para personalizar como as consultas SQL são formatadas, consulte instruções SQL de formato personalizado.

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

• Black implementa os padrões PEP 8 para um recuo de 4 espaços. O recuo não é configurável.
• Não há suporte para formatação de cadeias de caracteres de Python inseridas dentro de um UDF do SQL. Da mesma forma, não há suporte para formatação de cadeias de caracteres SQL dentro de um Python UDF.

Idiomas de código em notebooks

Definir como idioma padrão

O idioma padrão do bloco de anotações aparece abaixo do nome do bloco de anotações.

Para alterar o idioma padrão, clique no botão de idioma e selecione o novo idioma na lista suspensa. Para garantir o funcionamento dos comandos existentes, os comandos do idioma padrão anterior são prefixados automaticamente com um comando mágico de idioma.

Misturar idiomas

Por padrão, as células usam o idioma padrão do notebook. Você pode substituir o idioma padrão de uma célula clicando no botão de idioma e escolhendo um idioma na lista suspensa.

Como alternativa, no início de uma célula, você pode usar o comando mágico de linguagem %<language>. Os comandos magic com suporte são: %python, %r, %scala e %sql.

Observação

Quando você invoca um comando mágico de linguagem, o comando é enviado para o REPL no contexto de execução do notebook. As variáveis definidas em um idioma (e, portanto, no REPL para esse idioma) não estão disponíveis no REPL de outro idioma. As REPLs podem compartilhar status somente por meio de recursos externos, como arquivos em DBFS ou objetos no armazenamento de objetos.

Os notebooks também dão suporte a alguns comandos mágicos auxiliares:

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

Realce da sintaxe SQL e preenchimento automático para comandos Python

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

Explorar resultados da célula SQL

Em um notebook do Databricks, os resultados de uma célula de linguagem SQL são disponibilizados automaticamente como um DataFrame implícito atribuído à variável _sqldf. Em seguida, você pode usar essa variável em qualquer célula de Python ou SQL que você executar posteriormente, independentemente de sua posição no notebook.

Observação

Este recurso tem as seguintes limitações:

• A variável _sqldf não está disponível em notebooks que usam um SQL warehouse para a computação.
• O uso de _sqldf em células subsequentes do Python tem suporte no Databricks Runtime 13.3 ou versões superiores.
• O uso _sqldf em células SQL subsequentes só tem suporte no Databricks Runtime 14.3 e superior.
• Se a consulta usar as palavras-chave CACHE TABLE ou UNCACHE TABLE, a _sqldf variável não estará disponível.

A captura de tela abaixo mostra como _sqldf podem ser usados em células SQL e Python seguintes:

Importante

A variável _sqldf é reatribuída cada vez que uma célula SQL é executada. Para evitar a perda de referência a um resultado DataFrame específico, atribua-o a um novo nome de variável antes de executar a próxima célula SQL:

Python

new_dataframe_name = _sqldf

SQL

ALTER VIEW _sqldf RENAME TO new_dataframe_name

Executar células SQL em paralelo

Enquanto um comando estiver em execução e o notebook estiver anexado a um cluster interativo, você poderá 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:

1. Executar a célula.

2. Clique em Executar agora. A célula é executada imediatamente.

   

Como a célula é executada em uma nova sessão, não há suporte para exibições temporárias, UDFs e implicit Python DataFrame (_sqldf) para células executadas em paralelo. Além disso, os nomes padrão do catálogo e do banco de dados são usados durante a execução paralela. Se o 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).

Executar células SQL em um armazenamento de dados SQL

Você pode executar comandos SQL em um notebook do Databricks em um SQL warehouse, um tipo de computação otimizado para análise de SQL. Confira Usar um notebook com um SQL warehouse.

Usar comandos mágicos

Os notebooks do Databricks dão suporte a vários comandos mágicos que estendem a funcionalidade além da sintaxe padrão para simplificar tarefas comuns. As mágicas de linha são prefixadas % e se aplicam a uma única linha. As magias das células são prefixadas %% e se aplicam a todo o corpo da célula.

Comando mágico	Exemplo	Descrição
%python	%python print("Hello")	Alterne o idioma da célula para Python. Executa o código Python na célula.
%r	%r print("Hello")	Alterne a linguagem de célula para R. Executa o código R na célula.
%scala	%scala println("Hello")	Alterne a linguagem de célula para Scala. Executa o código Scala na célula.
%sql	%sql SELECT * FROM table	Alterne o idioma da célula para o SQL. Os resultados estão disponíveis como _sqldf em células Python/SQL.
%md	%md # Title Content here	Alterne o idioma da célula para Markdown. Renderiza o conteúdo do Markdown na célula. Dá suporte a texto, imagens, fórmulas e LaTeX.
%pip	%pip install pandas	Instalar pacotes Python (com escopo de notebook). Consulte Bibliotecas de Python no escopo do Notebook.
%run	%run /path/to/notebook	Execute outro notebook, importando suas funções e variáveis. Consulte fluxos de trabalho do Notebook.
%fs	%fs ls /path	Execute comandos do sistema de arquivos dbutils. Abreviação dos comandos dbutils.fs. Consulte Trabalhar com arquivos.
%sh	%sh ls -la	Execute comandos de shell. É executado somente no nó do driver. Use -e para falhar em caso de erro.
%tensorboard	%tensorboard --logdir /logs	Exibir a interface do usuário do TensorBoard de forma incorporada. Disponível somente no Databricks Runtime ML. Consulte TensorBoard.
%set_cell_max_output_size_in_mb	%set_cell_max_output_size_in_mb 10	Defina o tamanho máximo da saída da célula. Intervalo: 1 a 20 MB. Aplica-se a todas as células subsequentes no notebook.
%skip	%skip print("This won't run")	Ignorar a execução da célula. Impede a execução da célula quando o notebook é executado.
%%profile	%%profile my_function()	Perfile a execução de código Python. Exibe uma árvore de chamadas hierárquica com informações de tempo. Requer o Databricks Runtime 17.2 ou versões posteriores.
%%oprofile	%%oprofile my_function()	Criação de objeto de perfil durante a execução da célula. Exibe uma tabela de novos objetos de rede criados, agrupados por tipo. Requer o Databricks Runtime 17.2 ou versões posteriores.

Observação

IPython Automagic: os notebooks do Databricks têm o IPython Automagic habilitado por padrão, permitindo que determinados comandos, como pip, funcionem sem o prefixo %. Por exemplo, pip install pandas funciona da mesma forma que %pip install pandas.

Importante

• Variáveis e estado são isolados entre diferentes REPLs de idiomas. Por exemplo, variáveis Python não são acessíveis em células de código Scala.
• Uma célula de notebook só pode ter um comando de célula mágico, e ele deve ser a primeira linha da célula.
• %run deve estar em uma célula sozinha, porque executa o notebook inteiro de forma contínua.
• Ao usar %pip no Databricks Runtime 12.2 LTS e abaixo, coloque todos os comandos de instalação do pacote no início do notebook à medida que o estado Python é redefinido após a instalação.