基本面数据

开发中：基本面数据尚未完全可用。在 IDE 或回测中使用此功能可能会返回不一致的基本面数据（缺失字段、报告日期不匹配，或与 K 线对齐的快照不稳定）。在未来版本将基本面数据标记为稳定之前，请将结果视为实验性的。

QuantCraft 策略可以在 OHLCV 价格 K 线之外使用公司财务数据：资产负债表、现金流量表、利润表，以及盈利历史／预期。数据从 QuantCraft 基本面数据服务按标的加载一次，组织为以日期为键的表，并在回测期间以与 K 线对齐的快照形式提供给你的策略。回调时机遵循策略生命周期；标的和日期在 Test（运行代码）中配置。

除了三大报表之外，你还会得到比率（共 91 个）、每股数值、估值倍数与收益率，以及质量评分（Piotroski F、Altman Z-prime、Beneish M）——全部是时点式（point-in-time）的，全部是可选的。它们按标的逐步推出，所以请对每次访问做保护：raw["metricsInputs"] is None 表示数据包早于这些指标。

本页涵盖：

• 有哪些财务报表数据可用
• 以日期为键的表如何组织
• 与 K 线对齐的载荷在回测期间如何到达你的回调

**相关：**全球 Fama-French 因子收益数据集（不是按代码的）是一项独立的功能——参见 Fama-French 因子（fama_french.qc，没有回调参数）。因子的 rows 以 YYYYMM 字符串为键，而不是列表索引。

---

你会得到什么

每个基本面数据包是针对一个代码的单个 JSON 对象，包含：

• 资产负债表——quarterly 和 yearly 报告。
• 现金流量表——quarterly 和 yearly 报告。
• 利润表——quarterly 和 yearly 报告。
• 盈利（Earnings）：
  • History——按报告日期的已公布 EPS 与预期及意外。
  • Trend——前瞻预期、EPS 趋势和分析师修正。
  • Annual——每个财年的 epsActual。
• 比率——quarterly 和 yearly 财务比率（利润率、回报率、流动性、杠杆）。
• Financials extended——核心利润表、资产负债表或现金流量表中没有的 quarterly 和 yearly 扩展指标。
• 每股——quarterly 和 yearly 的每股数值（按申报时的口径，股数基于该期间的拆股口径）。
• 估值——quarterly 和 yearly 的市值、企业价值、倍数和收益率，外加一个不带日期的 latest 对象。
• 评分——quarterly 和 yearly 的 Piotroski F、Altman Z-prime 和 Beneish M，外加 notApplicableReason。
• TTM——单个滚动十二个月对象（不按期间分桶）。
• 指标来源——扁平的 metricsInputs / metricsHealth 对象。在早于指标扩展的数据包上，metricsInputs 为 None。
• 申报历史——quarterly 和 yearly 的申报元数据（表格类型、申报日期，以期末为键）。当数据包中存在时，也包含在与 K 线对齐的 current(...) 快照中；原始表仍可通过 f.tables["filingHistory.quarterly"] 获取。
• 公司信息——扁平的实体元数据（名称、CIK、SIC、地址、交易所、代码）。不以日期为键，也不在与 K 线对齐的快照中；通过 f.raw["companyInfo"] 访问。

每份报告是一行 camelCase 指标——例如 totalAssets、cash、freeCashFlow、totalRevenue、netIncome、epsActual、epsEstimate、surprisePercent。数值在底层 JSON 中可能以字符串形式到达，任何缺失字段返回 None。

某个代码可能不会提供每个部分。请使用基本面数据覆盖范围浏览器查看某个代码有哪些字段可用。

---

以日期为键的表

对于上述每个部分，基本面数据都组织成一个以日期为键的表：行以报告日期（YYYY-MM-DD）为键，指标以并行列表的形式暴露，你可以像价格历史一样对其进行索引。

标准的表路径有：

不是表。valuation.latest、scores.notApplicableReason、ttm、metricsInputs、metricsHealth 和 companyInfo 不以日期为键，因此它们不出现在 tables、lists 和任何 K 线时点快照中——这是有意为之：

所有这些都是上传时点的数据而不是按期间的，所以把它们排除在 tables 之外，也就把它们排除在每个 K 线时点快照之外——回测因此无法在 2019 年的 K 线上意外读到今天的价格。请改为通过 f.raw 访问它们。空块（{"quarterly": {}, "yearly": {}}，金融行业申报人的 scores 就是这个样子）根本不会注册任何表。

索引约定：最新的在前

在这些表中，索引 0 是最近的符合条件的期间，索引 1 是前一个期间，依此类推。这与 QuantCraft 其余部分中价格序列的工作方式一致。

如果你想直接加载数据包（例如在回测之外），基本形态如下：

你可以从已加载的数据包中读取的内容：

DateKeyedTable 提供 periods（YYYY-MM-DD 键，最新在前）、columns（字段 → 值），并支持 table["fieldName"] 索引。

在运行时发现字段很容易：sorted(f.lists.keys()) 显示每个扁平序列，sorted(t.columns.keys()) 显示一个表的列——当服务器添加或移除字段时很有用。

---

回测中与 K 线对齐的载荷

在回测中，你不是把基本面数据作为原始表来读取——引擎会为当前 K 线选取正确的报告，并将其作为快照提供给你的回调。这称为与 K 线对齐的载荷。

为回测配置基本面数据

在 Run backtest 的 Symbol & data 标签页中：

1. 勾选 Uses fundamentals (select if your strategy requires fundamental data)（需要登录——QuantCraft 会发送你的会话令牌以加载 B2 基本面数据文件）。批量前向和图表前向运行把它标为 Use fundamentals (optional)。当你的版本提供基本面数据功能时会显示该复选框，但除非你拥有 Premium 或已启用免费数据访问，否则它是禁用状态（带有 Premium 提示）。
2. 从多选框中选择一个或多个基本面数据包（路径形如 fundamentals/AAPL.json.gz）。

对于 Screener 标的来源（回测）或 Screener 目标（AutoTrading / QuantCloud 批量运行），你不需要挑选任何内容：开启基本面数据，筛选所选的每个标的就都会得到自己的数据包，因此 fundamentals.current(bar["t"], symbol=symbol) 对每一个都可用。数据包来自 Screener 自己的下载（不会重复获取），而 Screener 尚未下载的标的会被获取一次并保留。在实盘运行中，数据包会跟随每次重新筛选。手动选择仍会作为额外项被接受（例如一个基准代码）。数据无法加载的标的会返回 None 而不是让运行失败——Output 面板会打印加载了多少个。

**OHLCV 标的与基本面数据标的是相互独立的。**你可以通过券商数据源回测 RNMBY，同时加载 RHM.XETRA 的基本面数据——请在代码中把正确的代码传给 fundamentals.current(..., symbol="RHM.XETRA")（或等效调用）。

当选择了多个数据包时，需要特定数据包时请在 fundamentals.current / get_data_with_offset 上使用显式的 symbol=。除非引擎应用其他规则，用于与 K 线对齐的快照的主数据包默认为你的标的列表中的第一个 OHLCV 标的。

要在回调之外进行底层的表访问，请在其不为 None 时使用 quantcraft.process.runtime 中的 qc_fundamentals（例如 qc_fundamentals.raw["companyInfo"]）。它只保存主数据包；对任何其他代码，请使用回调的 fundamentals 句柄并带上 symbol=。

如果没有配置基本面数据，引擎只会向你的回调传入 fundamentals=None，由你做判空保护。

时点式（回测）：回测引擎和 Debug Test 都会构造 BacktestFundamentals(..., backtest_mode=True)，所以 current / get_data_with_offset 使用申报日期门控（use_filing_date=True）——如果某个期间的 filing_date 晚于 K 线时间，该期间会被排除。当某个期间没有可用的 filing_date 时，会改用假定的申报期限——季度表为期末后 45 天，年度表为 90 天（default_filing_lag_days）——而不是让报告在其期间结束当天就变得可见。前向运行使用期末资格判断（backtest_mode=False）。在 IDE 回测中请优先使用回调的 fundamentals 句柄；不带 use_filing_date=True 直接调用原始的 qc_fundamentals.get_data_with_offset(...) 可能相对申报日期出现前视。

前向运行：实盘运行大约每小时重新加载一次基本面数据，并在 Screener 数据更新之后约 5 分钟内重新加载。重新加载失败会保留之前的数据。由于前向运行的“现在”确实就是今天，上传时点的块（raw["ttm"]、raw["valuation"]["latest"] 等）在那里是当前数据，而不是前视。

**旧版回调：**较旧的策略可能使用单独的 qc_fundamentals 参数或原始 dict，而不是 BacktestFundamentals。现代签名把 fundamentals 作为第三个参数传给 on_bar / on_tick。模块级别名 fundamentals_as_of_bar 对应同样的与 K 线对齐的载荷形态。

fundamentals 回调参数

当加载了基本面数据时，引擎会把一个 BacktestFundamentals 句柄作为 fundamentals 参数传给 on_bar、on_tick，以及（在前向运行中使用时）on_timer：

快照的样子

与 K 线对齐的快照是一个嵌套字典，仅包含在该 K 线时点有效的期间（IDE 回测中按申报日期门控）。每个非空部分都包含一个 periodEnd 以及该报告的指标：

当在 K 线时间或之前没有符合条件的期间时，Trend 可以为 null。上面 earningsYield: -5.0 旁边的 priceToEarningsRatio: null 表示这是一家亏损公司，而不是数据缺失——参见估值。

绝不在快照中：ttm、valuation.latest、scores.notApplicableReason、metricsInputs、metricsHealth、companyInfo。它们是上传时点的数据而不是按期间的，把它们附加到 K 线上会把未来信息泄露进回测。请从 qc_fundamentals.raw[...] 读取它们。

同样的逐 K 线字典也出现在结构化回测结果中每一行的 fundamentals 字段下，所以你在策略中看到的内容与结果数据中显示的一致。

查找更早的期间（get_data_with_offset）

有时你想要的不是某根 K 线时点的最新报告，而是之前的一份——上一季度、上一财年、上一条盈利记录：

行为：

• **每个子表独立索引。**当 offset=1 时，balanceSheet.quarterly 部分后退一个季度，而 balanceSheet.yearly 后退一个财年，依此类推。
• 如果某个子表在当前 K 线之前没有足够的历史，则返回字典中它的部分为 null（并可能打印一行说明）。
• 形态与 current(...) 相同，外加顶层的 "offset": <int>。
• 在原始的 QcFundamentals API 上，首选签名为 f.get_data_with_offset(bar_time, offset, *, print_on_shortfall=True, use_filing_date=False)。模块级函数 get_data_with_offset(qc, bar_time, offset, *, print_on_shortfall=True) 没有 use_filing_date 参数——它始终使用期末资格判断，所以要获得时点式数据，请用 use_filing_date=True 调用方法（或使用回调句柄）。默认的 use_filing_date=False 表示仅按期末资格判断（可能相对申报日期出现前视）。使用 use_filing_date=True 时，缺少 filing_date 的期间会回退到期末后 45 天（季度）／90 天（年度）的假定期限。在 IDE 回测中请优先使用回调的 fundamentals 句柄，它会自动使用申报日期门控。

多标的基本面数据

当你加载多个数据包时（用于横截面或比较类策略），可以用 symbol="TICKER" 选择从哪一个读取：

• 省略 symbol 使用主数据包：如果只加载了一个，就是它；否则是已设置的 fundamentals.primary，再否则是被交易的标的，再否则是按字母顺序第一个已加载的代码。在多标的或 Screener 运行中，这个回退可能悄悄指向错误的公司——在那里请始终传入 symbol=symbol。
• fundamentals.symbols 列出当前已加载的每个大写代码键。
• fundamentals.primary_symbol() 返回主键。
• 你回测中交易的标的可以与你加载的基本面数据标的不同——例如交易 SPY，同时读取 AAPL 和 MSFT 的基本面数据。

可接受的 K 线时间

current(...) 和 get_data_with_offset(...) 都接受多种时间格式，所以你可以传入 bar["t"]、bar.t[0] 或你自己的值：

• datetime（朴素的按 UTC 处理），
• date，
• ISO 字符串（包括末尾的 Z），
• UNIX epoch 秒（int / float）。

---

实用模式

一些常见的形态：

---

基本面数据字段参考

字段是否可用取决于标的——并非每个发行人都会报告每一行。请在运行时使用 sorted(f.lists.keys()) 或 sorted(t.columns.keys()) 查看某个特定数据包实际暴露了什么。数值可能以字符串形式到达；计算时请用 float(...) 转换。

资产负债表

表：balanceSheet.quarterly、balanceSheet.yearly

现金流量表

表：cashFlow.quarterly、cashFlow.yearly

利润表

表：incomeStatement.quarterly、incomeStatement.yearly

盈利——History

表：earnings.History（按报告日期的已公布 EPS 与预期）

盈利——Trend

表：earnings.Trend（前瞻预期与修正）

盈利——Annual

表：earnings.Annual（年度已公布 EPS）

比率

表：ratios.quarterly、ratios.yearly

自指标扩展以来共有 91 个指标（算上 date、currency_symbol 和 filing_date 共 94 个键）。原始集合列在最前面；从营运资本往下的所有内容都是新增的。正在推出中的标的可能只带有原始集合，因此请用 sorted(f.table("ratios.quarterly").columns.keys()) 查看实际列表。

原始集合

此组中的利润率和回报率字段（grossMargin、operatingMargin 等）是小数比例——乘以 100 得到百分比。debtToEquity 已更名为 debtToEquityRatio。

营运资本

杠杆与覆盖

全部为普通小数（4 位小数）。

回报率

利润率与资本密集度

派息与回馈

全部为百分比（2 位小数）：dividendPayoutRatio、freeCashFlowPayoutRatio、shareholderPayoutToFreeCashFlow、retentionRatio、sustainableGrowthRate。

同比增长

全部为百分比（2 位小数）。营收／净利润／EPS 的增长在这里没有重复——它们在 earnings.Trend 中。

复合年增长率——仅限 yearly

全部为百分比（2 位小数），并且在每个 quarterly 期间上为 null——在季度期间上请求其中任何一个的筛选或规则会使每个标的失败。

revenueCagr3y / revenueCagr5y、netIncomeCagr3y / netIncomeCagr5y、epsCagr3y / epsCagr5y、freeCashFlowCagr3y / freeCashFlowCagr5y、dividendCagr3y / dividendCagr5y。

Financials extended

表：financialsExtended.quarterly、financialsExtended.yearly

字段因标的而异，此处不逐一列举。请在运行时查看已加载数据包暴露了什么：

常见字段包括扩展的 EBITDA 指标、营运资本构成，以及核心利润表中没有的每股数据。

已淘汰的字段：ebitda、ebitdaMargin、enterpriseValue、priceToEarnings、priceToBook、priceToSales、evToEbitda 和 evToRevenue 正在从 Financials extended 中撤销，改用估值和比率中的版本，它们按滚动十二个月口径计算（因此数值有所不同）。

每股

表：perShare.quarterly、perShare.yearly

一份按申报时口径的记录：sharesOutstanding 采用该期间所报告的拆股口径，因此无法跨越拆股边界进行比较。任何需要比较的内容请使用估值。除非另有说明，数值均为 4 位小数的字符串。

估值

表：valuation.quarterly、valuation.yearly（外加非表的 valuation.latest）

三条规则：

1. **倍数是 marketCap / 汇总值，而不是 price / perShare。**不要根据 perShare 重新计算——重述后的可比数据会让较早期间的两者出现分歧。
2. **符号收益率旁边出现 None 倍数是正确的，不是 bug。**下文标注为分母非正时为 null 的倍数，在其分母非正时会变成 None，而收益率和 bookToMarketRatio 保留其符号。亏损公司会显示 priceToEarningsRatio: None 并且 earningsYield: -5.0。
3. 倍数采用滚动十二个月口径，即使在季度期间也是如此——季度市盈率是真正的滚动市盈率，而不是年化的一个季度。

元数据

规模：marketCap、enterpriseValue ——2 位小数的金额字符串。

倍数（4 位小数的数字）

收益率——2 位小数的百分比，带符号：earningsYield、ebitToEnterpriseValueYield、freeCashFlowYield、operatingCashFlowYield、dividendYield、buybackYield、shareholderYield。

valuation.latest ——不是一个期间。一个单独的对象，带有上面的每个字段，外加 priceAsOf、priceAgeDays、priceSource、fundamentalsAsOf 和 ttmBasis。它位于日期键旁边，所以它不是表条目，也绝不会出现在 K 线时点快照中——在回测中读取它就是前视。请通过 qc_fundamentals.raw["valuation"]["latest"] 访问；没有可用价格时它为 None。

评分

表：scores.quarterly、scores.yearly

两种预期的缺失，都不是错误：

• 申报人的最早期间没有评分——它们需要有上一年可供比较。
• 对于 SIC 6000–6799（银行、券商、保险公司、REIT），两个桶都是空的，且 scores.notApplicableReason 为 "financial-sector-sic"。请把它当作“不适用”，而不是“无数据”。从 qc_fundamentals.raw["scores"]["notApplicableReason"] 读取它。

TTM

ttm 是单个对象，不是表——是截至上传时点（而不是任何 K 线）的滚动十二个月汇总。它绝不会出现在快照中；请通过 qc_fundamentals.raw["ttm"] 访问（在前向运行中安全，在回测中是前视）。

• 元数据：basis（"quarterly" / "annual"）、asOf、periodsUsed（list[str]）、complete（bool）、synthetic（bool——财年第四季度是重构得出的；正常，通常为 true）、coverageDays（约 365）。
• 流量——对 4 个季度求和，除 epsBasic / epsDiluted（4 位小数）外均为 2 位小数的字符串：totalRevenue、grossProfit、operatingIncome、ebit、ebitda、netIncome、epsBasic、epsDiluted、depreciationAndAmortization、interestExpense、incomeBeforeTax、incomeTaxExpense、costOfRevenue、sellingGeneralAdministrative、researchDevelopment、taxProvision、totalCashFromOperatingActivities、totalCashflowsFromInvestingActivities、capitalExpenditures、freeCashFlow、dividendsPaid、stockBasedCompensation、paymentsForRepurchaseOfCommonStock、proceedsFromIssuanceOfCommonStock、repaymentsOfLongTermDebt。
• 时点存量——最近的期间，从不求和，2 位小数的字符串：totalAssets、totalLiab、totalStockholderEquity、totalCurrentAssets、totalCurrentLiabilities、totalDebt、netDebt、cashAndShortTermInvestments、goodWill、intangibleAssets、netWorkingCapital、retainedEarnings、netReceivables、inventory、accountsPayable、propertyPlantAndEquipmentNet、preferredStockTotalEquity、commonStockSharesOutstanding、minorityInterest。

指标来源（metricsInputs / metricsHealth）

描述指标来自何处的扁平对象：

在依赖基于价格的字段之前，先检查 metricsHealth["prices"] != "absent"；"stale" 仍然可用——请与 priceAsOf 比较。**metricsInputs is None 表示数据包早于指标扩展。**字段会随着标的重新上传而逐个出现，因此覆盖范围在一段时间内参差不齐：请把上面的每个块都视为可选。

指标块的类型约定

**每个指标都可以独立为 null。**当期间对象的所有非元数据键都为 null 时，整个期间对象会被省略。块为空时是 {"quarterly": {}, "yearly": {}} ——绝不会是 null，也绝不会被丢弃。NaN / Infinity 从不出现。

公司信息

companyInfo 是扁平对象——它不以日期为键，也不会出现在 current(...) / get_data_with_offset(...) 快照中。请直接访问：

---

注意事项与陷阱

• **始终对 None 做保护。**如果没有配置基本面数据，fundamentals 为 None。在快照内部，个别部分（例如 earnings.Trend、scores）对某些 K 线也可能为 null，而指标扩展的块在较旧的数据包上可能完全缺失。
• 在多标的和 Screener 运行中始终传入 symbol= ——主数据包的回退可能不是你当前所处的代码。
• **数字可能是字符串。**底层 JSON 经常把数值指标作为字符串发送；做数学运算时请用 float(...) 转换。
• 最新在前的索引适用于以日期为键的表和偏移查找——索引 0 是该 K 线时点最近的符合条件的期间，1 是它之前的一个，依此类推。
• K 线的时间戳是判断哪份报告为“当前”的依据——直接传入 bar["t"]（或 bar.t[0]）；你不需要自己解析它。