Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-10-04

BI-as-code — proyecto abierto e integración con Git

Exporta la definición del dashboard y del modelo como un JSON determinístico, versiónalo en Git, revísalo en un Pull Request y reimpórtalo con dry-run y resolución explícita de conflictos.

En esta página (11)

1. Qué es#

La definición de un dashboard — visuales, filtros, páginas, bookmarks, modelo (tablas, relaciones, columnas calculadas, KPI) y dependencias — exportada como un único archivo JSON determinístico, que puede versionarse en Git, revisarse en un Pull Request y reimportarse sin perder identidad. Es el equivalente al PBIP / la integración con Git de Fabric.

2. Cuándo usarlo#

  • Quieres un historial real de quién cambió qué en un panel, con revisión en PR.
  • Vas a promover un panel entre entornos (dev → test → prod) sin copiar datos — mira Entornos y promoción.
  • Necesitas probar lo que construiste sin exponer datos: la Ingestia Academy corrige los desafíos prácticos a partir de este archivo.
  • Quieres un respaldo legible de la estructura del panel.

3. Cómo funciona#

El formato (ProjetoBI)

jsonc
{
  "formatVersion": 2,
  "dashboard": {
    "id": "…",                 // preservado en el round-trip
    "name": "Vendas 2026",
    "widgets": [ { "id": "w…", "viz": "line", "sql": "…" } ],
    "pages": { … } | null,      // canvas + pestañas
    "filters": [ { "id": "…", "type": "select", … } ],
    "bookmarks": [ { "id": "…", "name": "…" } ]
  },
  "model": { "tables": [], "relations": [], "calcColumns": [], "kpis": [] },
  "dependencies": {
    "savedQueryIds": [],
    "semanticModelId": "…",     // cuando hay vínculo con el modelo central
    "tabelasReferenciadas": [ "dataset.tabela", … ]
  }
}

Determinismo (byte a byte). La exportación ordena las claves de objeto (recursivo, alfabético) y preserva el orden de los arrays (el orden de los widgets y de los filtros es semántico). El mismo proyecto genera exactamente los mismos bytes; el diff de Git solo aparece cuando el contenido cambia de verdad.

IDs preservados. Exportar nunca regenera un id: los widgets (w…), las columnas calculadas, los KPI y las jerarquías salen con el id que tienen en la base. Las relaciones no tienen id — la identidad es el propio vínculo (tabla.columna → tabla.columna). Por eso reimportar el mismo archivo es idempotente: todo aparece como inalterado.

El flujo Git

  1. Exportar

    Abre Dashboards → [panel] → Compartir y, en la tarjeta Proyecto (BI-as-code), usa Exportar proyecto. Descarga <nombre>-projeto.json.

  2. Commitear

    Guarda el archivo en el repositorio de la empresa (ej.: bi/<panel>/projeto.json):

    bash
    git add bi/vendas/projeto.json
    git commit -m "bi(vendas): ajusta KPI de receita"
    git push

--- Revisar en el PR Como el archivo está ordenado y es multilínea, cada campo alterado es una línea del diff. Sin ruido de reordenamiento. --- Reimportar En la misma tarjeta Proyecto (BI-as-code), elige el archivo revisado (hasta 1 MB, leído en tu navegador) y haz clic en Previsualizar (dry-run): el producto muestra la clasificación de cada entidad antes de grabar. Importar proyecto solo se habilita después de esa previsualización.

código

### Import: dry-run + resolución explícita de conflictos

| status        | significado                                             |
| ------------- | ------------------------------------------------------- |
| `novo`        | el id solo existe en el proyecto importado              |
| `inalterado`  | mismo id, contenido idéntico al actual                  |
| `conflito`    | mismo id, **contenido diferente** (con diff legible en el idioma de quien lee) |

**Un conflicto nunca se resuelve en silencio.** Sin una estrategia elegida, el import
**aborta y no graba nada**. Estrategias (en el selector **Estrategia en caso de
conflicto**): **`manter_meu`** — "Mantener el mío" (queda el contenido actual),
**`usar_deles`** — "Usar el del archivo" (entra el del archivo), y
**`abortar_em_conflito`** — "Abortar en conflicto", que es el **valor por defecto de la pantalla**.
El merge es **aditivo**: lo que solo existe en tu panel se preserva — importar nunca
borra lo que no enviaste.

## 4. Requisitos previos

- Ser el **dueño del workspace**: exportar, previsualizar e importar el proyecto
  definen el panel entero (definición + modelo), como duplicarlo o eliminarlo — la
  tarjeta está en la página **Compartir**, y el formulario de import aparece solo para
  el dueño.
- El panel necesita estar **guardado** (la exportación lee lo que está en la base, no lo que
  está en la pantalla sin guardar).
- Para promover entre entornos: workspaces hermanos en la misma
  [organización](../administracao/organizacao-e-workspaces.md).

## 5. Cómo validar

1. Exporta el panel; guarda el archivo A.
2. Reimporta A **sin cambiar nada**: el dry-run tiene que mostrar **solo `inalterado`**.
3. Exporta de nuevo (archivo B). `A` y `B` deben ser **idénticos byte a byte**
   (`diff A B` vacío).
4. Cambia el título de un widget en el archivo y reimporta: el dry-run muestra **un**
   `conflito`, con el diff de ese campo; cambia la estrategia a **"Usar el del
   archivo"** (`usar_deles`) y haz clic en **Importar proyecto**. Con la estrategia
   por defecto (abortar), el import rechaza y nada se graba.

## 6. Límites y advertencias

**Viaja en el proyecto (la definición):** ids de widgets, columnas calculadas, KPI y
jerarquías; visuales (tipo + SQL/configuración), filtros, bookmarks, página/canvas;
modelo; dependencias declaradas (`savedQueryIds`, `semanticModelId`,
`tabelasReferenciadas`).

**Queda en el entorno (NO migra):**

- **Datos y snapshots** — solo la definición viaja; el refresh repuebla los datos en el destino.
- **Secretos y credenciales** — conexiones, claves y tokens nunca entran en el archivo.
- **Programaciones e historial de ejecución** — cron, próximos disparos, ejecuciones.
- **Estado por persona** — vistas personales y favoritos.

Compatibilidad: `formatVersion` **corriente = 2**; la lectura acepta **2 y 1** (la
anterior sufre un _upgrade_ automático, `page` → `pages`). Un `formatVersion`
desconocido, un JSON roto o sin `formatVersion` es **rechazado** (fail-closed).
Los **pipelines** no entran en este formato — tienen su propio
[versionado](../orquestracao/publicar-e-versionar.md).

## 7. Datos de ejemplo (sintéticos)

Workspace **Aurora Varejo**: panel "Comercial Aurora" sobre `aurora_gold.vendas`,
`produtos`, `filiais` y `calendario`, con las medidas `Receita`, `Pedidos` y
`Ticket médio`. El archivo exportado tiene `dependencies.tabelasReferenciadas`
apuntando a esas cuatro tablas y `model.relations` con
`vendas.produto_id → produtos.id` y `vendas.filial_id → filiais.id`.

## 8. Evidencia

Suite determinística de **round-trip** (exportar → importar → exportar devuelve los
mismos bytes), de **ordenamiento canónico** (claves en cualquier orden → misma salida),
de **clasificación del dry-run** (nuevo / sin cambios / conflicto) y de **rechazo**
de un `formatVersion` desconocido.

**Relacionado:** [Editor, canvas, páginas y temas](editor-canvas-paginas-temas.md) ·
[Publicar y compartir](tutorial-publicar-e-compartilhar.md) ·
[Entornos y promoción](../administracao/ambientes-e-promocao.md).

Enlaces relacionados