quantdb-data-structure

⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

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

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

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

位置	路径
生产服务器宿主机	/opt/quantmind/data/quantdb
容器内（./data:/data bind mount）	/data/quantdb
本地仓库	<项目根>/data/quantdb
用户自定义数据集（产出区）	/data/quantcustom（宿主机 /opt/quantmind/data/quantcustom）

⚠️ quantdb/ 是官方只读数据；quantcustom/ 是用户/挖掘产出（因子挖掘、因子工厂的落盘区，QM_QUANTCUSTOM_DATA_DIR）。两者结构同为 6 大类，但写入一律进 quantcustom，不要污染 quantdb。

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

二、顶层数据集目录

目录	内容	组织方式
1_kline_data/	日K（daily_forward/backward/unadjusted 三种复权）、index_daily、min1_kline、min5_kline、tick	日K/指数=分区；分钟线=单文件
2_base_sector/	instrument_detail、sector_concept、trading_calendar、index_weights、margin_trading、hsgt_north	混合
3_financial_data/	balance/income/cashflow/股本/分红因子等财务报表	单文件为主
4_bond_etf/	债券 / ETF	单文件
5_technical_derived/	valuation（估值）、technical_indicators、market_sentiment	分区
6_ml_datasets/	features_daily、l1_factors、l2_factors、l1_l2_factors、alpha_library（Alpha101+GTJA191+Alpha158 三库因子）	分区

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

用户自定义数据集 quantcustom/6_ml_datasets/

挖掘产物统一落 data/quantcustom/6_ml_datasets/<数据集>/（结构与 quantdb 一致，按 dt=YYYYMMDD/ 分区）：

数据集	来源	附加文件
l1_factors	① RD-Agent 因子 export ② 因子工厂（backend/scripts/factor_factory.py）	MANIFEST.csv（factor_name/expression/ic/icir/coverage/kept）、PROPOSALS.json

• 读取入口：QuantDBFactorReader(mode="CUSTOM")（QM_QUANTCUSTOM_DATA_DIR，默认 /data/quantcustom）。
• 只读展示：GET /api/v1/alpha-agent/factory-factors（读 l1_factors/MANIFEST.csv，只回显不回测）。
• 历史补全/落库路径：backend/services/api/routers/admin/alpha_factor_pipeline.py。

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

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 的 symbol/wind_code	后缀式	600519.SH、000001.SZ
PG 表 stock_daily_latest 等内部表	前缀式	SH600519、SZ000001

• 查 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）：

视图	数据
qdb_daily_forward / qdb_daily_backward / qdb_daily_unadjusted	前复权 / 后复权 / 不复权日K
qdb_index_daily	指数日K
qdb_valuation	估值
qdb_technical_indicators	技术指标
qdb_market_sentiment	市场情绪
qdb_features_daily	每日特征
qdb_margin_trading	融资融券
qdb_l2_factors / qdb_l1_l2_factors	L2 / L1+L2 因子
qdb_l1_factors	L1 因子（仅当存在 dt=* 分区时挂载）
qdb_alpha_library	三库因子 429 列（训练直读）
qdb_hsgt_north_daily / qdb_hsgt_north	北向资金日频 / 季度

临时探查可直接 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 技能？