quantdb-fields

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

quantdb-fields — QuantDB 字段单位速查手册

用 QuantDB 数据做任何分析/回测/报告前必读。所有单位均为 2026-08 直接读本地 parquet 实测验证（不是照抄文档）。 单位搞错的后果：成交额差 1 万倍、股息率差 100 倍、换手率差 100 倍—— 分析结论全部作废。

一、通用规则（先记这个）

规则	说明
个股 OHLC = 元	开高低收统一为人民币元（与市值同量纲）
个股成交量 = 股	A 股 1 手 = 100 股，但 QuantDB 个股 kline 的 volume 单位就是股，不是手
个股成交额 = 万元	amount = 5828.37 表示 5828.37 万元（约 5828 万），不是元
指数成交量 = 手	index_daily.volume 单位是手（1 手 = 100 股），与个股相反！
市值 = 元	valuation 的 total_mv/float_mv 单位是元（工业富联 float_mv ≈ 1.31 万亿）
比例字段 ≈ 小数或 %	没有统一约定，按数据集查下表；% 的字段值 = 百分数（4.06 即 4.06%）
symbol 格式按数据源分	parquet 用后缀 601138.SH；PG 的 stock_daily_latest 用前缀 SH601138
验证公式	个股 close*volume/amount ≈ 1e4（股+万元）；指数 ≈ 2e4（手+万元）

二、1_kline_data 日线（daily_forward / daily_backward / daily_unadjusted）

字段	单位	实测依据
volume	股	601138 20260814 volume=4704920 股，amount=5828.37 万元，close*volume/amount≈1e4
amount	万元	同上（close 66.19 × 470 万股 ≈ 3.1 亿 ≈ 31163 万元，与 amount 同量级吻合）
open/high/low/close	元（forward=前复权，backward=后复权，unadjusted=不复权）
单位切换传闻	不存在。20260721 前后 amount 均为万元、volume 均为股。曾有记忆说 20260721 切换到"手/元"，实测已无此切换，按股/万元统一处理

min1/min5：同单位（volume=股、amount=万元），但数据停滞在 2026-07-24，用前先查最新日期。

三、L2 原始逐笔与十档盘口（1_kline_data/l2_data + tick_data，2026-08 新增）

万得(Wind) L2 数据，backend/scripts/wind_l2_import.py 从逐日 7z 压缩包（20260511.7z）导入。 当前实测只有 1 个交易日 20260511（order 1950 + trade 1721 = 3671 文件，部分标的仅其一）， 用前先查日期覆盖：ls data/quantdb/1_kline_data/l2_data/ | grep -oE '[0-9]{8}' | sort -u。

文件命名：order_{code}_{date}.parquet / trade_{code}_{date}.parquet，code 为下划线格式 000001_SZ（对应后缀 000001.SZ）。time 单位统一为 UTC 毫秒（万得 hhmmssmmm 转 UTC， 北京 09:15:00 = 01:15:00 UTC），覆盖 09:15 集合竞价到 15:00 收盘。

逐笔委托 order_

字段	单位/格式	说明
time	UTC ms	09:15 集合竞价 → 15:00 收盘
order_id	int	交易所委托号（可与 trade_.ask_order_id/bid_order_id 配对）
channel	str	委托编号
order_type	str	'0'=普通委托、'U'=撤单、'1'=其余
direction	str	'B'=买 / 'S'=卖
price	元	万得 ×10000 → 元（已归一）；集合竞价未定价委托 price=0
volume	股

逐笔成交 trade_

字段	单位/格式	说明
time	UTC ms	同上
trade_id	int	成交编号
trade_type	str	'C'=集合竞价成交 / '0'=连续竞价
direction	str	'B'/'S'/' '（集合竞价段=空格）
price	元，未复权	与 daily_unadjusted 对齐（实测 000001.SZ 20260511 末笔 11.28 = unadjusted close 11.28）；与 daily_forward 前复权 close 有除权差（有分红送转者差数十%）
volume	股	⚠️ 沪≈日线量、深≈2×日线量（见坑1）
ask_order_id / bid_order_id	int	叫卖/叫买序号 → 配对逐笔↔委托

tick_data 十档盘口快照（18 列）

列	单位	说明
lastPrice/open/high/low/lastClose	元
amount	混源	⚠️ 见坑2
volume	混源	当日累计成交量
pvolume	笔	连续竞价成交笔数（wind 导入有值）；旧导入=0（可作来源判据）
askPrice/bidPrice	array(10)	十档价，元
askVol/bidVol	array(10)	十档量，股
stockStatus	int	BS 标志
openInt/settlementPrice/lastSettlementPrice	—	期货占位字段，A股多为 0

⚠️ 三个必踩的坑

1. 沪/深成交量双口径：逐笔成交 volume 求和，沪 SH = 日线 volume（实测 600714.SH 求和 34825501≈日线 34825500）； 深 SZ ≈ 1.8~2.1× 日线 volume（实测 002830 1.92×、300521 2.11×、000999 1.79×、000001 1.88×）。 → 逐笔求和不能当当日成交量，深市除 ~2 或直接与日线对账。
2. tick_data 单位混源：同一目录内单位不统一——wind_l2_import 导入的（如 20260511）volume=股、amount=万元； 更早 QuantDB tick 同步的（如 20260720）volume=手、amount=元。 实测：20260511 最后快照 volume 93186521≈日线 93186520 股、amount 104743.53≈104743.54 万； 20260720 volume 1567304 手×100=156730400 股、amount 1713460189 元=171346.02 万。 → 用前必须拿最后一条快照对账日线，或按 pvolume（0=旧/手·元，>0=wind/股·万元）区分。
3. 价格=未复权真实成交：有除权除息时与前复权日线差一个复权因子 （实测 002830.SZ 20260511 L2 末笔 24.08 vs 前复权 close 17.06）；算收益需先统一复权口径。

导入命令（手动增量，不吃 quantdb_daily_sync）

python backend/scripts/wind_l2_import.py --archive /path/to/20260511.7z                      # 全市场
python backend/scripts/wind_l2_import.py --archive ... --symbols 000001.SZ,600519.SH         # 指定标的
python backend/scripts/wind_l2_import.py --archive ... --force                               # 覆盖重导

文件名即日期（20260511.7z → 20260511），流式逐股解压导入、可断点续跑（已存在三件套自动跳过）。 容器内 7z 默认 /opt/p7zip-legacy/bin/7z，数据目录自动探测 /data/quantdb 或本地 data/quantdb。

四、1_kline_data/index_daily 指数日线（⚠️ 与个股相反）

字段	单位	实测依据
volume	手（×100=股）	上证 000001.SH 20260814 volume=499525600 手 = 499.5 亿股（合理）；close*volume/amount=19808≈2e4
amount	万元	99037192 万元 = 9903.7 亿元 ≈ 上证单日成交额 ✓
close	点位	3927.18

反推：指数平均股价 = close×100/(close×volume/amount) = close×100/19808 ≈ 19.8 元/股，符合 A 股平均股价，故 volume 必为手。

五、5_technical_derived 技术衍生

valuation（估值）

字段	单位	注意
close	元，不复权	601138 close=66.19（与 technical_indicators 的后复权 close=70.05 不同）
total_mv / float_mv	元	float_mv=1313480468277.96 ≈ 1.31 万亿 ✓
total_capital / circulating_capital	股	19844092284 股 ≈ 198.4 亿股
net_profit_ttm / revenue_ttm / equity / annual_net_profit	元
pe_ttm / pe_static / pb / ps_ttm	倍
dividend_rate	%（百分数值）	0.148 = 0.148%！公式 = 近一年每10股派息/10/close×100。601138: 0.98/10/66.19×100=0.1481 ✓；600519: 51.98/10/1341.99×100=0.3873 ✓。把它当小数会差 100 倍
dividend_rate 口径切换	20260814 起	此前为小数口径（每10股派息/不复权close，如 0.98/65.60=0.01494）；20260814 起切换为百分数口径（×100）。同字段历史不连续，跨 20260814 分析需 ×10 归一

technical_indicators（技术指标）

字段	单位	陷阱
close	后复权	601138=70.05，与不复权 66.19 不同；凡基于 close 算的指标都是后复权口径
volume_ma_3/5	股
amount_ma_5	万元
pct_change	%	1.4717 = 1.47%
future_return_1d / future_return_20d	未来 N 日收益（标签）	2026-09 由 return_Nd 改名；勿当历史动量或过滤条件（标签泄漏）。历史动量用 pct_change / l1 mom_ret_*
vol_std_20	%	4.0578 = 4.06%（l1 里同名字段是小数 0.0406，差 100 倍！）
vol_atr_14	元	3.58 元（l1 同名字段也是元，一致）
macd_hist / rsi_14 / kdj_*	原始指标值	与 l1 一致

market_sentiment（市场情绪）

字段	单位
close	不复权
turnover_rate 等比率	小数（0.02 = 2%）
momentum_*	%（百分数值）

六、6_ml_datasets 因子

features_daily（技术+估值合并表，78 列，2026-09 起新增 30 列）

基础 46 个数值列单位与 technical_indicators / valuation 一致；新增 30 列全部以字符串存储，用前先转数值：

字段	单位	实测/注意
dividend_rate	小数口径（无 ×100）	与 valuation 不同！公式 = 每10股派息/不复权close（0.98/66.19=0.0148），从未切换口径。valuation 20260814 起是它的 10 倍。特征快照 generate_feature_snapshots.py 已 ×10 归一到百分数口径
total_mv / float_mv / pe / pb 等	与 valuation 完全一致	实测 601138 全部 ✓
total_cap_yi / float_mv_yi	亿元	实测 ×1e8/total_mv=1.000、×1e8/float_mv=1.000（与本表 total_mv/float_mv（元）差 1e8）
free_float_shares	万股（自由流通股本）	×1e4 转股；000001.SZ=816056.58 万股≈81.6 亿股（自由流通 < 流通股本，勿与 circulating_capital 混用）
hs_turnover	%（换手率）	如 0.43 / 1.71，max≈76
zaf	%（当日涨跌幅）	与 pct_change 高度一致（corr=0.986，-0.93 vs -0.928）
seal_strength	无量纲（封板强度，≈1.0 封住）	如 1.02
ever_zt_count / year_zt_days	计数（整数）	曾涨停次数 / 年内涨停天数
ipo_price	元	发行价
zt_price / dt_price	元（基于不复权价）	涨停价/跌停价；⚠️ 与表内前复权 close 不同口径（勿直接比；000001.SZ: zt=13.04/dt=10.67 vs 前复权 close=18.16）
beta_now	无量纲（beta）	与 beta_20 corr≈0.71（窗口/口径不同）
dyna_pe / static_pe_ttm	倍	⚠️ 含负哨兵（实测 -686 / -897），亏损股勿直接用
div_yield	%（百分数值）	5.14=5.14%；与本表 dividend_rate（小数 0.0508）差 100 倍
pb_mrq	倍	≈pb（pb_mrq/pb median=1.000）
list_date	字符串 YYYYMMDD	如 '19910403'
industry_code / industry_name	字符串	128 细分行业（X5001 / 全国性银行）
sector_code	字符串	如 881386
region_area_code / region_area_name	字符串	32 地区板块（18 / 深圳板块）
main_business	中文文本	主营业务
in_hs300 / is_hsgt / is_margin / is_kcb_creatable / is_st / is_quit_risk / is_hk	字符串 '0'/'1'	标记位（转 int 后再过滤/统计）

l1_factors（一级因子，decimal 为主）

字段	单位
收益率类 mom_ret_*	小数（0.0147 = 1.47%）
vol_std_*	小数（0.0406 = 4.06%；与 technical_indicators 的 % 版本差 100 倍）
vol_atr_14	元（3.55 元）
fun_total_mv	ln(市值元) —— 用时要 exp()
分位数/percentile 字段	0~1 小数
liq_* / fun_turnover / fun_mv	部分日期为 None，注意补缺

l2_factors（二级因子，flow 金额注意）

字段	单位	实测依据
flow_net_amount / flow_buy/sell / flow_super/large/medium/small_net	万元（2026-09 起）	与同表 amount 同量纲：flow_net_amount/amount≈flow_net_ratio；此前为元（flow/(amount×1e4)≈ratio）
flow_*_ratio	小数
vol_turnover_total	股	与 kline volume 完全相等 ✓
分区	已恢复日更	⚠️ top 少数净流入可能厂商同值封顶

读入归一：backend/shared/quantdb_flow_units.py 自动把万元→元（兼容旧分区），下游再 /1e8→亿、×1e-6→百万元。

flow 灌入口径（update_sdl_complete_pipeline.py）：假定源为元时 /1e6→百万元；新版万元源须先 ×1e4。

七、PG 表 stock_daily_latest（API 服务数据源）

列	单位 / 格式	实测依据
symbol	前缀格式 SH601138（不是 601138.SH）	suffix 查询 0 行，prefix 查询 1072 万行
volume	股	601138 max_volume=633217088 股
amount	万元	601138 amount=5828.37，max_amount=3306339（万元）
float_mv / total_mv	元	float_mv=7095151630 元
turnover_rate / flow_net_amount / main_flow	NULL（未灌）	风险评分里"缺少换手率"由此而来
volume_ratio_5	倍（0.934）

八、research API 换算表（/research/features 等接口返回）

API 层 _UNIT_SCALES 把部分字段缩放后输出（L2 金额先归一为元）：

输出字段	缩放	输出单位	例
totalMv / floatMv	×1e-8	亿元
mainFlow / flowNetAmount / flowLargeNet / flowMediumNet / flowSmallNet / flowSuperNet	×1e-6	百万元	统一口径
turnoverRate	—	% 小数

九、3_financial_data 财务数据

数据集	字段	单位
balance / income / cashflow	各科目	元
capital	股本	股
holder_num	股东户数	户
dividend_factors	interest	每10股派息（元）——600519 每10股派 51.98 元，601138 派 0.98 元。算每股股息要 /10
dividend_factors	stockBonus / stockGift / allotNum	每10股送/转/配股数
dividend_factors	dr	除权因子（复权用）

十、2_base_sector

数据集	字段	单位	注意
instrument_detail	Symbol	后缀 601138.SH	HqDate 停滞 20260720，市值/估值滞后
	J_zgb / FreeLtgb	万股（1984409.25 万股 = 198.4 亿股）	与 valuation 的 circulating_capital(股) 差 1e4
	J_yysy / J_jly / J_zzc 等 J_*	万元（25107808 万 = 251 亿）	与 financials 的元差 1e4
	Zsz / Ltsz	亿元（11211.91 亿 ✓）
	J_mgsy	元（2.14 元/股）
	fHSL	不明（0.56，非换手率%，与自算 0.74% 不符），别当换手率用
	TotalBVol	不明（43555，量级像手，但远小于全天量）	L2 快照字段，非全天
	DYRatio	不可靠（600519=4.15 vs 真实 0.39%），别当股息率，用 valuation.dividend_rate
	Yield	不明（6078.44），勿用
index_weights	Weight	%	文件名 000300.SH.parquet 不是 000300.parquet
trading_calendar	TradingDate	YYYYMMDD int

十一、其他数据集

数据集	字段	单位	状态
margin_trading	finance_*	万元
	slo_volume / slo_net	股
hsgt_north	holding_quantity 股 / holding_value 元 / 比率 %		停滞 2024-08（北向改季度披露后）

十二、已知数据缺口（2026-08 实测）

1. min1/min5 分钟线停更（最新 2026-07-24）
2. l2_factors 分区停更 —— 已恢复（2026-08-19 实测至 20260818）
3. hsgt_north 北向明细停更（2024-08，改季度披露所致）
4. instrument_detail HqDate 滞后（20260720）
5. dt=20260729~20260802 个股日线有同步缺口（非交易日+同步中断） 5b. valuation dt=20260813 只有 101 行（同步缺口，dividend_rate 全 NaN），features_daily 同日 5543 行正常
6. technical_indicators / features_daily 的 future_return_*（旧 return_*）是未来收益标签，勿当历史动量过滤
7. stock_daily_latest 的 turnover_rate/flow_net_amount/main_flow 常为 NULL
8. l2_data 原始逐笔仅 20260511 单日 —— 万得按日 7z 手动导入（wind_l2_import.py），非自动日更
9. tick_data 单位混源 —— wind=股/万元，旧同步=手/元，对账前勿直接用

十三、分析前检查清单

• 确认数据源是 parquet 还是 PG/API（单位体系不同）
• symbol 格式匹配数据源（parquet 后缀 / PG 前缀）
• 成交量：个股=股，指数=手
• 成交额：万元（API 输出已缩放为亿/百万）
• 波动率：technical_indicators 是 %，l1 是小数（差 100 倍）
• 股息率：valuation.dividend_rate 是 % 百分数值（0.148=0.148%），不是小数
• close 口径：technical_indicators 是后复权，valuation 是不复权
• 市值：parquet 是元，instrument_detail 是亿元/万股，API 是亿元
• 财务：financials 是元，instrument_detail J_* 是万元
• 用前查数据最新日期（分钟线、l2、hsgt 都可能已停更）
• L2 原始逐笔（l2_data）：先查日期覆盖（当前仅 20260511 单日），价格是未复权，逐笔求和沪≈日线量/深≈2×，别当成交量
• tick_data：先拿最后一条快照对账日线（wind=股/万元 vs 旧同步=手/元，单位混源）