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

Pipeline de datos — Bronze, Silver y Gold

Las tres capas del datalake, qué guarda cada una y cómo las transformaciones conectan una con otra.

En esta página (11)

Lee antes: README.md (vocabulario + plantilla). Incremental/backfill/checkpoint están en ingestao-incremental-backfill.md; programación/retry/DLQ en agendamento-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"):

código
validar → landing → bronze → registrar
  • validar — verifica la conexión y las credenciales cifradas
  • landing — envía los datos brutos a la landing
  • bronze — carga verbatim en la capa Bronze del datalake
  • registrar — actualiza el catálogo y la última sincronización (graba lastSyncAt)

Pipeline de ingeniería (página /pipeline):

código
ingest → bronze → silver → gold → publish

Qué 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 date de 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.json en 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):

ReglaComportamiento
Status canceladodescartado
Cantidadentero > 0; si no, se descarta
Precioparsea formato brasileño (1.299,90) y estadounidense (199.90); > 0; si no, se descarta
FechaYYYY-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_idobligatorio
Categoría vacíase convierte en "Sem categoria" (no se descarta)
Deduplicaciónpor pedido_id, conserva la 1.ª ocurrencia
receitaderivada = 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)#

  1. Estado — disponible. Pipeline cubierto por pruebas automáticas y ejecutado en el datalake de cada workspace.
  2. Qué hace — lleva los datos desde la origen hasta marts Gold listos para dashboard, pasando por calidad y deduplicación en Silver.
  3. 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.
  4. 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).
  5. 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).
  6. 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.
  7. Seguridad — datasets/buckets acotados por workspace; nombres de columna interpolados solo a partir de una allowlist; PII enmascarada en el profiling.
  8. 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.
  9. 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:

CambioSeveridadEfecto
columna/tabla nuevainfoaditivo — el mart no se rompe
columna eliminadaatencaoel mart que la lee se rompe
tipo cambiadoatencaoel cast/agregación aguas abajo se rompe
tabla eliminadaatencao—

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.

Enlaces relacionados