Lee antes:
README.md(vocabulario + plantilla). Incremental/backfill/checkpoint están eningestao-incremental-backfill.md; programación/retry/DLQ enagendamento-retry-dlq.md.
Las dos pistas en vivo#
El producto muestra el progreso en tiempo real con pasos serializables (cliente + servidor).
Ingesta de una fuente (detalle del pipeline /sources/[id], sección "Tablas de Bronze" → "Ingerir en vivo"):
validar → landing → bronze → registrarvalidar— verifica la conexión y las credenciales cifradaslanding— envía los datos brutos a la landingbronze— carga verbatim en la capa Bronze del datalakeregistrar— actualiza el catálogo y la última sincronización (grabalastSyncAt)
Pipeline de ingeniería (página /pipeline):
ingest → bronze → silver → gold → publishQué hace cada capa (implementación de referencia determinista)#
El pipeline tiene una implementación de referencia (en dev corre sobre SQLite; los mismos
contratos valen en el datalake por workspace). Datos de ejemplo: una tabla sintética
vendas con columnas pedido_id, data_pedido, cliente_id, uf, categoria, produto, preco_unitario, quantidade, forma_pagamento, status.
Bronze — crudo, verbatim, auditable
- Ingesta en una transacción, con el tipo de cada columna detectado por los valores
(archivo) o tomado del origen (base de datos), y marcas técnicas. Un identificador solo con
dígitos (CPF, CEP) se lee como número y pierde el cero a la izquierda: envíalo
formateado. Una columna
datede base de datos llega como fecha y hora (medianoche). - Garantiza el número de campos (rellena los faltantes con
"") — nunca descarta una fila en Bronze. - En el camino SaaS/landing, los brutos van a
landing/<prefix>/_saas/<sourceId>/<stamp>/<tabela>/chunk-NNNN.jsonen NDJSON (un objeto por línea), y después una única carga lee todos los fragmentos.
Silver — limpieza, tipado, calidad y deduplicación
Reglas de calidad aplicadas fila por fila (un rechazo = fila descartada, contada en rejectedRows):
| Regla | Comportamiento |
|---|---|
Status cancelado | descartado |
| Cantidad | entero > 0; si no, se descarta |
| Precio | parsea formato brasileño (1.299,90) y estadounidense (199.90); > 0; si no, se descarta |
| Fecha | YYYY-MM-DD válida; si no, se descarta; deriva mes = YYYY-MM |
| Estado (UF) | se normaliza a 2 letras mayúsculas; si no, se descarta |
pedido_id | obligatorio |
| Categoría vacía | se convierte en "Sem categoria" (no se descarta) |
| Deduplicación | por pedido_id, conserva la 1.ª ocurrencia |
receita | derivada = preco_unitario × quantidade |
rejectedRows = bronzeRows − silverRows — la diferencia siempre está visible (nada desaparece en silencio).
Gold — datamarts agregados
Marts recreados en cada ejecución (idempotente): gold_receita_mensal, gold_receita_uf,
gold_receita_categoria (con share), gold_kpis (una sola fila: ingresos totales,
pedidos, ticket promedio, n.º de estados, período). Cada ejecución graba un pipeline_runs
(bronze/silver/rechazadas/marts/duración/KPIs).
Publish
El upsert del dashboard gold republica el panel público (published: true) — ejecutar
el pipeline hace que los datos gold sean visibles sin acción manual.
Ficha (plantilla de 9 campos)#
- Estado — disponible. Pipeline cubierto por pruebas automáticas y ejecutado en el datalake de cada workspace.
- Qué hace — lleva los datos desde la origen hasta marts Gold listos para dashboard, pasando por calidad y deduplicación en Silver.
- Cómo funciona — medallón Bronze→Silver→Gold; Bronze verbatim, Silver con reglas de calidad + dedupe, Gold agregado. Datasets por workspace
<prefix>_bronze/_silver/_gold. - Plan · Permiso — núcleo · verificación de acceso · interruptores de apagado para la ejecución de ingesta (carga) y la actualización de paneles (republicar).
- Costo — las cargas y consultas en el datalake son cobrables; el costo lo estima el motor de costos y lo limita un tope de bytes facturables (ver
custo-limites-seguranca.md). - Límites — profiling: tope de 50 columnas, 5 ejemplos × 60 caracteres, payload de 32 KiB; carga SaaS por defecto
batchSize 5.000/maxRows 200.000. - Seguridad — datasets/buckets acotados por workspace; nombres de columna interpolados solo a partir de una allowlist; PII enmascarada en el profiling.
- Cómo validar — en la consola, ejecuta el pipeline de un workspace de ejemplo y revisa, en la pantalla de ejecución, los contadores Bronze/Silver/rechazadas y los marts Gold generados; el panel gold se republica automáticamente al final.
- En resumen — pipeline medallón Bronze→Silver→Gold con calidad y deduplicación.
Profiling del catálogo (muestra segura)#
El profiling es puro. Dada una muestra + el esquema, calcula por columna: tipo declarado × inferido (divergencia = señal de suciedad), % de nulos, n.º de distintos (siempre una estimación), mín./máx. de numéricos/fechas, longitud promedio de texto y hasta 5 ejemplos.
Seguridad incorporada (el motivo por el que el módulo existe por separado):
- Columna PII → los ejemplos se convierten en
•••; mín./máx./distintos/longitud suprimidos (solo sobrevive el % de nulos). - Columna oculta (gobernanza) → ni siquiera aparece (el nombre no viaja).
- Topes: 50 columnas, ejemplo de 60 caracteres, payload total ≤ 32 KiB (se corta con aviso).
Schema drift (el mart no se rompe en silencio)#
El esquema descubierto se convierte en una línea base serializable y se compara línea base × actual:
| Cambio | Severidad | Efecto |
|---|---|---|
| columna/tabla nueva | info | aditivo — el mart no se rompe |
| columna eliminada | atencao | el mart que la lee se rompe |
| tipo cambiado | atencao | el cast/agregación aguas abajo se rompe |
| tabla eliminada | atencao | — |
La severidad es la peor encontrada; el mart se marca como "se rompe" cuando hay atencao.
Saneamiento automático de la carga (el pipeline no se rompe por un nombre de clave)#
El saneamiento es el plan B de la carga en el datalake: la ingesta programada trae archivos de los
sistemas del cliente directo a la landing — claves con acento/espacio/vacías
("preço", "nome do cliente") tumbarían el load ("Invalid field name"). Cuando el
load NDJSON falla, el archivo se sanea (minúsculas, sin acento, _; vacía → coluna;
empieza con número → col_) y se vuelve a cargar. También desenvuelve envoltorios ({meta..., data:[...]})
y convierte array/pretty-JSON a NDJSON. Regla conservadora: una línea no parseable se
mantiene tal cual (no inventa datos).
Transformaciones (Silver→Gold como código versionado)#
Las transformaciones de negocio son una IR versionada compilada a SQL determinista (pasos en portugués: reemplazar, texto, fechas, dividir, condicional; group-by/joins con prevención de fan-out consciente del grano). El versionado, la ejecución paralela de verificación y el rollback están cubiertos por pruebas automáticas. Las salidas están congeladas por el conjunto de pruebas de referencia, con resultado idéntico en cada ejecución.