Desenvolver código em notebooks do Databricks

Esta página descreve como desenvolver código em cadernos Databricks, incluindo formatação de código, autocompletamento, mistura de linguagens e comandos mágicos.

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 usa o caderno ou o editor de ficheiros, o Genie Code está disponível para o ajudar a gerar, explicar e depurar código. Consulte Use Genie Code para mais informações.

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

Importante

O notebook deve estar ligado a uma sessão de compute ativa para funcionalidades de assistência ao código, incluindo autocompletamento, formatação de código Python e o depurador.

Modularize seu código

Com o Databricks Runtime 11.3 LTS e superiores, pode criar e gerir ficheiros de código-fonte no espaço de trabalho do Azure Databricks e depois importar esses ficheiros para os seus cadernos conforme necessário.

Para mais informações sobre como trabalhar com ficheiros de código-fonte, veja Partilhar código entre notebooks 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 em Python e SQL em células de caderno. 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 Python Black Formatter

Importante

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

Azure Databricks suporta formatação de código Python usando preto dentro do caderno. O notebook deve estar anexado a um cluster com os pacotes Python black e tokenize-rt instalados.

Na Databricks Runtime 11.3 LTS e versões superiores, 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 inferiores, deve instalar black==22.3.0 e tokenize-rt==4.2.1 a partir do PyPI no seu portátil ou cluster para usar 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 mais detalhes sobre a instalação de bibliotecas, consulte Python gestão de ambientes.

Para ficheiros e cadernos nas pastas Git do Databricks, podes 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.

Azure Databricks usa um formatador SQL personalizado para formatar SQL e o formador 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 Formatar Python no menu suspenso de opções de comando de uma célula Python. Este item do menu só é visível nas células do notebook Python ou naquelas com uma %pythonmágica de linguagem.
  • Menu do Caderno Edit: Selecionar uma célula Python ou SQL, e depois selecionar Edit > Formatar Célula(s).

• Formatar várias células

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

• Formate todas as células Python e SQL no caderno

  Selecione Editar > Formatar Bloco de Anotações. Se o seu caderno contiver mais do que uma linguagem, apenas as células SQL e Python sã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.
• A formatação de cadeias Python embutidas dentro de um UDF SQL não é suportada. De forma semelhante, a formatação de strings SQL dentro de um UDF Python 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.

Alternativamente, podes usar o comando %<language> de magia de linguagem 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 mais informações, consulte Trabalhar com ficheiros em 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.

Realce da sintaxe SQL e autocompletar comandos em Python

O realce de sintaxe e o SQL autocompletamento estão disponíveis quando usas SQL dentro de um comando Python, como num comando spark.sql.

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. Depois podes usar esta variável em qualquer célula de Python e SQL que executes depois, independentemente da sua posição no caderno.

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 em células de Python subsequentes é suportada no Databricks Runtime 13.3 e superiores.
• 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 ecrã abaixo mostra como _sqldf pode ser usada 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 numa nova sessão, vistas temporárias, UDFs e o implicito Python DataFrame (_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 num SQL warehouse

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.

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. As magias de linha são prefixadas com % e aplicam-se a uma única linha. Os comandos mágicos de célula têm o prefixo %% e aplicam-se a todo o corpo da célula.

Comando mágico	Exemplo	Descrição
%python	%python print("Hello")	Muda a linguagem celular 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 em 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	Instalar pacotes Python (limitados ao caderno). Ver Bibliotecas de Python com âmbito do notebook.
%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.
%%profile	%%profile my_function()	Execução de código Python de perfil. Apresenta uma árvore de chamadas hierárquica com informações de temporização. Requer Databricks Runtime 17.2 ou superior.
%%oprofile	%%oprofile my_function()	Criação de objetos de perfil durante a execução da célula. Apresenta uma tabela de novos objetos criados, agrupados por tipo. Requer Databricks Runtime 17.2 ou superior.

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 nas 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 ou versões anteriores, coloque todos os comandos de instalação do pacote no início do seu notebook, pois o estado do Python é reiniciado após a instalação.