quantdb-data-structure — QuantDB 数据结构与读取口径

写任何触碰 QuantDB 本地数据的代码/查询前必读。字段单位与口径陷阱另见 skills/quantdb-fields/SKILL.md（本技能管「数据在哪、怎么组织、怎么读」）。

一、路径映射（先定位数据）

数据目录解析优先级（quantdb_hub.py._resolve_data_dir）： 环境变量 QM_QUANTDB_DATA_DIR → /data/quantdb → /app/data/quantdb → D:/quant_data → 项目根 data/quantdb。

二、顶层数据集目录

辅助文件：releases/（数据包版本）、.sync_state / quantdb_sync.sqlite（增量同步状态）、.qlib_cache、_meta。

三、文件组织规律（决定查询写法）

1. 分区型：<数据集>/dt=YYYYMMDD/data.parquet。dt 是 Hive 分区列，整数（如 20260828），DuckDB 过滤 WHERE dt BETWEEN 20260101 AND 20260828 可走谓词下推，不要写字符串。
2. 单文件型：<数据集>/{symbol}.parquet（财务报表、分钟K）或整表单文件（instrument_detail.parquet），用 pd.read_parquet 直读。
3. 混合格式：6_ml_datasets/l1_factors/ 同时存在平铺 l1_factors_YYYYMMDD.parquet 与 dt=YYYYMMDD/ 分区——只读 dt=* 分区目录，避免混入平铺文件。
4. 北向资金特殊：2_base_sector/hsgt_north/ 日频在 daily_freq/*.parquet（无分区），季度快照用 quarter=YYYYQN Hive 分区（2024-08 起季度披露）。

四、代码格式口径（最高频踩坑点）

• 查 QuantDB parquet 前必须转换：后端用 backend/shared/stock_utils.py 的 StockCodeUtil.to_suffix(code)；前端 normalizeStockCode。
• 反面教训：把前缀式代码原样传进 parquet 查询会静默返回空、不报错，快路径还会悄悄跌入兜底数据源（复权口径随之失效）。写完新链路必须实测两种复权参数下首/末根数值真正分化，并核对响应的 source_used 字段。

五、读取入口与 DuckDB 视图清单

唯一推荐入口：backend/services/engine/data_platform/quantdb_hub.py（QuantDBDataHub）——懒加载、线程安全、自动做列名映射（time→trade_date、wind_code→symbol、volinstock/vol_in_stock→volume）。不要绕过它自己拼 parquet 路径，除非做数据巡检。

分区数据集挂载的 DuckDB 视图（hive_partitioning=1, union_by_name=true）：

临时探查可直接 DuckDB 查文件：

SELECT * FROM read_parquet('/data/quantdb/1_kline_data/daily_forward/dt=20260828/data.parquet')
WHERE symbol = '600519.SH';

六、服务器核查命令速查

# 目录与体量
ls /opt/quantmind/data/quantdb && du -sh /opt/quantmind/data/quantdb/*

# 容器内可见性
docker exec quantmind ls /data/quantdb

# 某交易日数据是否到位（以日K为例）
ls /opt/quantmind/data/quantdb/1_kline_data/daily_forward/dt=20260828/

数据更新后服务未感知时：docker compose restart quantmind celery-worker（数据走 bind mount，无需重建镜像）。增量同步需先在【个人中心】→【数据平台】绑定 QUANTDB_API_KEY 后 docker exec 触发。

七、写代码前的自查清单

• 用的是 QM_QUANTDB_DATA_DIR/默认目录解析，而不是写死路径？
• 分区过滤用的是整数 dt，范围合理（不跨年全表扫）？
• 查 parquet 的代码已转后缀式？查 PG 内部表保持前缀式？
• 查询结果为空时验证过不是「格式错配静默查空」，而是真的无数据？
• 涉及字段单位（成交量/成交额/市值/股息率）时已对照 quantdb-fields 技能？