Exportar projeto JSON, diff no Git, importar com dry-run

Selo de estado: Preview (teto atual do produto) · Curso ACD-340 — Publicação, distribuição, RLS e BI-as-code · Aula 7 de 8 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai exportar, ler diff, importar resolvendo conflito.

Vídeo#

Identificador no manifesto: acd-340-07-bi-as-code-exportar-importar · duração-alvo 9 min · tela do produto: /dashboards.

Roteiro (capítulos):

1. 00:00–01:30 — O que viaja no projeto (e o que fica no ambiente, como credenciais e dados).
2. 01:30–03:30 — Exportar projeto: o JSON determinístico, chaves ordenadas, ids preservados.
3. 03:30–05:30 — Commitar e revisar no Git: por que o diff é legível, campo por campo.
4. 05:30–07:30 — Reimportar: o dry-run e os três status (novo, inalterado, conflito).
5. 07:30–08:30 — Resolvendo um conflito de propósito (manter_meu × usar_deles).
6. 08:30–09:00 — Erros comuns e encerramento.

Conteúdo#

BI-as-code trata a definição de um dashboard — visuais, filtros, páginas, bookmarks e o modelo (tabelas, relações, colunas calculadas, KPIs) — como um arquivo só, um JSON determinístico que pode viver num repositório Git, ser revisado em Pull Request e reimportado sem perder identidade. É o equivalente, no ingestia.bi, ao PBIP e à integração Git do Fabric: em vez de um binário opaco, você tem texto legível por humanos e por um git diff.

Como aparece no produto. No painel, a ação Exportar projeto baixa um arquivo <nome>-projeto.json. Duas garantias tornam esse arquivo útil como artefato de versionamento: determinismo byte a byte (a exportação ordena as chaves de objeto, recursivamente, em ordem alfabética, e preserva a ordem dos arrays — então o mesmo projeto gera exatamente os mesmos bytes, e o diff do Git só aparece quando o conteúdo muda de verdade) e ids preservados (widgets, colunas calculadas, KPIs e hierarquias saem com o id que já têm no banco — nada é regenerado). Depois de guardar o arquivo no repositório da empresa e abrir um Pull Request, cada campo alterado aparece como uma linha do diff, sem ruído de reordenação. Para trazer o arquivo de volta, você reimporta no painel — e antes de gravar qualquer coisa, o produto roda um dry-run: cada entidade do projeto importado recebe um status entre novo (o id só existe no arquivo), inalterado (mesmo id, mesmo conteúdo) ou conflito (mesmo id, conteúdo diferente, com o diff daquele campo em pt-BR). Um conflito nunca é resolvido em silêncio — sem uma estratégia escolhida explicitamente, o import aborta e não grava nada. As estratégias disponíveis são manter_meu (fica o que já está no painel), usar_deles (entra o que vem do arquivo) e abortar_em_conflito (o padrão implícito, se você não decidir). O merge, sempre, é aditivo: o que só existe no seu painel é preservado — importar nunca apaga o que você não mandou no arquivo.

Exemplo Aurora. A Aurora Varejo exporta o painel "Comercial Aurora", construído sobre aurora_gold.vendas, produtos, filiais e calendario, com as medidas Receita, Pedidos e Ticket médio. O arquivo A resultante tem dependencies.tabelasReferenciadas apontando para essas quatro tabelas e model.relations com vendas.produto_id → produtos.id e vendas.filial_id → filiais.id. Reimportar o arquivo A sem mudar nada deve mostrar só inalterado em cada entidade — é o teste de idempotência. Exportar de novo (arquivo B) deve produzir bytes idênticos ao arquivo A. Agora, alguém edita o título de um widget direto no arquivo e reimporta: o dry-run mostra um conflito, com o diff daquele campo específico; a pessoa escolhe usar_deles e confirma na tela — e só esse widget muda, o resto do painel permanece como estava.

Erros comuns. O primeiro é achar que o arquivo exportado leva dados — ele leva só a definição: snapshots, segredos, credenciais de conexão, agendamentos e histórico de execução nunca entram no projeto; no destino, você usa as conexões de lá e roda o refresh para repopular os dados. O segundo é deixar um conflito sem estratégia escolhida e se surpreender quando "nada parece ter acontecido" — é exatamente o comportamento esperado: sem decisão explícita, o import aborta e não grava nada, de propósito, para nunca sobrescrever silenciosamente o trabalho de outra pessoa. O terceiro é temer que reimportar vá apagar widgets ou filtros que só existem no painel atual e não no arquivo — não existe esse risco, porque o merge é estritamente aditivo.

Estado do produto. O motor é provado por uma suíte de round-trip (exportar → importar → exportar devolve os mesmos bytes), de ordenação canônica e de classificação do dry-run — determinístico, com resultado idêntico a cada execução. O que falta para sair de Preview é a validação em nuvem com painéis reais em volume e a homologação humana do fluxo de Pull Request dentro do repositório de um cliente de verdade — por isso o selo desta aula é Preview, sem SLA. Vale notar que esse mesmo par diff→aprovar→aplicar é a base do fluxo de promoção entre ambientes (dev → test → prod), coberto em Ambientes e promoção — ali a diferença é que a promoção também exige que quem aprova não seja quem promove.

Faça você mesmo#

Este é o mesmo arquivo (ProjetoBI) usado nos desafios práticos da Ingestia Academy — vale a pena dominar o fluxo aqui. No workspace de treino Aurora Varejo (abra /dashboards no console):

1. Abra um painel publicado e salvo (o export lê o banco, não o rascunho sem salvar) e use Exportar projeto. Guarde o arquivo A.
2. Reimporte o arquivo A sem alterar nada e confirme que o dry-run mostra só inalterado em todas as entidades.
3. Exporte de novo (arquivo B) e confirme que A e B são idênticos byte a byte (diff A B vazio, se você tiver acesso a uma linha de comando; ou compare o tamanho e o conteúdo visualmente).
4. Abra o arquivo A num editor de texto e altere o título de um widget.
5. Reimporte o arquivo alterado e confirme que o dry-run mostra um conflito, com o diff daquele campo.
6. Escolha a estratégia usar_deles e confirme a importação na tela.
7. Confirme que só o título daquele widget mudou — o resto do painel permanece intacto.
8. (Opcional) Repita o passo 4 escolhendo manter_meu desta vez, e confirme que o painel não muda.

Você terminou quando tiver passado pelos três status do dry-run (novo, inalterado, conflito) pelo menos uma vez cada, e conseguir explicar por que reimportar nunca apaga o que só existe no seu painel.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• bi/bi-as-code
• administracao/ambientes-e-promocao

Capacidades ensinadas#

C12.2 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".