Desenvolver código em notebooks do Databricks

Esta página descreve como desenvolver código em blocos de anotações Databricks, incluindo preenchimento automático, formatação automática para Python e SQL, combinação de Python e SQL em um bloco de anotações e acompanhamento do histórico de versões do notebook.

Para obter mais detalhes sobre as funcionalidades avançadas disponíveis com o editor, como preenchimento automático, seleção de variáveis, suporte a vários cursores e comparações lado a lado, consulte Como navegar pelo bloco de notas Databricks e editor de ficheiros.

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

Os notebooks Databricks também incluem um depurador interativo integrado para notebooks Python. Consulte Depurar cadernos.

Modularize seu código

Com o Databricks Runtime 11.3 LTS e superior, você pode criar e gerenciar arquivos de código-fonte no espaço de trabalho do Azure Databricks e, em seguida, importar esses arquivos para seus blocos de anotações, 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 Databricks e Trabalhar com módulos Python e R.

Formatar células de código

O Azure 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 para manter seu código formatado e ajudam a impor os mesmos padrões de codificação em seus blocos de anotações.

Biblioteca do Black formatter para Python

Importante

Esta funcionalidade está em Pré-visualização Pública.

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

No Databricks Runtime 11.3 LTS e superior, o 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 versões anteriores, é necessário instalar black==22.3.0 e tokenize-rt==4.2.1 a partir do PyPI no seu notebook ou cluster para utilizar o formatador Python. Pode executar o seguinte comando no seu bloco de notas:

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

ou instale a biblioteca no cluster.

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

Para ficheiros e cadernos de notas em pastas Databricks Git, pode-se configurar o formatador Python com base no ficheiro pyproject.toml. Para usar este recurso, crie um arquivo pyproject.toml no diretório raiz da pasta do 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ê deve ter a permissão CAN EDIT no bloco de anotações para formatar o código.

O Azure Databricks usa a biblioteca Gethue/sql-formatter para formatar SQL e o formatador de código preto para Python.

Você pode acionar 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 de contexto do comando de uma célula SQL. Este item de menu é visível apenas em células do bloco de notas SQL ou naquelas com uma %sqlmágica de linguagem.
    • Formatar célula Python: Selecione Format Python no menu suspenso de contexto de comando de uma célula Python. Este item de menu é visível apenas em células de bloco de anotações Python ou naquelas com uma %pythonmágica de linguagem.
  • No menu Editar do Bloco de Anotações: Selecione uma célula Python ou SQL e, em seguida, selecione Editar > Formatar Célula(s).

• Formatar várias células

  Selecione várias células e, em seguida, selecione Editar > Formatar Célula(s). Se você selecionar células de mais de uma linguagem, somente as células SQL e Python serão formatadas. Isto inclui quem utiliza %sql e %python.

• Formatar todas as células Python e SQL no bloco de notas

  Selecione Editar > Formatar Bloco de Anotações. Se o seu bloco de notas contiver mais do que uma linguagem, apenas as células SQL e Python serão formatadas. Isto inclui quem utiliza %sql e %python.

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

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

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

Linguagens de código em blocos de notas

Definir 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 no menu suspenso. Para garantir que os comandos existentes continuem a funcionar, os comandos do idioma padrão anterior são automaticamente prefixados com um comando language magic.

Misturar idiomas

Por padrão, as células usam o idioma padrão do bloco de anotações. Você pode substituir o idioma padrão em uma célula clicando no botão de idioma e selecionando um idioma no menu pendente.

Como alternativa, pode usar o comando mágico de idioma %<language> no início de uma célula. Os comandos mágicos suportados são: %python, %r, %scala, e %sql.

Nota

Quando se invoca um comando de mágica de linguagem, o comando é enviado para o REPL no contexto de execução do caderno. As variáveis definidas numa língua (e, portanto, no REPL para essa língua) não estão disponíveis no REPL de outra língua. Os REPLs podem compartilhar o estado somente por meio de recursos externos, como arquivos no DBFS ou objetos no armazenamento de objetos.

Os notebooks também suportam alguns comandos mágicos auxiliares:

• %sh: Permite que você execute o código shell em seu bloco de anotações. Para fazer a célula falhar se o comando shell tiver um status de saída diferente de zero, adicione a opção -e. Este comando é executado apenas no driver 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 usar comandos do sistema de ficheiros dbutils. 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 incluir vários tipos de documentação, incluindo texto, imagens e fórmulas e equações matemáticas. Consulte a secção seguinte.

Destacar e autocompletar a sintaxe SQL em comandos Python

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

Explore os resultados da célula SQL

Em um bloco de anotações 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 Python e SQL executada depois, independentemente de sua posição no bloco de anotações.

Nota

Este recurso tem as seguintes limitações:

• A _sqldf variável não está disponível em blocos de anotações que usam um SQL warehouse para computação.
• A utilização de _sqldf nas células subsequentes de Python é suportada no Databricks Runtime 13.3 e superior.
• O uso _sqldf em células SQL subsequentes só é suportado 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 pode ser usado em células Python e SQL subsequentes:

Importante

A variável _sqldf é reatribuída cada vez que uma célula SQL é executada. Para evitar perder a referência a um resultado específico do DataFrame, 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 está em execução e seu bloco de anotações está anexado 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:

1. Corre a célula.

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

   

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

Executar células SQL em um armazém SQL

Você pode executar comandos SQL em um bloco de anotações Databricks em um SQL warehouse, um tipo de computação otimizado para análise SQL. Consulte Usar um notebook com um depósito de SQL.

Executar código no Assistente em computação sem servidor

Você pode executar código no Assistente em Databricks em computação sem servidor, que é a computação padrão em Databricks. Para páginas onde já há uma computação selecionada (por exemplo, blocos de anotações ou editor SQL), o Databricks usa como padrão usá-la. Para obter informações sobre tipos de computação, consulte Computação.

Se você não tiver acesso à computação sem servidor, deverá ter uma instância de computação disponível para executar o código no painel Assistente.

Use comandos mágicos

Os notebooks Databricks suportam vários comandos mágicos que estendem a funcionalidade além da sintaxe padrão para simplificar tarefas comuns. Os comandos mágicos são prefixados com % com as mágicas de linha e célula.

Comando mágico	Exemplo	Descrição
%python	%python print("Hello")	Mude a linguagem da célula para Python. Executa código Python na célula.
%r	%r print("Hello")	Alterne o idioma da célula para R. Executa o código R na célula.
%scala	%scala println("Hello")	Mude o idioma da célula para Scala. Executa o código Scala na célula.
%sql	%sql SELECT * FROM table	Mude a linguagem da célula para SQL. Os resultados estão disponíveis como _sqldf nas células Python/SQL.
%md	%md # Title Content here	Mude o idioma da célula para Markdown. Renderiza o conteúdo de Markdown na célula. Suporta texto, imagens, fórmulas e LaTeX.
%pip	%pip install pandas	Instale pacotes Python (de âmbito específico de notebook). Veja Bibliotecas de Python específicas para notebooks.
%run	%run /path/to/notebook	Execute outro notebook, importando suas funções e variáveis. Consulte Fluxos de trabalho do bloco de notas.
%fs	%fs ls /path	Execute comandos do sistema de ficheiros dbutils. Taquigrafia de comandos dbutils.fs. Consulte Trabalhar com ficheiros.
%sh	%sh ls -la	Execute comandos na linha de comando. É executado somente no nó do driver. Use -e para falhar em caso de erro.
%tensorboard	%tensorboard --logdir /logs	Exiba a interface do usuário do TensorBoard de forma integrada. Disponível apenas 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 de saída da célula. Intervalo: 1-20 MB. Aplica-se a todas as células subsequentes do bloco de notas.
%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.

Nota

IPython Automagic: Nos notebooks Databricks, o recurso automágico do IPython está ativado por padrão, permitindo que certos comandos sejam executados pip sem o prefixo %. Por exemplo, pip install pandas funciona da mesma forma que %pip install pandas.

Importante

• As variáveis e o estado são isolados entre REPLs de linguagem diferente. Por exemplo, variáveis Python não são acessíveis em células Scala.
• Uma célula de notebook só pode ter um comando mágico de célula, devendo ser a primeira linha da célula.
• %run deve estar em uma célula por si só, porque ele executa todo o bloco de anotações em linha.
• Ao usar %pip no Databricks Runtime 12.2 LTS e inferior, coloque todos os comandos de instalação do pacote no início do seu notebook, pois o estado Python é redefinido após a instalação.