Gerenciar ativos de arquivo em pastas Git do Databricks

As pastas Git do Databricks servem como clientes Git para clones gerenciados pelo Databricks de repositórios de origem baseados em Git, permitindo que você execute um subconjunto de operações Git no conteúdo do seu workspace. Como parte dessa integração com o Git, os arquivos armazenados no repositório remoto são vistos como "ativos" com base em seu tipo, com algumas limitações específicas para seu tipo. Os arquivos de notebook, em particular, têm propriedades diferentes com base em seu tipo. Leia este artigo para entender como trabalhar com ativos, especialmente notebooks IPYNB, em pastas Git.

Tipos de ativos com suporte

Apenas determinados tipos de ativos do Azure Databricks são aceitos pelas pastas Git. Nesse caso, "aceito" significa "pode ser serializado, controlado por versão e enviado para o repositório Git de suporte".

Atualmente, os tipos de ativos de dados aceitos são:

Tipo de ativo	Detalhes
Arquivo	Os arquivos são dados serializados e podem incluir qualquer coisa, de bibliotecas a binários, código e imagens. Para obter mais informações, leia O que são arquivos de workspace?
Notebook	Os notebooks são especificamente os formatos de arquivo de bloco de anotações suportados pelo Databricks. Os notebooks são considerados um tipo de ativo separado do Azure Databricks dos Arquivos porque eles não são serializados. As pastas Git determinam um Notebook pela extensão de nome de arquivo (por exemplo, .ipynb) ou por extensões de nome de arquivo combinadas com um marcador especial no conteúdo do arquivo (por exemplo, um comentário # Databricks notebook source no início dos arquivos de origem .py).
Pasta	Uma pasta é uma estrutura específica do Azure Databricks que representa informações serializadas sobre um agrupamento lógico de arquivos no Git. Como esperado, o usuário experimenta isso como uma "pasta" ao exibir uma pasta Git do Azure Databricks ou acessá-la com a CLI do Azure Databricks.

Os tipos de ativo do Azure Databricks que atualmente não têm suporte em pastas Git incluem o seguinte:

• Consultas DBSQL
• Alertas
• Painéis (incluindo painéis herdados)

Ao trabalhar com seus ativos no Git, observe as seguintes limitações de nomenclatura de arquivo:

• Uma pasta não pode conter um notebook com o mesmo nome de outro bloco de anotações, arquivo ou pasta no mesmo repositório Git, mesmo que a extensão de arquivo seja diferente. (Para notebooks de formato de origem, a extensão é .py para Python, .scala para Scala, .sql para SQL e .r para R. Para notebooks no formato IPYNB, a extensão é .ipynb.) Por exemplo, você não pode usar um notebook de formato de origem nomeado test1.py e um bloco de anotações IPYNB nomeado test1 na mesma pasta Git porque o arquivo de notebook do Python no formato de origem (test1.py) será serializado como test1 e ocorrerá um conflito.
• Não há suporte para o caractere / em nomes de arquivo. Por exemplo, você não pode ter um arquivo nomeado i/o.py em sua pasta Git.

Se você tentar executar operações Git em arquivos que têm nomes que têm esses padrões, receberá uma mensagem "Erro ao buscar o status do Git". Se você receber este erro inesperadamente, examine os nomes de arquivo dos ativos em seu repositório Git. Se você encontrar arquivos com nomes que tenham esses padrões conflitantes, renomeie-os e tente executar a operação novamente.

Observação

Você pode mover ativos sem suporte existentes para uma pasta Git, mas não pode fazer commit das alterações desses ativos de volta para o repositório. Você não pode criar novos ativos sem suporte em uma pasta Git.

Formatos de notebook

O Databricks considera dois tipos de formatos de notebook de alto nível, específicos do Databricks: "origem" e "ipynb". Quando um usuário faz a confirmação de um notebook no formato "origem", a plataforma Databricks faz a confirmação de um arquivo simples com um sufixo de idioma, como .py, .sql, .scala ou .r. Um notebook em formato de "origem" contém apenas o código-fonte e não contém saídas, como exibições de tabelas e visualizações que são os resultados da execução do notebook.

O formato "ipynb", no entanto, tem saídas associadas a ele, e esses artefatos são automaticamente enviados para o repositório Git que faz o backup da pasta Git ao enviar por push o notebook .ipynb que os gerou. Se quiser confirmar os resultados junto com o código, use o formato de notebook "ipynb" e a configuração de instalação para permitir que um usuário confirme as saída geradas. Como resultado, o "ipynb" também dá suporte a uma melhor experiência de exibição no Databricks para os notebooks enviados para repositórios Git remotos por meio de pastas Git.

Formato de fonte de notebook	Detalhes
origem	Pode ser qualquer arquivo de código com um sufixo de arquivo padrão que sinalize a linguagem do código, como .py, .scala, .r e .sql. Os notebooks de "origem" são tratados como arquivos de texto e não incluirão nenhuma saída associada quando confirmados novamente em um repositório Git.
ipynb	Os arquivos "ipynb" terminam com .ipynb e podem, se configurados, enviar resultados (como visualizações) da pasta Git do Databricks para o repositório Git de backup. Um notebook .ipnynb pode conter código em qualquer linguagem compatível com os notebooks do Databricks (apesar da parte py de .ipynb).

Se quiser que as saídas sejam enviadas de volta ao seu repositório após a execução de um notebook, use um notebook .ipynb (Jupyter). Se você quiser apenas executar o notebook e gerenciá-lo no Git, use um formato "origem" como .py.

Para obter mais detalhes sobre os formatos de notebook com suporte, leia Exportar e importar notebooks do Databricks.

Observação

O que são "outputs"?

As saídas são os resultados da execução de um notebook na plataforma Databricks, incluindo exibições de tabelas e visualizações.

Como fazer para informar qual formato um notebook está usando, além da extensão do arquivo?

Na parte superior de um notebook gerenciado pelo Databricks, geralmente há um comentário de uma única linha que indica o formato. Por exemplo, para um .py notebook "origem", você verá uma linha semelhante a esta:

# Databricks notebook source

Para arquivos .ipynb, o sufixo do arquivo é usado para indicar que se trata do formato de notebook "ipynb".

Notebooks IPYNB em pastas Git do Databricks

O suporte para notebooks Jupyter (arquivos .ipynb) está disponível nas pastas Git. Você pode clonar repositórios com .ipynb notebooks, trabalhar com eles no produto Databricks e, em seguida, confirmar e efetuar push como .ipynb notebooks. Metadados como o painel de controle de notebook são preservados. Os administradores podem controlar se as saídas podem ser confirmadas ou não.

Permitir commit da saída do notebook .ipynb

Por padrão, a configuração de administrador para pastas Git não permite que seja feito commit da saída do notebook .ipynb. Os administradores do workspace podem alterar essa configuração:

1. Vá para as configurações Configurações do administrador > Workspace.

2. Em Pastas Git > Permitir que pastas Git exportem saídas IPYNB, selecione Permitir: saídas IPYNB podem ser ativadas.

   

Importante

Quando as saídas são incluídas, as configurações de visualização e dashboard são preservadas com o formato de arquivo .ipynb.

Controlar as confirmações de artefatos de saída do notebook do IPYNB

Quando você confirma um arquivo .ipynb, o Databricks cria um arquivo de configuração que permite controlar como você confirma as saídas: .databricks/commit_outputs.

1. Se você tiver um arquivo de notebook .ipynb, mas nenhum arquivo de configuração em seu repositório, abra o modal Status do Git.

2. Na caixa de diálogo de notificação, clique em Criar arquivo commit_outputs.

   

Você também pode gerar arquivos de configuração no menu Arquivo. O menu Arquivo tem um controle que permite atualizar automaticamente o arquivo de configuração para especificar a inclusão ou exclusão de saídas para um notebook específico.

1. No menu Arquivo, selecione Confirmar saídas de notebooks.

   

2. Na caixa de diálogo, confirme sua escolha para confirmar as saídas do notebook.

   

Converter um notebook de origem em IPYNB

Você pode converter um notebook de origem existente em uma pasta Git em um notebook IPYNB por meio da interface do usuário do Azure Databricks.

1. Abra um bloco de anotações de origem em seu workspace.

2. Selecione Arquivo no menu do workspace e selecione Alterar formato do notebook [origem]. Se o notebook já estiver no formato IPYNB, a [origem] será [ipynb] no elemento de menu.

   

3. Na caixa de diálogo modal, selecione "Formato do notebook Jupyter (.ipynb)" e clique em Alterar.

   

Também é possível:

• Criar novos notebooks .ipynb.
• Exiba as diferenças como Diferença de código (alterações de código nas células) ou Diferença bruta (alterações de código apresentadas como sintaxe JSON, que inclui saídas de notebook como metadados).

Para obter mais informações sobre os tipos de notebooks com suporte no Azure Databricks, leia Exportar e importar notebooks do Databricks.