diff --git a/README.md b/README.md index 8fa6d44..fba9336 100644 --- a/README.md +++ b/README.md @@ -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_`): + - 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 --repo AnselmoBorges/pocdabdbt --body ''`. -### 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 - - [prd] - host = https://adb-2533506717590470.10.azuredatabricks.net - token = dapi - ``` -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" -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 - ``` - 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" +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_.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. diff --git a/dabdbt/README.md b/dabdbt/README.md index 920666e..c20843e 100644 --- a/dabdbt/README.md +++ b/dabdbt/README.md @@ -1,106 +1,112 @@ -# Projeto dbt `dabdbt` – Guia Operacional +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 +# Projeto dbt `dabdbt` – Guia Operacional Interno -Este diretório contém o projeto dbt utilizado na POC da Rescue Point. Aqui estão os modelos, seeds, macros, notebooks e definições do Databricks Asset Bundle responsáveis por mover dados do Azure SQL para camadas analíticas no Unity Catalog e publicar a documentação no storage account `sarescuedev`. +Documentação do diretório `dabdbt/`, que contém o projeto dbt empacotado pelo Databricks Asset Bundle. Aqui estão as instruções de configuração, execução, estrutura de camadas e componentes auxiliares. --- ## 1. Componentes principais -- **`databricks.yml`** – Define os targets (`dev`, `prd`), hosts dos workspaces e variáveis padrão para deploy. -- **`dbt_project.yml`** – Configura camadas (`silver` → schema `s`, `gold` → schema `g`, `seeds` → schema `b`) e ativa `persist_docs`. -- **`dbt_profiles/`** – Perfis `dev` e `prod`, com catálogos `rescue_dev` / `rescue_prd`. -- **`resources/`** – Arquivos YAML do bundle (`dabdbt.job.yml`) e especificação do cluster single-node usado pelas tasks. -- **`notebooks/publish_docs.py`** – Notebook que publica o portal no container `$web`, aplicando `content_type` e `content_disposition` corretos. -- **`scripts/publish_docs.sh`** – Alternativa em shell para sincronizar o conteúdo de `target/docs` com o volume `/Volumes/rescue_/rescue_b/vol_docs`. -- **`src/`** – Modelos SQL, seeds, macros e documentação (`docs/overview.md`, `docs/sources.md`, `docs/portal.html`). +- **`databricks.yml`** – Targets `dev`/`prd`, hosts e variáveis (ex.: `sql_warehouse_id`, `prod_root_path`). O target `prd` usa warehouse `7a2b912f6c29d8a8` e root path `/Workspace/Shared/srv_eng_prd/.bundle/${bundle.name}/${bundle.target}`. +- **`dbt_project.yml`** – Configura camadas (`silver` → schema `s`, `gold` → `g`, `seeds` → `b`), ativa `persist_docs` e flags (`use_materialization_v2`, `populate_by_name`). +- **`dbt_profiles/`** – Perfis `dev`/`prd` com catálogos (`rescue_dev`/`rescue_prd`), schemas padrão, `http_path` dos warehouses e tokens. +- **`resources/dabdbt.job.yml`** – Job do bundle com tasks `dbt_seed`, `dbt_silver`, `dbt_gold`, `dbt_docs`. Cada task referencia `warehouse_id: ${var.sql_warehouse_id}`. +- **`src/`** – Modelos SQL, seeds, macros (`apply_uc_tags`, `normalize_city`), documentação (`docs/*.md`). +- **`scripts/publish_docs.sh`** – Utilitário shell para sincronizar `target/docs` com o volume do Unity Catalog. +- **`notebooks/publish_docs.py`** – Notebook legado que publica docs direto no storage (mantido para referência, mas a publicação padrão agora é via GitHub Actions). --- -## 2. Fluxo dbt por camadas +## 2. Camadas e tags -| Camada | Localização | Artefatos | Descrição | Tags padrão | +| Camada | Catálogo/Schema | Principais artefatos | Finalidade | Tags aplicadas | | --- | --- | --- | --- | --- | -| Bronze | `rescue_dev.b` | `ibge_municipios` (seed) | Referência do IBGE com coordenadas e códigos oficiais | `layer:bronze`, `process:dbt` (definidos no seed) | -| Silver | `rescue_dev.s` | `customers_s`, `orders_s`, `order_items_s`, `order_payments_s` | Normaliza dados brutos do Azure SQL e enriquece com IBGE | `source:Azure SQL`, `process:dbt`, `layer:silver`, `data_owner:rescue` | -| Gold | `rescue_dev.g` | `customer_overview_g`, `order_fulfillment_g`, `item_sales_g`, `payment_performance_g`, `geo_heatmap_g`, `product_basket_g` | Métricas analíticas prontas para dashboards | `process:dbt`, `layer:gold`, `data_owner:rescue` | +| Bronze | `rescue_.b` | Seed `ibge_municipios` | Referência IBGE com coordenadas | `layer:bronze`, `process:dbt` | +| Silver | `rescue_.s` | `customers_s`, `orders_s`, `order_items_s`, `order_payments_s` | Normalização + enriquecimento dos dados transacionais | `source:Azure SQL`, `process:dbt`, `layer:silver`, `data_owner:rescue` | +| Gold | `rescue_.g` | `customer_overview_g`, `order_fulfillment_g`, `item_sales_g`, `payment_performance_g`, `geo_heatmap_g`, `product_basket_g` | Métricas analíticas e visões para dashboards | `process:dbt`, `layer:gold`, `data_owner:rescue` | -O macro `apply_uc_tags` garante que as tags acima sejam aplicadas em tabelas e colunas imediatamente após cada modelo ser materializado. +As tags são aplicadas automaticamente pela macro `apply_uc_tags` após cada materialização, garantindo consistência de metadados no Unity Catalog. --- -## 3. Executar com dbt CLI +## 3. Execução com dbt CLI (dev) ```bash cd dabdbt export DBT_PROFILES_DIR="$(pwd)/dbt_profiles" export DBT_HOST="https://adb-1293581597272291.11.azuredatabricks.net" export DBT_ACCESS_TOKEN="dapi" +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 ``` -Para visualizar os artefatos locais: `dbt docs serve`. +Para visualizar a documentação localmente: `dbt docs serve`. + +> Ajuste `DBT_PROD_HTTP_PATH` e tokens conforme necessário para testar o target `prd` localmente. --- -## 4. Deploy e execução via bundle +## 4. Deploy via Databricks Asset Bundles ```bash -# Deploy (sincroniza notebooks, job e recursos) +# Deploy sincroniza recursos (jobs, configs, notebooks) databricks bundle deploy --target dev --profile dev -# Executa o job completo +# Execução do job completo databricks bundle run dabdbt_job --target dev --profile dev ``` -### Estrutura do job -1. `dbt_seed` → `dbt seed --select ibge_municipios` -2. `dbt_silver` → `dbt run --select tag:silver` -3. `dbt_gold` → `dbt run --select tag:gold` -4. `dbt_docs` → `dbt docs generate --target-path=/Volumes/rescue_${bundle.target}/rescue_b/vol_docs/${bundle.name}` -5. `publish_docs` → notebook Python que lê os arquivos do volume e publica no storage `sarescuedev` usando o secret `pocdocdbt/sasdocsdbt` (ou as variáveis `AZURE_STORAGE_ACCOUNT`, `AZURE_STORAGE_CONTAINER`, `SAS_DOCS_TOKEN`). - -O job reutiliza o cluster single-node definido em `resources/dbt_single_node_cluster_spot.json`. Ajuste `existing_cluster_id` caso seja necessário apontar para outro cluster. +### Estrutura das tasks +1. `dbt_seed` – `dbt seed --select ibge_municipios --profiles-dir=dbt_profiles`. +2. `dbt_silver` – `dbt run --select tag:silver --profiles-dir=dbt_profiles`. +3. `dbt_gold` – `dbt run --select tag:gold --profiles-dir=dbt_profiles`. +4. `dbt_docs` – `dbt docs generate --target-path=/Volumes/rescue_${bundle.target}/rescue_b/vol_docs/${bundle.name}`. ---- +O notebook `publish_docs.py` permanece disponível para execução manual, mas a publicação padrão para os static websites ocorre pelos workflows do GitHub (ver README raiz). -## 5. Notebook `publish_docs.py` -- Determina dinamicamente o bundle (`dabdbt`) e target (`dev`/`prd`) para localizar os arquivos em `/Volumes/rescue_/rescue_b/vol_docs/`. -- Define `CONTENT_TYPES` para extensões comuns e utiliza `mimetypes.guess_type` como fallback. -- Em cada upload, aplica `content_settings` com `content_type` adequado e `content_disposition=inline`, garantindo que HTMLs sejam renderizados no navegador. -- Usa o secret scope `pocdocdbt` e a key `sasdocsdbt`. Em execuções locais, pode ler `SAS_DOCS_TOKEN`. +### Clusters e warehouses +- As tasks usam `warehouse_id: ${var.sql_warehouse_id}` (definido em `databricks.yml`). +- Para trocar o warehouse, configure `targets..variables.sql_warehouse_id` ou atualize o default. +- Caso queira executar em cluster, substitua `dbt_task` por `spark_python_task`/`notebook_task` conforme a necessidade e remova `warehouse_id`. --- -## 6. Publicação manual (opcional) -Se precisar enviar rapidamente os artefatos de `target/docs` para o storage sem passar pelo Databricks: +## 5. Publicação manual de documentação +Apesar de a publicação oficial acontecer via GitHub Actions, é possível sincronizar manualmente para depuração: ```bash -RESCUE_ENV=dev ./scripts/publish_docs.sh # sincroniza para o volume montado +# Copia docs locais para o volume montado (para teste em notebook) +RESCUE_ENV=dev ./scripts/publish_docs.sh +# Upload direto para o storage (hotfix) az storage blob upload \ --account-name sarescuedev \ --container-name '$web' \ --name dabdbt/index.html \ --file target/docs/index.html \ --overwrite \ - --account-key + --auth-mode login ``` -> Use esta abordagem apenas para hotfixes. O fluxo padrão deve ser o notebook `publish_docs.py`. +> Após uploads diretos, rode `az storage blob update --content-type 'text/html; charset=utf-8' --content-disposition inline` se o header não estiver correto. --- -## 7. Dicas de troubleshooting -- **Conteúdo baixando ao invés de abrir**: verifique `contentType` no blob com `az storage blob show`. Deve ser `"text/html; charset=utf-8"`. Se não estiver, reexecute a task `publish_docs`. -- **Erro `StorageCustomDomainNameNotValid` ao vincular domínio**: certifique-se de que o CNAME de `docsdev.rescuepoint.com.br` aponta diretamente para `sarescuedev.z13.web.core.windows.net` (cloudflare em modo “DNS only” durante a validação). -- **Secret não encontrado**: confira se o escopo `pocdocdbt` está disponível no workspace e se a key `sasdocsdbt` contém um SAS com permissão `acdl`. -- **Erros de autenticação no dbt**: renove o token e exporte novamente `DBT_ACCESS_TOKEN` (ou configure `~/.dbt/profiles.yml` para uso pessoal). +## 6. Troubleshooting +- **Warehouse inválido**: certifique-se de que `sql_warehouse_id` está ajustado no target (`f38fa7279458bb21` em dev, `7a2b912f6c29d8a8` em prd). +- **Erro de root path/ACL**: mantenha `prod_root_path` em `/Workspace/Shared/srv_eng_prd/.bundle/...` ou habilite ACLs no workspace. +- **Tags não aplicadas**: verifique logs do macro `apply_uc_tags`; ajuste permissões no catálogo se necessário. +- **Documentação não publicada**: confirme execução da task `dbt_docs` e se o workflow do GitHub atualizou o blob `dabdbt/index.html`. +- **Flag deprecation**: `populate_by_name` já está habilitado no `dbt_project.yml`; não reintroduzir `allow_population_by_field_name`. --- -## 8. Próximos passos -1. Adicionar testes (`dbt test`) e documentação de colunas diretamente nos `schema.yml`. -2. Configurar um ambiente `prd`, ajustando `variables.prod_root_path` em `databricks.yml` e `vars/prod.yml`. -3. Criar dashboards em Databricks SQL/Power BI consumindo os modelos gold. -4. Automatizar alertas (e-mail/Webhook) nas tasks críticas do job. +## 7. Próximos passos +- Adicionar `dbt test` e `snapshots/` conforme a evolução do pipeline. +- Padronizar grants automáticos via `grants.yml` no bundle. +- Integrar monitoramento (email/Slack) ao job ou aos workflows de deploy. +- Avaliar substituição do notebook de publicação por funções puramente declarativas (ex.: `sql_task` + Python wheel monitorada). -Com essas informações você consegue executar, depurar e evoluir a POC `dabdbt` dentro da plataforma da Rescue Point. +Para mais contexto sobre fontes, modelos e macros consulte `src/docs/*.md`. Para visão de automação/infra, veja o README na raiz do repositório. diff --git a/dabdbt/dbt_profiles/profiles.yml b/dabdbt/dbt_profiles/profiles.yml index d29c89a..3b240cc 100644 --- a/dabdbt/dbt_profiles/profiles.yml +++ b/dabdbt/dbt_profiles/profiles.yml @@ -28,6 +28,7 @@ dabdbt: token: "{{ env_var('DBT_ACCESS_TOKEN', '') or env_var('DATABRICKS_TOKEN', '') }}" retry_all: true connect_timeout: 60 + threads: 8 # The production target when deployed with the Databricks CLI prd: @@ -45,3 +46,4 @@ dabdbt: # see databricks.yml for the workspace host used for 'prod' host: "{{ env_var('DBT_HOST') }}" token: "{{ env_var('DBT_ACCESS_TOKEN') }}" + threads: 8