Entrega Parquet (S3)

Además del acceso SQL directo, Sincronización y Datos puede entregar el modelo de datos de tu cuenta como archivos Parquet en un bucket S3 compartido. Cada entrega es un lote (una carpeta con un snapshot de todas las tablas en ese momento).

Los nombres de columnas y tipos coinciden con el modelo documentado en esta sección. Los id son los mismos que devuelve la API pública (CS…, PY…, etc.).

Estructura en S3

Tu cuenta tiene un prefijo propio dentro del bucket (por ejemplo mi-organizacion/). Cada corrida de exportación crea una carpeta directamente bajo ese prefijo:

{tu-prefijo}/{YYYY_MM_DD_HHMMSS}_{modo}/{tabla}.parquet

Segmento	Significado
tu-prefijo	Carpeta asignada a tu cuenta en el bucket
YYYY_MM_DD_HHMMSS	Fecha y hora UTC en que empezó la corrida (2025_06_18_143022)
modo	full o incremental
tabla	Nombre de la entidad (customers, payments, …)

Ejemplo

Supongamos que tu prefijo es mi-organizacion:

mi-organizacion/
├── 2025_06_18_143022_full/
│   ├── customers.parquet
│   ├── payments.parquet
│   └── subscriptions.parquet
├── 2025_06_19_010000_incremental/
│   ├── customers.parquet
│   └── payments.parquet
└── 2025_06_20_091500_full/
    ├── customers.parquet
    └── payments.parquet

Cada carpeta es una corrida completa: incluye un archivo .parquet por entidad del modelo de datos. Una corrida está lista cuando están todos los archivos esperados de ese lote.

Consumo en orden cronológico (FIFO)

El diseño está pensado para que puedas listar las carpetas en la raíz de tu prefijo y procesarlas de la más antigua a la más nueva:

1. Listar prefijos bajo s3://…/{tu-prefijo}/ (delimiter /).
2. Ordenar los nombres ascendente — el formato YYYY_MM_DD_HHMMSS ordena correctamente en el tiempo.
3. Tomar la carpeta más antigua que aún no procesaste.
4. Leer todos los .parquet de esa carpeta.
5. Aplicar la lógica según el modo (full o incremental, ver abajo).
6. Marcar la carpeta como procesada y pasar a la siguiente.

No hace falta borrar carpetas antiguas para saber cuál sigue: el orden del nombre indica qué viene después. Registra en tu sistema qué carpetas ya ingestaste (checkpoint por nombre de carpeta).

Orden lexicográfico = orden cronológico

2025_06_18_143022_full → 2025_06_19_010000_incremental → 2025_06_20_091500_full es el orden correcto de procesamiento.

Modos de corrida

Modo	Contenido	Cuándo usarlo
full	Todas las filas de cada tabla en ese momento	Carga inicial, reconstrucción de base, corrección mayor
incremental	Filas publicadas recientemente (ventana ~26 h): las que cambiaron en ese lapso, más las que cambiaron antes pero recién llegaron al warehouse ahora	Actualización diaria sobre una base full ya cargada

• Tras un full, reemplaza en tu warehouse la foto completa de cada tabla (o las tablas afectadas).
• Tras un incremental, haz merge o upsert de las filas nuevas o cambiadas. Para el cursor de ingesta dentro de los archivos, usa dw_loaded_at (ver Convenciones).

Las corridas incremental suelen publicarse una vez al día. Un full se dispara cuando acordamos una recarga completa (por ejemplo, tras un cambio de esquema o una corrección de datos).

Llegadas tardías

Una fila cuyo cambio en origen quedó fuera de la ventana, pero que recién ahora llega a nuestro warehouse, se publica igual en el incremental con su dw_loaded_at actualizado. Por eso tu cursor la toma como novedad aunque su updated_at sea viejo.

Este rescate cubre cambios de hasta 14 días de antigüedad. Si una interrupción prolongada dejara algo afuera de esa ventana, hace falta un full para recuperarlo: lo detectamos de nuestro lado y lo coordinamos con vos.

Retención en el bucket

Por política de retención, los archivos con varios días de antigüedad se eliminan automáticamente del bucket. No uses el bucket como archivo histórico a largo plazo: ingresa cada carpeta en tu data warehouse y conserva el historial allí.

Si necesitas reprocesar un periodo que ya salió del bucket, contacta a soporte@debi.pro para coordinar un nuevo full.

Formato

• Formato de archivo: Apache Parquet (columnar, comprimido).
• Compatibilidad: Cualquier motor que lea Parquet (Spark, DuckDB, Athena, BigQuery load, Snowflake stage, etc.).
• Esquema: El de las tablas en Modelo de datos y Convenciones.