# etl_cursor 任务游标表

> 生成时间：2026-02-13

## 表信息

| 属性 | 值 |
|------|-----|
| Schema | meta |
| 表名 | etl_cursor |
| 主键 | cursor_id |
| 唯一约束 | (task_id, store_id) |
| 外键 | task_id → etl_task(task_id) ON DELETE CASCADE |
| 记录数 | 44 |
| 说明 | 记录每个任务/门店的增量窗口水位及最后一次运行 ID，是增量正确性的关键表 |

## 字段说明

| 序号 | 字段名 | 类型 | 可空 | 默认值 | 说明 |
|------|--------|------|------|--------|------|
| 1 | cursor_id | BIGINT | NO | BIGSERIAL | 自增主键 |
| 2 | task_id | BIGINT | NO | | 关联 etl_task.task_id，标识所属任务 |
| 3 | store_id | BIGINT | NO | | 门店/租户粒度 |
| 4 | last_start | TIMESTAMPTZ | YES | | 上次窗口开始时间（含重叠偏移），下次增量从此时间点继续 |
| 5 | last_end | TIMESTAMPTZ | YES | | 上次窗口结束时间 |
| 6 | last_id | BIGINT | YES | | 上次处理的最大主键/游标值（可选），用于基于 ID 的增量模式 |
| 7 | last_run_id | BIGINT | YES | | 上次运行 ID，对应 etl_run.run_id |
| 8 | extra | JSONB | YES | '{}'::jsonb | 附加游标信息 JSON，可存放任务特有的水位数据 |
| 9 | created_at | TIMESTAMPTZ | YES | now() | 创建时间 |
| 10 | updated_at | TIMESTAMPTZ | YES | now() | 更新时间 |

## 使用说明

```sql
-- 查询所有任务的当前游标水位
SELECT t.task_code, c.store_id, c.last_start, c.last_end, c.last_run_id
FROM meta.etl_cursor c
JOIN meta.etl_task t ON c.task_id = t.task_id
ORDER BY t.task_code;

-- 查询指定任务的游标详情
SELECT *
FROM meta.etl_cursor
WHERE task_id = (SELECT task_id FROM meta.etl_task WHERE task_code = 'FETCH_ORDERS' LIMIT 1);

-- 重置某任务的游标（用于重跑历史数据）
UPDATE meta.etl_cursor
SET last_start = '2024-01-01 00:00:00+08', last_end = NULL, last_id = NULL, updated_at = now()
WHERE task_id = (SELECT task_id FROM meta.etl_task WHERE task_code = 'FETCH_ORDERS' LIMIT 1);
```

## 可回溯性

| 项目 | 说明 |
|------|------|
| 可回溯 | ✅ 完全可回溯（created_at / updated_at 记录变更时间，last_run_id 可追溯到具体运行记录） |
| 数据来源 | 由调度器（orchestration）在每次任务运行后自动更新 |
| 关联表 | etl_task（通过 task_id 关联）、etl_run（通过 last_run_id 关联） |
