Documentação para um projeto de BI
- Amanda Nascimento
- 23 de jun.
- 6 min de leitura
Atualizado: 29 de ago.
Documentar um projeto de BI vai muito além de criar tabelas... Precisamos entender a necessidade, mapear corretamente os dados, prever o crescimento futuro e garantir que qualquer profissional consiga dar manutenção no futuro com segurança.
Neste post vou mostrar passo a passo de como criei uma documentação e as ferramentas que utilizei. Dividi o projeto em quatro etapas, criei um sumário no Microsoft Word colocando o título dessas 4 etapas principais como Título 1 (principal) e os subtemas utilizei o Título 2 (secundário) e na medida em que fui desenvolvendo o projeto, fui preenchendo a documentação e no final, exportei para pdf e salvei como versão 01.
Um projeto bem documentado é sinônimo de transparência, controle e sucesso.
💻 Etapa 1: Detalhes do projeto
➡️ Nomes e áreas dos envolvidos
Quem são os demandantes do projeto?
Nome da área solicitante
Responsável técnico da área de negócios
P.O responsável
P.M.O responsável
Responsável B.I
➡️ Datas
Início do projeto
Conclusão Execução
Conclusão Homologação
Go-Live
Encerramento
➡️ Metodologia e repositório de scripts
Metodologia: Scrum, Kanban, etc (especificar)
Ferramenta de acompanhamento: (Jira, trello, etc)
Repositório: Github
➡️ Fluxo do processo
Utilizei o site (gratuito) https://app.diagrams.net/ para criar o diagrama
Exemplo:
🗣️ Etapa 2: Entendimento do Projeto com a Área de Negócios
Perguntas para a área de negócio:
Qual é o objetivo principal do projeto?
Quais decisões serão tomadas com base nesses dados?
Quais são as dores com o processo atual?
Quais são os indicadores (KPIs) mais importantes?
Quais são as métricas de cálculo dos indicadores?
Quem são os usuários finais do painel?
Qual o nível de detalhe esperado?
Glossário dos termos do negócio
Nome | Conceito |
Exemplo: ATM | ATM (Automated Teller Machine) caixa eletrônico, é um terminal de autoatendimento bancário instalado em agências ou locais públicos. |
Dados Sensíveis
O projeto possui dados sensíveis? Justifique o uso.
Quem pode acessar os dados?
É necessário inserir segurança de controle de acesso por usuário?
Quais filtros são considerados importantes para visualização dos dados?
Existe alguma outra observação que você gostaria de pontuar?
📌 Sempre valide com a área de negócio o que é considerado “correto” ou “esperado” para cada métrica.
🗣️ Etapa 3: Dados e atualizações
Existe alguma fonte de dados disponível? (API, servidor, arquivo txt, csv, Excel ou outros)
Há necessidade de exportação dos dados ou integração com outros sistemas?
A cada atualização, precisamos trazer todos os dados novamente ou apenas os novos/alterados?
☐Full Load: Reprocessa toda a base de dados (mais simples, porém mais pesado)
☐ Incremental Load: Apenas os dados novos ou modificados são trazidos (requer chave ou coluna de controle, como data_modificacao, data_inclusao, id, rowversion etc.)
Informe a frequência em que o dado é atualizado na origem.
☐Em tempo real
☐A cada 60 minutos
☐ 1x por dia
☐ 1x por semana
☐ Quinzenal
☐ Mensal
☐ Trimestral
Existe alguma informação que indique quando o dado foi criado ou alterado? Explique.
Qual o tempo necessário de base história deverá ser mantida?
☐hora ☐ Diário ☐Semanal ☐Quinzenal ☐Mensal ☐Trimestral ☐Semestral ☐Anual
☐Outro (Justifique).
Existe algum campo que nunca se repete e identifica cada linha de forma única (PK) para cada registro? Algo que nunca se repete, como um número de pedido, matrícula ou protocolo? Explique e nomeie os campos.
Existe alguma outra observação relevante sobre os dados?
Exemplo do formulário para auxiliar a etapa inicial
📊 Etapa 3: Planejamento da Arquitetura (Refinamento técnico)
➡️ Fonte dos dados
Nome da Fonte | Tipo | Origem | Formato | Acesso |
Planilha de Vendas | Arquivo | Enviado via e-mail | .xlsx | Pasta compartilhada / SharePoint |
Cadastro de Clientes | Banco | Sistema de CRM | Tabela SQL | Conexão ODBC: crm_db.clientes |
Cadastro de Produtos | Banco | ERP (Oracle) | Tabela SQL | Conexão Oracle: erp.produtos |
Calendário | Tabela Local | Tabela gerada em script | .csv | Local ou gerada por script de data |
➡️ Frequência da carga
Fonte | Frequência | Horário de Atualização | Observações |
Vendas (planilha) | Diária (manual) | Até 09h00 | E-mail automático do sistema de vendas |
Clientes (CRM) | Diário (automático) | 05h00 | Full Load |
Produtos (ERP) | Diário (automático) | 05h00 | Full Load |
Calendário | Única (estática) | - | Script Python para geração até 2030 |
➡️ Estrutura dos dados (camanda medalhão, bronze (stage), silver (ods) e camada ouro (dm_BI)
Tudo vai depender da necessidade do negócio mas neste caso, na camada stage será a carga incremental (comente novos registros), na camada ODS ficará o operacional, dado bruto contendo o histórico completo e os dados nos tipos corretos, exemplo, coluna de data, estará formatada como data, número como número, etc. É a famosa tabela tabelão!
Na camada DW falaremos mais para frente, mas é onde ficarão as nossas tabelas fato com as dimensões de filtro agregado ao invés de um tabelçao como na camada ODS.
Utilizarei procedures para levar os dados de camda a camada.
➡️ Tabelas envolvidas
Nome da Tabela | Fonte | Chaves | Comentário |
stage_vendas | Planilha Excel | id_venda | Ingestão bruta |
stage_clientes | CRM (SQL Server) | id_cliente | Importação direta |
stage_produtos | ERP (Oracle) | id_produto | Apenas produtos ativos |
➡️ Regras de negócio e tratamentos necessários
Regra de Negócio | Aplicação |
Não considerar vendas com valor total = 0 | Filtro em stage_vendas |
Clientes com estado nulo serão marcados como 'IGNORAR' | Regra em dim_cliente |
Produto descontinuado será mantido para histórico | Nenhum filtro aplicado |
Datas devem ter FK válida na dim_data | Carga rejeita datas inválidas |
Vendas duplicadas (mesmo ID) são ignoradas | duplicação por id_venda |
➡️ Caminho do dado
Exemplo:
Planilha Excel (.xlsx)
↓
Carga manual via script Python (ETL)
↓
Tabela stage_vendas
↓
Transformações, deduplicações
↓
Tabela fato_vendas (com FKs)
↓
Power BI conectado ao DM
➡️ Organização da Documentação no Projeto
/📁pasta
├── 01. Discovery (todo o material que recebermos das áreas envolvidas)
├── 02. Delivery (entrega final)
├── 03. Documentação (este arquivo word, diagramas, etc)
├── 04. Python
├── 05. T-SQL
└── 00. Integração
└── 01. Stage
└── 01. Table - Controle de Processamento.sql
└── 02. Table - Estrutura_Stage - Saldo.sql
└── 02. ODS
└── 01. Table - Saldo.sql
└── 02. Procedure - Carga table Saldo.sql
└── 03. DM
└── 01. Table - dimData.sql
└── 02. Table - dimOcorrencias.sql
└── 03. Table - dimFilial.sql
├── 06. SSIS (Integration Service)
├── 07. SSAS (Analysis Services)
├── 08. Power BI
└── 01. Relatórios
└── 02. Script TMDL
➡️ Ferramentas e linguagens utilizadas
ETL: SSIS (Visual Studio)
Banco de dados: SQL Server (Servidor BI)
Linguagens: SQL e Python
Visualização: Power BI
➡️ Governança e segurança
Quem pode acessar os dados?
Quais são as camadas de acesso?
➡️ Diagrama
Criei o diagrama gratuitamente no site: https://dbdiagram.io/d/
🛠️ Etapa 4: Desenvolvimento e Documentação técnica
➡️ Dados alocados em: Nome servidor BI ➡️ Schema: Nome schema
➡️ Tabelas - Camada Stage e ODS (INPUT)
Para cada tabela de stage, documente:
Nome da tabela
Origem dos dados
Descrição de cada coluna
Tipo de dado
Observações (formato, nulos, padrões, etc.)
📄 Exemplo: Documentação Técnica da Camada Stage (faça isso para todas as tabelas)
Tabela: stage_vendas
Coluna | Tipo de dado | Descrição |
id_venda | INT | Identificador único da venda |
data_venda | DATE | Data em que a venda foi realizada |
id_produto | INT | Chave estrangeira para produto |
id_cliente | INT | Chave estrangeira para cliente |
valor_total | DECIMAL(10,2) | Valor total da venda |
➡️ Camada DM - DataMart (Output)
Qual tipo de modelagem utilizada?
☒ Estrela ☐ Floco de Neve ☐ 3FN ☐Data Vault
Quais são as tabelas de dimensões?
Nome da Tabela | Tipo | Comentário |
DimData | Dimensão | Calendário completo: dia, mês, ano, feriados, semana, etc. |
DimStatusK7 | Dimensão | Status/classificações do processo K7. |
DimOcorrencias | Dimensão | Tipos de ocorrência, categorias e descrições. |
DimFilial | Dimensão | Informações da filial: código, nome, cidade, UF, regional. |
DimCicloContabil | Dimensão | Períodos/fechamentos contábeis: ciclo, competência, ano fiscal. |
DimIdK7 | Dimensão | Identificadores e atributos do K7 (chaves e metadados). |
DimIdATM | Dimensão | Identificação do ATM/terminal: código, localização, tipo, status. |
DimTipoNotas | Dimensão | Denominações/tipos de cédulas (ex.: R$ 10, R$ 20, R$ 50, etc.). |
Qual o relacionamento entre as tabelas e quais são as chaves primárias e chaves secundárias de cada tabela fato?
Quais são as tabelas fato?
Diagrama DM
Utilizei o site https://app.diagrams.net/ para fazer o diagrama abaixo, mas também poderia usar o Microsoft Power Point, Paint, canvas, figma, etc.
Algumas ferramentas para auxiliar
Ferramenta | Foco | Gratuito? | Link |
Diagramas em geral | ✅ 100% | ||
ERD a partir de código | ✅ Sim | ||
Lucidchart | Apresentações e colaboração | ⚠️ Parcial | |
Creately | Visuais corporativos diversos | ⚠️ Parcial | |
Whimsical | Fluxos e UX | ⚠️ Parcial | |
Figma | Design e prototipagem colaborativa (inclui fluxos e diagramas) | ✅ Sim (versão free) | |
Canva | Design gráfico e diagramas simples | ✅ Sim (versão free) |
