cointegrated_pairs 表说明（协整配对关系表）
cointegrated_pairs 表说明（协整配对关系表）
1. 概述与用途
- 表名：
cointegrated_pairs - 用途：保存通过两两配对回测筛选的协整配对关系，供实时服务启动时从数据库加载到内存使用。
- 更新方式：每次回测/导入前以 CSV 为准做 UPSERT（存在则更新，不存在则插入）；表结构无软删除字段。
2. 表结构（列定义）
| 列名 | 类型 | 约束/说明 |
|---|---|---|
id |
SERIAL |
主键，自增 |
base_symbol |
TEXT |
NOT NULL，基准币种（如 BTC/USDC:USDC） |
alt_symbol |
TEXT |
NOT NULL，目标币种（如 ETH/USDC:USDC） |
correlation_4h |
DOUBLE PRECISION |
可选，4H 收益率相关系数 |
cointegration_count |
INTEGER |
可选，协整通过数（满分 6） |
health_score_short |
DOUBLE PRECISION |
可选，4H/60D 短期健康评分 |
health_score_long |
DOUBLE PRECISION |
可选，4H/60D 长期健康评分 |
created_at |
TIMESTAMPTZ |
默认 NOW()，创建时间 |
updated_at |
TIMESTAMPTZ |
默认 NOW()，更新时间 |
3. 唯一约束
- UNIQUE(base_symbol, alt_symbol)
同一(base_symbol, alt_symbol)组合只保留一条记录，UPSERT 时以该约束判定冲突并执行更新。
4. 索引
| 索引名 | 列 | 用途 |
|---|---|---|
idx_cointegrated_pairs_alt |
(alt_symbol) |
按目标币种快速查找所有 base，供实时服务启动加载 |
idx_cointegrated_pairs_base |
(base_symbol) |
按基准币种查找，供统计/管理用 |
5. 抽样数据示例
以下为从 cointegrated_pairs 表抽样的一条真实记录：
| 字段 | 值 |
|---|---|
| id | 1 |
| base_symbol | AAVE/USDC:USDC |
| alt_symbol | SAGA/USDC:USDC |
| correlation_4h | 0.6264 |
| cointegration_count | 3 |
| health_score_short | 29.25 |
| health_score_long | 5.01 |
| created_at | 2026-02-18 06:07:34+00:00 |
| updated_at | 2026-02-18 06:07:34+00:00 |
含义简述：基准币 AAVE、目标币 SAGA 的协整配对；4H 收益率相关系数约 0.63，协整通过数 3/6，短期健康评分 29.25、长期 5.01。
6. 相关脚本
| 脚本 | 说明 |
|---|---|
src/scripts/backtest_pairwise_correlation.py |
两两配对回测，产出 pairwise_passed.csv |
src/scripts/import_cointegrated_pairs.py |
将 pairwise_passed.csv 导入本表（COPY + UPSERT） |
常用命令（项目根目录）：
# 使用默认 CSV 路径（项目根目录 pairwise_passed.csv）
uv run python -m src.scripts.import_cointegrated_pairs
# 指定 CSV 路径
uv run python -m src.scripts.import_cointegrated_pairs --csv path/to/pairwise_passed.csv
7. DDL 来源
- 新库初始化：
database/init_timescaledb.sql（约 531–560 行）。 - 已有库迁移：
database/migrations/20260218_add_cointegrated_pairs.sql。
代码侧通过 TimescaleDBClient 直连执行 SQL；实时服务从本表加载配对列表到内存使用。