worlddatabank

Visão Geral — Metodologia de Pipelines Fabric

Esta metodologia define como construímos e organizamos pipelines de dados em Microsoft Fabric. É aplicada consistentemente em todos os pipelines do projecto.

Arquitectura Medallion

Todos os pipelines seguem a arquitectura Bronze → Silver → Gold:

Fonte Externa
     │
     ▼
  BRONZE          Cópia fiel da fonte — sem transformações de schema
     │
     ▼
  SILVER          Normalização: cast de tipos, colunas de auditoria, overwrite
     │
     ▼
  GOLD            Consolidação: harmonização de múltiplas fontes, mapeamentos, enriquecimento

Quando usar cada camada

Camada	Responsabilidade	Escrita
Bronze	Copiar dados externos para o Lakehouse sem alterar o conteúdo	Ficheiros originais (CSV, JSON, etc.)
Silver	Normalizar schema, cast de tipos, adicionar colunas de auditoria	Delta, mode=overwrite
Gold	Consolidar múltiplas fontes, aplicar mapeamentos, enriquecer	Delta, delete+append por fonte ou overwrite total

Organização dos Notebooks

Cada pipeline tem uma pasta de notebooks com esta estrutura típica:

notebooks/<pipeline>/
├── <pipeline>_runner.ipynb        — orquestrador, único ponto de entrada
├── <pipeline>_BRONZE.ipynb        — ingestão (ou vários notebooks de bronze por fonte)
├── <pipeline>_SILVER.ipynb        — normalização (ou vários por fonte)
└── <pipeline>_GOLD.ipynb          — consolidação

As bibliotecas partilhadas são compiladas a partir de notebooks/Utils/ e instaladas em /lakehouse/default/Files/Global_Libs/ no Fabric.

Padrões Transversais

Todos os notebooks do pipeline partilham os mesmos padrões:

Parâmetros via main_set — configuração injectada pelo runner em runtime (ver Orquestração)
Logging estruturado — ELogger com correlation_id propagado entre notebooks (ver Bibliotecas)
Error handling — padrão handleError com saída imediata em produção (ver Silver)
Execução local vs. produção — flag running_local controla comportamento de erros e parâmetros

Decisões Arquitecturais

Sem Vendor Lock-in — Notebooks em vez de Data Factory / Dataflow Gen2

Todos os pipelines são implementados em Spark notebooks, não em Data Factory Gen2 pipelines nem Dataflow Gen2. Razões:

Os notebooks são portáteis — correm localmente, num workspace de desenvolvimento, e em produção sem alterações
A lógica está em Python/PySpark, não em configuração visual proprietária que não é versionável de forma útil
O runner invoca notebooks via notebookutils.notebook.run() — sem dependências de conectores proprietários
Sem componentes visuais cujo comportamento muda entre versões do Fabric sem aviso

Tudo Parametrizável — Sem Valores Hardcoded

Nunca se hardcodam paths de Lakehouses, nomes de contentores, credenciais, ou qualquer configuração que varie por ambiente. Tudo passa via main_set:

# ✅ Correcto — parametrizado via main_set
lh_bronze = main_set["lh_bronze"]   # abfss://workspace@onelake.dfs.fabric.microsoft.com/lakehouse.Lakehouse

# ❌ Errado — hardcoded
lh_bronze = "abfss://33f78fb2-abc-.../<guid>.Lakehouse"

Isto garante que o mesmo notebook corre em desenvolvimento, staging e produção apenas mudando os parâmetros no runner.

Sempre ABFSS — Sem Montagem de Lakehouses

Os paths de Lakehouse são sempre em formato ABFSS (abfss://<workspace>@onelake.dfs.fabric.microsoft.com/<lakehouse>/). Nunca se “afixa” um Lakehouse em construção de paths — os paths chegam sempre como parâmetro.

A excepção são as Global Libs, que estão afixadas como Lakehouse por defeito no contexto dos notebooks. Isto permite o import directo sem configuração:

import sys
sys.path.append("/lakehouse/default/Files/Global_Libs")
from dap_ELogger import ELogger

Este /lakehouse/default/ funciona porque o Lakehouse das Global Libs está configurado como default no workspace. Para tudo o resto, usar ABFSS explícito.

Separação de Workspaces por Tipo de Acesso

Workspace	ID	Quando usar
`e_ext_ingest_ws`	—	Dados com acesso público ou provenientes do exterior (APIs públicas, parceiros, upload de ficheiros)
`e_int_ingest_ws`	—	Dados com acesso privado ou de sistemas internos

O pipeline Calamidade e o Gapminder correm em e_ext_ingest_ws. Pipelines que acedam a sistemas internos ou dados sensíveis devem usar e_int_ingest_ws.

Trabalho Futuro

Áreas identificadas para evolução, mas ainda não implementadas:

Funções centralizadas: centralizar funções utilitárias reutilizáveis (normalizar_geo, cast functions, etc.) numa biblioteca partilhada acessível a todos os pipelines. Actualmente estão duplicadas inline em cada notebook silver.
Configuração metadata-driven: mover a configuração de pipelines (grupos, tasks, parâmetros) para tabelas de metadata em vez de estar hardcoded no runner. Permitiria alterar a configuração sem modificar notebooks.

Case Studies

Implementações concretas desta metodologia:

PAGE — Apoio Calamidade — ingestão de candidaturas via Azure Blob Storage
Gapminder — ingestão de indicadores económicos via REST API pública

Documentação da Metodologia

Secção	Conteúdo
Camada Bronze	Padrões de ingestão de dados externos
Camada Silver	Normalização, casting, auditoria
Camada Gold	Consolidação, mapeamentos, enriquecimento
Orquestração — Runner	Configuração declarativa, grupos, movement types
Bibliotecas Comuns	ELogger, Azure REST, Lakehouse file tools
Fontes de Dados	Padrões de acesso a fontes externas

Voltar à Home

This site is open source. Improve this page.