# etl_run 运行记录表

> 生成时间：2026-02-13

## 表信息

| 属性 | 值 |
|------|-----|
| Schema | meta |
| 表名 | etl_run |
| 主键 | run_id |
| 外键 | task_id → etl_task(task_id) ON DELETE CASCADE |
| 记录数 | 8726 |
| 说明 | 记录每次任务执行的窗口参数、运行状态、处理计数与日志路径，是 ETL 运维排查的核心表 |

## 字段说明

| 序号 | 字段名 | 类型 | 可空 | 默认值 | 说明 |
|------|--------|------|------|--------|------|
| 1 | run_id | BIGINT | NO | BIGSERIAL | 自增主键 |
| 2 | run_uuid | TEXT | NO | | 本次调度的唯一标识（UUID 格式），用于跨系统关联 |
| 3 | task_id | BIGINT | NO | | 关联 etl_task.task_id，标识所属任务 |
| 4 | store_id | BIGINT | NO | | 门店/租户粒度 |
| 5 | status | TEXT | NO | | 运行状态。**枚举值**: `SUCC` = 成功, `FAIL` = 失败, `PARTIAL` = 部分成功 |
| 6 | started_at | TIMESTAMPTZ | YES | now() | 开始时间 |
| 7 | ended_at | TIMESTAMPTZ | YES | | 结束时间 |
| 8 | window_start | TIMESTAMPTZ | YES | | 本次窗口开始时间 |
| 9 | window_end | TIMESTAMPTZ | YES | | 本次窗口结束时间 |
| 10 | window_minutes | INTEGER | YES | | 窗口跨度（分钟） |
| 11 | overlap_seconds | INTEGER | YES | | 窗口重叠秒数 |
| 12 | fetched_count | INTEGER | YES | 0 | 抓取/读取的记录数 |
| 13 | loaded_count | INTEGER | YES | 0 | 插入的记录数 |
| 14 | updated_count | INTEGER | YES | 0 | 更新的记录数 |
| 15 | skipped_count | INTEGER | YES | 0 | 跳过的记录数 |
| 16 | error_count | INTEGER | YES | 0 | 错误记录数 |
| 17 | unknown_fields | INTEGER | YES | 0 | 未知字段计数（清洗阶段发现的未定义字段） |
| 18 | export_dir | TEXT | YES | | 抓取/导出目录路径 |
| 19 | log_path | TEXT | YES | | 日志文件路径 |
| 20 | request_params | JSONB | YES | '{}'::jsonb | 请求参数 JSON，记录本次运行使用的 API 请求参数 |
| 21 | manifest | JSONB | YES | '{}'::jsonb | 运行产出清单/统计 JSON，记录处理结果摘要 |
| 22 | error_message | TEXT | YES | | 错误信息（若失败时记录具体原因） |
| 23 | extra | JSONB | YES | '{}'::jsonb | 附加字段，保留扩展 |

## 使用说明

```sql
-- 查询最近 10 次运行记录
SELECT r.run_id, t.task_code, r.status, r.started_at, r.ended_at,
       r.fetched_count, r.loaded_count, r.error_count
FROM meta.etl_run r
JOIN meta.etl_task t ON r.task_id = t.task_id
ORDER BY r.started_at DESC
LIMIT 10;

-- 查询失败的运行记录及错误信息
SELECT r.run_id, t.task_code, r.started_at, r.error_message
FROM meta.etl_run r
JOIN meta.etl_task t ON r.task_id = t.task_id
WHERE r.status = 'FAIL'
ORDER BY r.started_at DESC;

-- 统计各任务的运行成功率
SELECT t.task_code,
       COUNT(*) AS total_runs,
       COUNT(*) FILTER (WHERE r.status = 'SUCC') AS success_count,
       ROUND(100.0 * COUNT(*) FILTER (WHERE r.status = 'SUCC') / COUNT(*), 1) AS success_rate
FROM meta.etl_run r
JOIN meta.etl_task t ON r.task_id = t.task_id
GROUP BY t.task_code
ORDER BY success_rate;
```

## 可回溯性

| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯（每次运行独立记录，含完整窗口参数、计数和错误信息） |
| 数据来源 | 由调度器（orchestration）在任务执行过程中自动写入和更新 |
| 关联表 | etl_task（通过 task_id 关联）、etl_cursor（通过 last_run_id 反向关联） |
