Files
archer/docs/progress.md
T
voidandClaude Sonnet 4.6 366d61ca25 Add archer import and allow date-mode bulk delete
archer import replays a sealed archive into an existing table: shard
selection (`--select`), SHA-256 pre-verification, idempotent modes
(`ignore`/`insert`/`replace`), and both LOAD DATA and batched-INSERT
engines. It reads manifest.jsonl strictly so corruption is reported
instead of skipped, and supports --dry-run, --allow-partial, and
per-shard workers.

--bulk-delete no longer rejects --shard-by date. Range deletion now
derives its bounds from the chunk's actual keys (date scanners rewrite
LastKey into a resumption cursor) and keeps safe-auto-increment
semantics by excluding the current max key. A startup warning documents
the monotonic-shard-column assumption.

Also splits CLI/format/sharding/progress/safety reference docs out of
the README, and adds the corresponding OpenSpec change artifacts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-08 21:14:23 +08:00

42 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 进度显示
默认 `--progress auto`:stderr 是终端时在最后一行原地刷新,重定向到文件或管道时不输出进度。
进度与警告统一写 stderr;`--dry-run` 与 `--statistics` 仍写 stdout,因此
`archer ... > result.txt` 不会把进度混进结果。
| 取值 | 行为 |
|---|---|
| `auto`(默认) | stderr 是终端时显示实时进度,否则静默 |
| `on` | 始终显示;非终端时每个间隔输出一行完整 `key=value` |
| `off` / `0` | 关闭 |
| `N>0` | 开启,并在每处理 N 行时额外输出一行 |
`--progress-interval`(默认 `1s`)是最小刷新间隔。终端模式用 `\r` 覆盖同一行并以空格补齐,
不使用 ANSI 清行或颜色,兼容 Windows conhost;行宽超过 100 字符时按优先级裁掉字节数、
分片序号,再缩短进度条,不换行。
进度包含:已处理行数、约 5 秒窗口速率、当前阶段与阶段耗时、本次运行 elapsed,
存在分片时包含分片序号,写文件时包含已写字节。阶段依次为
`probe → resume → estimate → scan → file → db → checkpoint → finalize`;
等待副本延迟时显示 `lag-wait` 与等待原因,而不是一条孤立的 `waiting:` 消息。
单日长查询、fsync 与 lag 等待期间进度仍按间隔刷新。
总量估算只使用有界 MIN/MAX 查询(独立连接 + 2 秒超时,绝不 `COUNT(*)`):
| 场景 | 口径 | 显示 |
|---|---|---|
| `--shard-by date` | 分片列的 MIN/MAX 天范围 | `estimate=day`、`day 37/120`、`~58%`、`eta ~1m36s` |
| 非日期、单列整数唯一键 | 键的 MIN/MAX | `estimate=key`、`~58%`、`eta ~1m36s` |
| 复合键、字符串/二进制键 | 不适用 | `estimate=none`,只显示行数与速率 |
百分比与 ETA 都带 `~`;ETA 按本次运行的推进速率与剩余量计算,不使用"已用时间 ÷ 百分比"。
日期模式按天跳变、键模式在键有空洞或分布不均时偏差较大,这些值都是估算而非精确进度,
不影响归档逻辑。
续跑后进度从 `state.json` 的累计 `rows_done` 起算,不会从零重来;本次运行写回的
`rows_done` 同样是累计值(续跑前已提交 + 本次提交)。旧版本写入的 checkpoint 只记录
上次运行的行数,升级后首次续跑可能偏低,完成后即恢复累计语义。
按 Ctrl+C 时先停止刷新、清除实时行并输出最终快照,然后封存当前分片并写 checkpoint,
退出码保持 130。