Schemas y Modelos

Referencia completa de modelos Pydantic generados automáticamente desde el esquema OpenAPI.

---

DAGInfo

Una entrada de la lista de DAGs.

Los aliases mapean los campos del envelope de etl_backend.list_etls() declarativamente — el controlador no transforma nada, Pydantic v2 valida la lista entera en su core Rust.

Campo	Tipo	Requerido	Default	Descripción
dag_id	string	✅	—	ID del DAG
description	string | null	—	—	Descripción del DAG o ETL
last_run	string | null	—	—	Última ejecución

DAGListResponse

Respuesta con lista de DAGs.

Campo	Tipo	Requerido	Default	Descripción
dags	DAGInfo[]	—	—	Lista de DAGs
total	integer	—	0	Total de DAGs
id_company	string	✅	—	ID de la compañía

DagRunStats

Aggregated counts for /dags/{dag_id}/stats — output del etl.pvt_run_stats.

Reemplaza el viejo LogStats (que era log-centric y reportaba total_warnings=0, total_info=0 siempre porque metadata.parquet no tiene esas columnas). Esto es run-centric: cuántas ejecuciones, cuántas con cada fase OK/fail/skipped.

Campo	Tipo	Requerido	Default	Descripción
total_runs	integer	—	0
extract	PhaseStats	—	—	Sub-bloque de DagRunStats con la distribución success/failed/not_run de una fase.
transform	PhaseStats	—	—	Sub-bloque de DagRunStats con la distribución success/failed/not_run de una fase.
load	PhaseStats	—	—	Sub-bloque de DagRunStats con la distribución success/failed/not_run de una fase.
fully_successful	integer	—	0
any_phase_failed	integer	—	0
date_range	object	—	—

DagRunTimeline

Output del etl.pvt_run_timeline — buckets ordenados por tiempo.

Campo	Tipo	Requerido	Default	Descripción
interval	string	✅	—
points	TimelinePoint[]	—	—

ErrorDetail

Individual error detail with field and message.

Campo	Tipo	Requerido	Default	Descripción
field	string | null	—	—	Field that caused the error (if applicable)
message	string	✅	—	Error message for this field or context

ErrorResponse

Standardized error response for all endpoints.

Returns RFC 9457 Problem Details format for consistency across all HTTP error statuses.

Campo	Tipo	Requerido	Default	Descripción
error_code	string	✅	—	Machine-readable error code (e.g., 'VALIDATION_ERROR', 'UNAUTHORIZED', 'NOT_FOUND')
message	string	✅	—	Human-readable error message
status_code	integer	✅	—	HTTP status code (400, 401, 403, 404, 422, 500, 502, 503, 504)
request_id	string | null	—	—	Unique request ID for tracing and support
details	ErrorDetail[] | null	—	—	List of additional error details (e.g., validation errors per field)
timestamp	string | null	—	—	ISO 8601 timestamp when error occurred

HTTPValidationError

Campo	Tipo	Requerido	Default	Descripción
detail	ValidationError[]	—	—

HealthResponse

Estado de salud de la API.

Campo	Tipo	Requerido	Default	Descripción
status	string	✅	—	Estado: healthy
app_name	string	✅	—	Nombre de la aplicación
version	string	✅	—	Versión de la aplicación
environment	string	✅	—	Ambiente: production, develop

ParquetPageResponse

Respuesta paginada genérica para endpoints que leen archivos Parquet de S3.

Usado por todos los endpoints de /runs/ que retornan filas de parquet: - GET /runs/event/queue-data - GET /runs/event/payload - GET /runs/phases/{phase}/metadata - GET /runs/phases/{phase}/data - GET /runs/phases/{phase}/logs - GET /runs/phases/{phase}/errors

El campo rows es dinámico — su schema varía según el archivo parquet leído.

Campo	Tipo	Requerido	Default	Descripción
rows	object[]	✅	—	Filas del archivo Parquet
total	integer	✅	—	Total estimado de filas (puede ser 0 si not_found)
page	integer	✅	—	Página actual (0-indexed)
limit	integer	✅	—	Tamaño de página solicitado
has_more	boolean	✅	—	Si hay más páginas disponibles
not_found	boolean	—	False	True si el artefacto no existe en S3 (tarea aún no ejecutada)
message	string | null	—	—	Mensaje descriptivo cuando not_found=True

PhaseStats

Sub-bloque de DagRunStats con la distribución success/failed/not_run de una fase.

Campo	Tipo	Requerido	Default	Descripción
success	integer	—	0
failed	integer	—	0
not_run	integer	—	0

PresignedUrlResponse

URL prefirmada de S3 para descarga directa de un artefacto Parquet.

Campo	Tipo	Requerido	Default	Descripción
url	string	✅	—	URL prefirmada de S3 (GET)
key	string	✅	—	Key S3 completo del archivo
filename	string	✅	—	Nombre del archivo
expires_in	integer	✅	—	Segundos hasta expiración de la URL
bucket	string	✅	—	Nombre del bucket S3

RunArtifactInfo

Información de un artefacto Parquet dentro de un run.

Campo	Tipo	Requerido	Default	Descripción
key	string	✅	—	Key S3 completo
path	string	✅	—	Path relativo al run
filename	string	✅	—	Nombre del archivo
size	integer	✅	—	Tamaño en bytes
last_modified	string	✅	—	Fecha de última modificación ISO
url	string	✅	—	URL prefirmada para descarga directa

RunArtifactsResponse

Lista de todos los artefactos Parquet disponibles para un run.

Campo	Tipo	Requerido	Default	Descripción
run_id	string	✅	—	ID de la ejecución
dag_id	string	✅	—	ID del DAG/ETL
date	string	✅	—	Fecha del run (YYYY-MM-DD)
total	integer	✅	—	Total de artefactos encontrados
artifacts	RunArtifactInfo[]	✅	—	Lista de artefactos con URLs

SearchRunResult

Resultado de un run individual en la búsqueda avanzada.

Campo	Tipo	Requerido	Default	Descripción
run_id	string	✅	—	ID de la ejecución (Airflow run_id)
date	string	✅	—	Fecha del run (YYYY-MM-DD)
type	string	✅	—	Tipo: ERROR si alguna fase falló, ACTION_DONE si ok
first_timestamp	string	✅	—	Primer timestamp registrado
last_timestamp	string | null	—	—	Último timestamp registrado
log_count	integer | null	—	—	Cantidad de logs del run. Null cuando se obtiene desde la PVT (etl.logs no almacena el conteo); el frontend puede consultar /runs/phases/{phase}/metadata si lo necesita.
extract	string	✅	—	Estado del extract: success, failed
transform	string	✅	—	Estado del transform: success, failed, not_run
load	string	✅	—	Estado del load: success, failed, not_run
matched_phases	string[] | null	—	—	Fases donde matcheó el keyword (solo si se buscó por keyword)

SearchRunsResponse

Respuesta de búsqueda avanzada cross-phase.

Campo	Tipo	Requerido	Default	Descripción
runs	SearchRunResult[]	✅	—	Runs que coinciden con los filtros
total	integer	✅	—	Total de runs encontrados
page	integer	✅	—	Página actual (0-indexed)
limit	integer	✅	—	Tamaño de página
has_more	boolean	✅	—	Si hay más páginas disponibles

TimelinePoint

Un bucket de la timeline.

Campo	Tipo	Requerido	Default	Descripción
timestamp	string	✅	—
total_runs	integer	—	0
successful	integer	—	0
failed	integer	—	0

ValidationError

Campo	Tipo	Requerido	Default	Descripción
loc	string | integer[]	✅	—
msg	string	✅	—
type	string	✅	—
input	any	—	—
ctx	object	—	—