Skip to content

Documenta operações e ajusta threads do dbt #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AnselmoBorges merged 1 commit into from
Oct 12, 2025
Merged

Documenta operações e ajusta threads do dbt #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
256 changes: 107 additions & 149 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,181 +1,139 @@
# Guia de Treinamento – Pipeline dbt + Databricks da Rescue Point
# Pipeline dbt + Databricks – Guia Geral

Este repositório concentra a prova de conceito **dabdbt**, utilizada como trilha de treinamento para a equipe de dados da Rescue Point. O objetivo é demonstrar, de ponta a ponta, como modelar dados com **dbt**, empacotar o fluxo com **Databricks Asset Bundles** e publicar a documentação em um static website hospedado na Azure.
Repositório de treinamento **dabdbt**, utilizado pela equipe de dados da Rescue Point para demonstrar um fluxo completo de **dbt** empacotado via **Databricks Asset Bundles** e publicado em static websites na Azure. Este README cobre visão geral, automação e operação dos ambientes. A documentação específica do projeto dbt está em `dabdbt/README.md`.

---

## 1. Visão geral rápida
- **Fonte**: Azure SQL (`sqlolistdev`) exposta no Unity Catalog pelo *foreign catalog* `sqlpoclf`.
- **Camadas**:
- `rescue_dev.b`: seed `ibge_municipios`.
- `rescue_dev.s`: modelos silver (`customers_s`, `orders_s`, `order_items_s`, `order_payments_s`).
- `rescue_dev.g`: modelos gold (visões analíticas para clientes, SLA, itens, pagamentos, heatmap, cestas).
- **Publicação**: portal e artefatos `dbt docs` servidos pelo static website do storage account `sarescuedev` (container `$web`), disponível em `https://docsdev.rescuepoint.com.br/`.
- **Orquestração**: job `dabdbt_job` criado via bundle. Tasks executam, nesta ordem, `dbt seed`, `dbt run (silver)`, `dbt run (gold)`, `dbt docs generate` e o notebook `notebooks/publish_docs.py`.
## Visão geral
- **Fontes**: Azure SQL (`sqlolistdev`) exposto no Unity Catalog via catálogo federado `sqlpoclf`.
- **Camadas** (catálogos `rescue_<target>`):
- Bronze (`.b`): seed `ibge_municipios` com referência IBGE.
- Silver (`.s`): `customers_s`, `orders_s`, `order_items_s`, `order_payments_s` com enriquecimento e tags UC.
- Gold (`.g`): visões analíticas `*_g` para clientes, fulfillment, vendas, pagamentos, heatmap e cesta de produtos.
- **Publicação**: artefatos `dbt docs` e `portal.html` publicados no static website do storage (`$web`). URLs atuais: `https://docsdev.rescuepoint.com.br/` (dev) e domínio de produção em preparação.
- **Orquestração**: job `dabdbt_job` com tasks `dbt_seed` → `dbt_silver` → `dbt_gold` → `dbt_docs`. A publicação no storage é feita por GitHub Actions (veja abaixo).

---

## 2. Estrutura do repositório
Estrutura resumida do repositório:
```
.
├── README.md # Este guia
├── portal.html # Portal estático hospedado no storage
├── requirements.txt # Dependências Python para desenvolvimento
├── scripts/ # Utilitários locais
└── dabdbt/ # Projeto dbt empacotado pelo bundle
├── README.md # Guia específico do projeto dbt
├── databricks.yml # Definição dos targets e hosts Databricks
├── dbt_project.yml # Configurações (camadas, tags, persist_docs)
├── dbt_profiles/ # Perfis `dev` e `prod`
├── notebooks/ # Notebook publish_docs.py (publicação do portal)
├── resources/ # Definições do job e do cluster
├── scripts/ # Script shell para copiar docs para volumes
├── src/ # Modelos, seeds, macros e documentação
└── vars/ # Variáveis específicas por ambiente
├── README.md # Este guia geral
├── requirements.txt # Dependências para setup local
├── portal.html # Portal estático publicado no storage
└── dabdbt/ # Projeto dbt + bundle
├── README.md # Documentação detalhada do projeto dbt
├── databricks.yml # Targets, variáveis e metadados do bundle
├── dbt_project.yml # Configuração dbt (camadas, flags, persist_docs)
├── dbt_profiles/ # Perfis dev/prd (catálogos, http_path, tokens)
├── resources/ # Job + specs de cluster/warehouse
├── src/ # Modelos, seeds, macros e docs
└── notebooks/ # Notebook de publicação (ainda disponível para referência)
```

---

## 3. Preparar o ambiente
## Automação (GitHub Actions)
A pipeline foi segmentada por branch:

### 3.1 Dependências básicas
1. **Python 3.10+** e `pip`.
2. **Azure CLI** (para validar o static website quando necessário).
3. **Databricks CLI v0.272+** (instalada via script oficial).
| Workflow | Branch | Ambientes e segredos | Ações principais |
| --- | --- | --- | --- |
| `.github/workflows/deploy-dev.yml` | `dev` | Environment `dev` com `AZURE_CREDENTIALS`, `AZURE_SUBSCRIPTION_ID`, `DATABRICKS_*` e variáveis (`AZURE_STORAGE_ACCOUNT`, etc.) | Deploy do bundle em `dev`, execução do job `dabdbt_job` e correção do header MIME do blob `dabdbt/index.html` no storage `sarescuedev` via `az storage blob update --auth-mode login` |
| `.github/workflows/deploy-prd.yml` | `main` | Environment `prd` com `AZURE_CREDENTIALS_PRD`, `AZURE_SUBSCRIPTION_ID`, `DATABRICKS_*` (para o workspace prd) e variáveis iguais às de dev, porém apontando para `sarescueprd` | Deploy do bundle em `prd`, execução do job com warehouse de produção e atualização do blob no static website |

```bash
python -m venv ~/rescue-dbt
source ~/rescue-dbt/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
### Service principals
- **dev**: `ghactions-dabdbt` (já configurado). Secrets reunidos em `AZURE_CREDENTIALS`.
- **prd**: `ghactions-dabdbt-prd` (criado via CLI). Secret `AZURE_CREDENTIALS_PRD` armazena o JSON com `clientId`, `clientSecret`, `subscriptionId` (`eef39a8e-5a31-408a-87e8-a8b61faae822`) e `tenantId`.

# CLI moderna do Databricks (executa apenas uma vez)
curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh \
| bash
```
> Para cadastrar/atualizar: `gh secret set AZURE_CREDENTIALS[_PRD] --env <dev|prd> --repo AnselmoBorges/pocdabdbt --body '<json>'`.

### 3.2 Autenticação Databricks
1. Gere um **Personal Access Token** no workspace DEV.
2. Configure `~/.databrickscfg`:
```ini
[dev]
host = https://adb-1293581597272291.11.azuredatabricks.net
token = dapi<token_dev>

[prd]
host = https://adb-2533506717590470.10.azuredatabricks.net
token = dapi<token_prd>
```
3. Restrinja as permissões do arquivo: `chmod 600 ~/.databrickscfg`.
4. Teste o acesso:
```bash
databricks auth profiles list
databricks workspace list /Users --profile dev
```

### 3.3 Variáveis úteis para dbt
```bash
export DBT_PROFILES_DIR="$(pwd)/dabdbt/dbt_profiles"
export DBT_HOST="https://adb-1293581597272291.11.azuredatabricks.net"
export DBT_ACCESS_TOKEN="dapi<token_dev>"
export DBT_DEV_HTTP_PATH="/sql/1.0/warehouses/f38fa7279458bb21"
```
### Ajustes recentes
- `az storage blob update` agora usa `--auth-mode login` e `az account set` para evitar busca de account key.
- Deploy de produção usa o warehouse `7a2b912f6c29d8a8` via variável `sql_warehouse_id`; dev permanece com `f38fa7279458bb21`.
- Bundle de produção grava em `/Workspace/Shared/srv_eng_prd/.bundle/${bundle.name}/${bundle.target}`, eliminando erros de ACL e alinhando com o usuário responsável (`srv_eng_prd`).

---

## 4. Executar o projeto localmente

> Use esta etapa para entender o comportamento dos modelos antes de subir ao Databricks.

1. **Instale dependências adicionais (se houver)**:
```bash
cd dabdbt
dbt deps
```
2. **Rodar a camada bronze + silver + gold**:
```bash
dbt seed --select ibge_municipios --target dev
dbt run --select tag:silver --target dev
dbt run --select tag:gold --target dev
```
3. **Gerar documentação local**:
```bash
dbt docs generate --target dev
dbt docs serve # opcional, abre um servidor local
```
4. **Sincronizar docs com o volume** (opcional):
```bash
RESCUE_ENV=dev ./scripts/publish_docs.sh
```
5. **Verificar tags no Unity Catalog**: após os `dbt run`, valide se as tabelas em `rescue_dev.s` e `rescue_dev.g` receberam `source=Azure SQL`, `process=dbt`, `layer`, `data_owner=rescue`.
## Operação por ambiente

---
### Desenvolvimento (`dev`)
- Workspace: `https://adb-1293581597272291.11.azuredatabricks.net`.
- Catálogo default nos perfis: `rescue_dev`.
- Warehouse: `f38fa7279458bb21` (serverless).
- Storage: `sarescuedev`, container `$web`.
- Execução local: `databricks bundle deploy --target dev --profile dev` seguido de `databricks bundle run dabdbt_job --target dev --profile dev`.

### Produção (`prd`)
- Workspace: `https://adb-2533506717590470.10.azuredatabricks.net`.
- Catálogo: `rescue_prd` (configurável via `DBT_PROD_CATALOG`).
- Warehouse: `7a2b912f6c29d8a8` (variável `sql_warehouse_id`).
- Root path: `/Workspace/Shared/srv_eng_prd/.bundle/dabdbt/prd` (variável `prod_root_path`).
- Storage: `sarescueprd`, container `$web` (segredo `AZURE_CREDENTIALS_PRD` com role `Storage Blob Data Contributor`).
- Após merge em `main`, acione manualmente `Deploy dabdbt (prd)` via **Actions → Run workflow** se precisar evitar deploy automático.

## 5. Deploy via Databricks Asset Bundles

1. **Deploy**:
```bash
cd dabdbt
databricks bundle deploy --target dev --profile dev
```
2. **Executar o job completo**:
```bash
databricks bundle run dabdbt_job --target dev --profile dev
```
3. **Estrutura do job** (`resources/dabdbt.job.yml`):
- `dbt_seed`, `dbt_silver`, `dbt_gold`: executam o CLI `dbt`.
- `dbt_docs`: grava a documentação em `/Volumes/rescue_dev/rescue_b/vol_docs/dabdbt`.
- `publish_docs`: chama `notebooks/publish_docs.py`, que:
- Lê arquivos do volume.
- Publica no storage account `sarescuedev` (container `$web`).
- Define `content_type` = `text/html; charset=utf-8` e `content_disposition = inline` para todos os HTML.

> Dica: acione apenas uma task usando `databricks bundle run dabdbt_job --task dbt_gold` quando precisar depurar uma etapa específica.
### Parâmetros importantes
- `databricks.yml` controla targets, root path, variáveis (`source_olist_env`, `sql_warehouse_id`).
- `dbt_project.yml` habilita `populate_by_name` (substitui `allow_population_by_field_name`) e `use_materialization_v2`.
- `dbt_profiles/profiles.yml` contém overrides de `http_path`, `catalog`, `schema`, `host`, `token` por ambiente.

---

## 6. Portal e publicação de documentação
## Setup local rápido
```bash
python -m venv ~/.venvs/dabdbt
source ~/.venvs/dabdbt/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

curl -fsSL https://raw.githubusercontent.com/databricks/setup-cli/main/install.sh | bash

1. O portal exibido em `https://docsdev.rescuepoint.com.br/` está em `portal.html` na raiz do repositório.
2. Após o job publicar a documentação, valide os headers:
```bash
az storage blob show \
--account-name sarescuedev \
--container-name '$web' \
--name 'dabdbt/index.html' \
--query properties.contentSettings
```
O resultado esperado é `contentType = "text/html; charset=utf-8"` e `contentDisposition = "inline"`.
3. Caso precise republicar manualmente (hotfix), execute:
```bash
az storage blob upload \
--account-name sarescuedev \
--container-name '$web' \
--name portal.html \
--file portal.html \
--overwrite \
--account-key <KEY>
```
Para os artefatos de documentação, prefira reexecutar o job `publish_docs` em Databricks para manter o processo automatizado.
export DBT_PROFILES_DIR="$(pwd)/dabdbt/dbt_profiles"
export DBT_HOST="https://adb-1293581597272291.11.azuredatabricks.net"
export DBT_ACCESS_TOKEN="dapi<token_dev>"
export DBT_DEV_HTTP_PATH="/sql/1.0/warehouses/f38fa7279458bb21"

cd dabdbt
dbt deps
dbt seed --select ibge_municipios --target dev
dbt run --select tag:silver --target dev
dbt run --select tag:gold --target dev
dbt docs generate --target dev
```

### Publicação manual (hotfix)
```bash
az storage blob upload \
--account-name sarescuedev \
--container-name '$web' \
--name portal.html \
--file portal.html \
--overwrite


--account-name sarescuedev \
--container-name '$web' \
--name dabdbt/index.html \
--content-type 'text/html; charset=utf-8' \
--content-disposition inline \
--auth-mode login
```

---

## 7. Troubleshooting rápido
| Sintoma | Causa comum | Ação sugerida |
## Troubleshooting
| Sintoma | Causa provável | Como corrigir |
| --- | --- | --- |
| `InvalidUri` ao acessar `docsdev.rescuepoint.com.br` | CNAME não validado pelo storage | Confirme CNAME direto para `sarescuedev.z13.web.core.windows.net` e refaça `az storage account update --set customDomain.*` |
| HTML baixando ao invés de abrir | `contentType` incorreto no blob | Reexecute a task `publish_docs` (ou `az storage blob update --content-type 'text/html; charset=utf-8'`) |
| `dbt run` falha com credenciais | Token expirado ou `DBT_ACCESS_TOKEN` ausente | Gere novo PAT e exporte a variável antes de rodar |
| Secret `sasdocsdbt` não encontrado | Scope não configurado no workspace | Cadastre o secret `pocdocdbt/sasdocsdbt` ou use `SAS_DOCS_TOKEN` ao executar o notebook manualmente |
| `SQL warehouse ... does not exist` no deploy | Variável `sql_warehouse_id` não configurada para o target | Ajuste `databricks.yml` ou `DBT_*_HTTP_PATH` conforme ambiente |
| Deploy falha com `ACLs for directory are disabled` | Root path fora de `/Workspace/Users/...` em workspace sem ACL | Use `/Workspace/Shared/...` (como configurado) ou habilite ACLs |
| HTML baixa em vez de abrir | `contentType` incorreto no blob | Reexecute workflow ou `az storage blob update --content-type 'text/html; charset=utf-8'` |
| Pipeline dev/prod não autentica no Azure | Secret `AZURE_CREDENTIALS[_PRD]` ausente ou inválido | Recrie com JSON do service principal e confira permissões `Storage Blob Data Contributor` |
| dbt acusa flag deprectada `allow_population_by_field_name` | Flag removida no dbt 1.8+ | Já mitigado com `populate_by_name: true` (não remover) |

---

## 8. Próximos passos para o time
1. **Dashboards**: conecte Databricks SQL ou Power BI às tabelas `rescue_dev.g`.
2. **Qualidade**: inclua testes (`dbt test`) e alertas personalizados no job.
3. **Produção**: ajuste `vars/prod.yml`, `databricks.yml` e configure `prod_root_path`/`prod_owner_user` quando o ambiente PRD for habilitado.
4. **Resiliência**: considere habilitar `retry_all` e `timeouts` específicos por task conforme as cargas crescerem.

Para uma visão detalhada do projeto dbt, consulte `dabdbt/README.md`. Para descrições de tabelas, fontes e macros, acesse `src/docs/overview.md` e `src/docs/sources.md` dentro do bundle.
## Próximos passos sugeridos
- Adicionar `dbt test` e testes personalizados para validar os modelos gold.
- Versionar e publicar dashboards conectados às tabelas `rescue_<target>.g`.
- Expandir monitoramento das Actions com notificações (Slack/email) em falhas.
- Avaliar uso de Unity Catalog grants via bundle (`grants.yml`) para automatizar permissões após o deploy.

Espero que esse material ajude!
Para detalhes das transformações e componentes dbt, consulte `dabdbt/README.md` e a documentação gerada em `src/docs`.```*** End Patch
1. O portal exibido em `https://docsdev.rescuepoint.com.br/` está em `portal.html` na raiz do repositório.
Loading