BI-as-code — projeto aberto e integração Git — ingestia.io Documentation

This page has not been translated yet — you are reading the Portuguese version. View in Portuguese

Selo de estado: Preview (limite atual do produto) · Atualizado em 2026-10-04. Fonte de estado: matriz de estados do produto. Sem SLA.

1. O que é#

A definição de um dashboard — visuais, filtros, páginas, bookmarks, modelo (tabelas, relações, colunas calculadas, KPIs) e dependências — exportada como um único arquivo JSON determinístico, que pode ser versionado no Git, revisado em Pull Request e reimportado sem perder identidade. É o equivalente ao PBIP / integração Git do Fabric.

2. Quando usar#

Quer histórico real de quem mudou o quê num painel, com revisão em PR.
Vai promover um painel entre ambientes (dev → test → prod) sem copiar dado — veja Ambientes e promoção.
Precisa provar o que construiu sem expor dado: a Ingestia Academy corrige os desafios práticos a partir deste arquivo.
Quer um backup legível da estrutura do painel.

3. Como funciona#

O formato (`ProjetoBI`)

jsonc

{
  "formatVersion": 2,
  "dashboard": {
    "id": "…",                 // preservado no round-trip
    "name": "Vendas 2026",
    "widgets": [ { "id": "w…", "viz": "line", "sql": "…" } ],
    "pages": { … } | null,      // canvas + abas
    "filters": [ { "id": "…", "type": "select", … } ],
    "bookmarks": [ { "id": "…", "name": "…" } ]
  },
  "model": { "tables": [], "relations": [], "calcColumns": [], "kpis": [] },
  "dependencies": {
    "savedQueryIds": [],
    "semanticModelId": "…",     // quando houver vínculo com modelo central
    "tabelasReferenciadas": [ "dataset.tabela", … ]
  }
}

Determinismo (byte a byte). A exportação ordena as chaves de objeto (recursivo, alfabético) e preserva a ordem dos arrays (a ordem de widgets e filtros é semântica). O mesmo projeto gera exatamente os mesmos bytes; o diff do Git só aparece quando o conteúdo realmente muda.

IDs preservados. Exportar nunca regenera id: widgets (w…), colunas calculadas, KPIs e hierarquias saem com o id que têm no banco. Relações não têm id — a identidade é a própria ligação (tabela.coluna → tabela.coluna). Por isso reimportar o mesmo arquivo é idempotente: tudo aparece como inalterado.

O fluxo Git

Exportar
Abra Dashboards → [painel] → Compartilhar e, no card Projeto (BI-as-code), use Exportar projeto. Baixa <nome>-projeto.json.
2
Commitar
Guarde o arquivo no repositório da empresa (ex.: bi/<painel>/projeto.json):
bash
```
git add bi/vendas/projeto.json
git commit -m "bi(vendas): ajusta KPI de receita"
git push
```

--- Revisar no PR Como o arquivo é ordenado e multilinha, cada campo alterado é uma linha do diff. Sem ruído de reordenação. --- Reimportar No mesmo card Projeto (BI-as-code), escolha o arquivo revisado (até 1 MB, lido no seu navegador) e clique em Pré-visualizar (dry-run): o produto mostra a classificação de cada entidade antes de gravar. Importar projeto só habilita depois dessa pré-visualização.

code


### Import: dry-run + resolução explícita de conflito

| status        | significado                                             |
| ------------- | ------------------------------------------------------- |
| `novo`        | id só existe no projeto importado                       |
| `inalterado`  | mesmo id, conteúdo idêntico ao atual                    |
| `conflito`    | mesmo id, **conteúdo diferente** (com diff legível no idioma de quem lê) |

**Conflito nunca é resolvido em silêncio.** Sem uma estratégia escolhida, o import
**aborta e não grava nada**. Estratégias (no seletor **Estratégia em caso de
conflito**): **`manter_meu`** — "Manter o meu" (fica o conteúdo atual),
**`usar_deles`** — "Usar o do arquivo" (entra o do arquivo), e
**`abortar_em_conflito`** — "Abortar em conflito", que é o **padrão da tela**.
O merge é **aditivo**: o que só existe no seu painel é preservado — importar nunca
apaga o que você não mandou.

## 4. Pré-requisitos

- Ser o **dono do workspace**: exportar, pré-visualizar e importar o projeto
  definem o painel inteiro (definição + modelo), como duplicar ou excluir — o
  card fica na página **Compartilhar**, e o formulário de import aparece só para
  o dono.
- O painel precisa estar **salvo** (o export lê o que está no banco, não o que
  está na tela sem salvar).
- Para promover entre ambientes: workspaces irmãos na mesma
  [organização](../administracao/organizacao-e-workspaces.md).

## 5. Como validar

1. Exporte o painel; guarde o arquivo A.
2. Reimporte A **sem mudar nada**: o dry-run precisa mostrar **só `inalterado`**.
3. Exporte de novo (arquivo B). `A` e `B` devem ser **idênticos byte a byte**
   (`diff A B` vazio).
4. Altere o título de um widget no arquivo e reimporte: o dry-run mostra **um**
   `conflito`, com o diff daquele campo; troque a estratégia para **"Usar o do
   arquivo"** (`usar_deles`) e clique em **Importar projeto**. Com a estratégia
   padrão (abortar), o import recusa e nada é gravado.

## 6. Limites e ressalvas

**Viaja no projeto (a definição):** ids de widgets, colunas calculadas, KPIs e
hierarquias; visuais (tipo + SQL/config), filtros, bookmarks, página/canvas;
modelo; dependências declaradas (`savedQueryIds`, `semanticModelId`,
`tabelasReferenciadas`).

**Fica no ambiente (NÃO migra):**

- **Dados e snapshots** — só a definição viaja; o refresh repopula os dados no destino.
- **Segredos e credenciais** — conexões, chaves e tokens nunca entram no arquivo.
- **Agendamentos e histórico de execução** — cron, próximos disparos, execuções.
- **Estado por pessoa** — visões pessoais e favoritos.

Compatibilidade: `formatVersion` **corrente = 2**; a leitura aceita **2 e 1** (a
anterior sofre _upgrade_ automático, `page` → `pages`). `formatVersion`
desconhecido, JSON quebrado ou sem `formatVersion` é **recusado** (fail-closed).
**Pipelines** não entram neste formato — têm o próprio
[versionamento](../orquestracao/publicar-e-versionar.md).

## 7. Dados de exemplo (sintéticos)

Workspace **Aurora Varejo**: painel "Comercial Aurora" sobre `aurora_gold.vendas`,
`produtos`, `filiais` e `calendario`, com as medidas `Receita`, `Pedidos` e
`Ticket médio`. O arquivo exportado tem `dependencies.tabelasReferenciadas`
apontando para essas quatro tabelas e `model.relations` com
`vendas.produto_id → produtos.id` e `vendas.filial_id → filiais.id`.

## 8. Evidência

Suíte determinística de **round-trip** (exportar → importar → exportar devolve os
mesmos bytes), de **ordenação canônica** (chaves em qualquer ordem → mesma saída),
de **classificação do dry-run** (novo / inalterado / conflito) e de **recusa**
de `formatVersion` desconhecido.

## 9. Estado & maturidade

`Preview`. O motor é provado por testes com resultado idêntico a cada execução;
falta a validação em nuvem com painéis reais em volume e a homologação humana do
fluxo de PR em um repositório de cliente. Sem SLA.

**Relacionado:** [Editor, canvas, páginas e temas](editor-canvas-paginas-temas.md) ·
[Publicar e compartilhar](tutorial-publicar-e-compartilhar.md) ·
[Ambientes e promoção](../administracao/ambientes-e-promocao.md).

1. O que é#

2. Quando usar#

3. Como funciona#

O formato (ProjetoBI)

O fluxo Git

Related links

O formato (`ProjetoBI`)