Como reutilizar notebooks com %run no Databricks

Copiar e colar as mesmas funções em cada notebook do Databricks torna o código difícil de manter: basta uma correção e tens de a repetir em vários sítios. Para reutilizar código entre notebooks no Databricks existe o comando mágico %run, que executa outro notebook e disponibiliza as suas funções e variáveis no notebook atual. O resultado é um único sítio para manter os utilitários partilhados, sem duplicação.

Pré-requisitos

• Acesso a um workspace do Databricks.
• Um cluster ativo para executar os notebooks.
• Conhecimentos básicos de Python.

Passo 1: Criar o notebook de utilitários

Cria um notebook chamado utils na mesma pasta onde vais trabalhar. Este notebook serve apenas para guardar as funções e variáveis que queres partilhar — pode conter qualquer código Python, desde constantes a funções auxiliares. Escreve o seguinte numa célula:

# Notebook: utils
PAIS_PADRAO = "Portugal"

def saudacao(nome):
    return f"Olá, {nome}!"

def contar_linhas(df):
    return df.count()

Não precisas de executar este notebook manualmente. O comando %run trata disso quando o chamares a partir de outro notebook.

Passo 2: Colocar os notebooks na mesma pasta

O %run aceita caminhos relativos. Se o notebook utils estiver na mesma pasta que o teu notebook principal, referencia-o com ./utils. Para pastas diferentes, usa o caminho completo, por exemplo /Workspace/Users/o-teu-email/utils. Confirma no explorador do Workspace que ambos os notebooks estão onde esperas.

Passo 3: Chamar o notebook com %run

No teu notebook principal, cria uma célula só com o comando %run. Este comando tem de ficar sozinho na célula — não o podes misturar com outro código Python na mesma célula.

%run ./utils

Ao executar esta célula, o Databricks corre o notebook utils do início ao fim e traz todas as suas definições para o contexto atual. É como se tivesses escrito aquele código no próprio notebook principal.

Passo 4: Usar as funções e variáveis importadas

Depois do %run, as funções saudacao e contar_linhas e a variável PAIS_PADRAO já estão disponíveis. Testa-as numa célula nova:

print(saudacao("bConcepts"))
print("País padrão:", PAIS_PADRAO)

dados = [("Ana", 30), ("Rui", 25)]
df = spark.createDataFrame(dados, ["nome", "idade"])
print("Total de linhas:", contar_linhas(df))

Repara que não voltaste a definir nenhuma destas funções: vieram todas do notebook utils. É este o ganho — escreves uma vez, usas em qualquer lado.

Passo 5: Reutilizar noutro notebook

A grande vantagem aparece quando tens vários notebooks. Cria um segundo notebook, por exemplo relatorio, na mesma pasta e coloca lá também %run ./utils numa célula isolada. Todas as funções ficam disponíveis sem copiar uma única linha. Se um dia corrigires a função saudacao no notebook utils, todos os notebooks que fazem %run passam a usar a versão corrigida automaticamente.

Verificar o resultado

Se tudo correu bem, a célula do Passo 4 mostra:

Olá, bConcepts!
País padrão: Portugal
Total de linhas: 2

Se aparecer o erro NameError: name 'saudacao' is not defined, é sinal de que a célula do %run não foi executada antes, ou de que o caminho está errado. Confirma que executaste primeiro a célula do %run e que o nome em ./utils coincide exatamente — maiúsculas e minúsculas contam.

Dica: o %run partilha o mesmo contexto, por isso as variáveis ficam acessíveis. Se precisares de executar um notebook de forma isolada e receber um valor de retorno, usa antes dbutils.notebook.run("utils", 60).

Conclusão

Com o %run passas a ter uma única fonte de verdade para funções e configurações partilhadas, o que reduz erros e facilita a manutenção. A partir daqui, organiza os utilitários por temas — por exemplo, um notebook para leitura de dados e outro para validações — e considera versioná-los com Databricks Repos e Git. Que funções repetes hoje nos teus notebooks e já podias mover para um utils?