Convenciones
Antes de empezar a consultar tablas, conviene tener claras las reglas que se repiten en todo el modelo: cómo se forman los IDs, cómo se manejan los timestamps, qué pasa con las filas eliminadas, cómo se expresan los importes y la moneda, etc. Estas convenciones no van a cambiar de manera silenciosa: cualquier cambio se anuncia con al menos 30 días de antelación.
Identificadores
Todas las columnas id y *_id son identificadores públicos con prefijo (CSljikas98, PYa8EJ1DkDnY, SBmQ6j9NWxblNv…) que devuelve la API REST pública.
Prefijos de ID
| Tabla | Prefijo |
|---|---|
customers | CS |
payments | PY |
payment_methods | PM |
subscriptions | SB |
mandates | MA |
sessions | SS |
links | LK |
gateways | GW |
events | EV |
webhooks | WH |
Timestamps
RFC3339 con offset de zona horaria (por ejemplo, 2022-02-11T23:19:22-03:00).
Soft deletes
Las filas soft-deleted se filtran automáticamente en la mayoría de los recursos. customers, links y payments exponen deleted_at para que se pueda ver cuándo se desactivó un objeto.
Metadata
metadata es un objeto JSON libre que el tenant puede adjuntar a los recursos vía API. Los valores son strings, números, booleanos o null. Máximo 500 caracteres por valor.
Currency
Códigos ISO 4217 (ARS, BRL, CLP, COP, MXN, USD, …). Los importes son decimales en la unidad mayor de la moneda (por ejemplo, 12.50 ARS, no centavos).
Country
ISO 3166-1 alpha-2 (AR, BR, MX, …).
Columnas de auditoría
Todas las tablas incluyen created_at y updated_at provenientes de la aplicación de origen. Reflejan cuándo se creó y cuándo se modificó por última vez la fila en el sistema fuente, y por eso no son adecuadas como cursor de ingesta. Para lecturas incrementales hay que usar dw_loaded_at (ver más abajo).
dw_loaded_at y cursor incremental
Todas las tablas exponen además una columna dw_loaded_at: el timestamp en que la fila fue publicada al warehouse. Es la columna que hay que usar como cursor incremental cuando se ingestan cambios o se asignan punteros desde un sistema externo.
dw_loaded_at avanza cada vez que se publica una fila, por lo que pollear sobre esta columna no se va a saltar actualizaciones tardías cuyo updated_at en la fuente sea anterior a la ventana ya consultada (por ejemplo, una fila que cambió hace horas pero recién llega al warehouse ahora). Polling sobre updated_at, en cambio, sí podría saltearlas.
Por esta razón, el campo incremental_cursor de cada tabla en el modelo de datos apunta a dw_loaded_at.
Guardar el máximo dw_loaded_at visto en cada corrida y, en la siguiente, traer solo las filas con dw_loaded_at > :last_seen. Combinado con el primary_key de la tabla (típicamente id), esto permite hacer upsert idempotente en el destino.
Primary keys
Todas las tablas excepto payment_logs exponen una clave primaria string llamada id. payment_logs es append-only y usa la clave compuesta (payment_id, processed_at, action).