Compartilhar via


Desenvolver código em notebooks do Databricks

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

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, consulte Navegar pelo notebook e o editor de arquivos do Databricks.

Quando você usa o notebook ou o editor de arquivos, o Assistente do Databricks está disponível para ajudar a gerar, explicar e depurar código. Confira Usar o Assistente do Databricks para obter mais informações.

Os notebooks do Databricks também incluem um depurador interativo interno para notebooks Python. Consulte Depurar notebooks.

Modularizar seu código

Importante

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

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 notebooks conforme necessário.

Para obter mais informações sobre como trabalhar com arquivos de código-fonte, consulte Compartilhar código entre notebooks do 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 SQL e Python em células do notebook de maneira 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 notebooks.

Biblioteca formatadora Black do Python

Importante

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

O Azure Databricks dá suporte à formatação de código Python usando a black no notebook. O notebook deve ser anexado a um cluster com os 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 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 saber mais detalhes sobre como instalar bibliotecas, confira Gerenciamento de ambiente do Python.

Quanto aos arquivos e notebooks nas pastas Git do Databricks, você 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 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.

O Azure Databricks usa a biblioteca Gethue/sql-formatter para formatar o SQL e o formatador de código black 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 fica visível apenas nas células do bloco de notas SQL ou naquelas com %sqllinguagem magic.
      • Formatar célula Python: selecione Formatar Python no menu suspenso de contexto de comando de uma célula Python. Este item de menu é visível apenas em células de notebook Python ou naquelas com uma %pythonlinguagem magic.
    • Menu Editar do notebook: 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élulas. Se você selecionar células de mais de uma linguagem, somente células SQL e Python serão formatadas. Isso inclui aquelas que usam %sql e %python.

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

    Selecione Editar > Formatar Notebook. Se o notebook contiver células de mais de uma linguagem, somente células SQL e Python serão formatadas. Isso inclui aquelas que usam %sql e %python.

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

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

Idiomas de código em notebooks

Definir como idioma padrão

O idioma padrão do notebook aparece ao lado do nome do notebook.

Idioma padrão do notebook

Para alterar o idioma padrão, clique no botão de idioma e selecione o novo idioma no menu suspenso. Para garantir o funcionamento dos comandos existentes, os comandos do idioma padrão anterior são prefixados automaticamente com um comando magic de idioma.

Misturar idiomas

Por padrão, as células usam o idioma padrão do notebook. Você pode substituir o idioma padrão em uma célula clicando no botão de idioma e selecionando um idioma no menu suspenso.

Menu suspenso de idioma da célula

Como alternativa, é possível usar o comando magic de idioma %<language> no inicio de uma célula. Os comandos magic com suporte são: %python, %r, %scala e %sql.

Observação

Quando você invoca um comando magic de linguagem, o comando é expedido 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 magic auxiliares:

  • %sh: permite que você execute o código do shell em seu notebook. Para falhar a célula 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, confira 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 de sintaxe do SQL e preenchimento automático em comandos do Python

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

Explorar os 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 Python e SQL executada posteriormente, independentemente de sua posição no notebook.

Observação

Este recurso tem as seguintes limitações:

  • A _sqldf variável não está disponível em notebooks que usam um SQL warehouse para computação.
  • O uso _sqldf em células subsequentes do Python tem suporte no Databricks Runtime 13.3 e superior.
  • 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 pode ser usado em células Python e SQL subsequentes:

dataframe de resultados sql

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. Execute a célula.

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

    Execute a célula SQL em paralelo com a célula em execução

Como a célula é executada em uma nova sessão, não há suporte para exibições temporárias, UDFs e DataFrame implícito do Python (_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 SQL warehouse

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.