JoinQuant API 对比：history 与 attribute_history 的区别与应用

在 JoinQuant 聚宽平台的回测和模拟交易环境中，history 和 attribute_history 都是用于获取历史行情数据的 API，但它们的设计目的和返回数据的结构有明显的区别。

简单来说：history 用于获取“多只股票”的“单个字段”数据；attribute_history 用于获取“单只股票”的“多个字段”数据。

以下是详细的对比说明：

1. 核心区别对比表

2. 详细功能解析

history

该函数主要用于获取多只标的在同一个属性（如收盘价）上的历史数据。

• 函数原型：history(count, unit='1d', field='avg', security_list=None, df=True, ...)
• 参数重点：
  • field: 只能是一个字符串，例如 'close' 或 'volume'。
  • security_list: 一个股票代码列表。如果为 None，则自动获取 set_universe 设置的股票池。
• 返回值：
  • 如果 df=True（默认），返回 pandas.DataFrame。索引是时间，列名是股票代码。

代码示例：

# 获取平安银行和万科A过去5天的收盘价
# 返回的 DataFrame 列是 '000001.XSHE' 和 '000002.XSHE'
h = history(5, unit='1d', field='close', security_list=['000001.XSHE', '000002.XSHE'])

attribute_history

该函数主要用于获取单只标的在多个属性（如开盘价、收盘价、成交量等）上的历史数据。

• 函数原型：attribute_history(security, count, unit='1d', fields=['open', 'close', ...], ...)
• 参数重点：
  • security: 必须是一个字符串（单只股票代码）。
  • fields: 可以是一个列表，包含多个字段，例如 ['open', 'close', 'high', 'low']。
• 返回值：
  • 如果 df=True（默认），返回 pandas.DataFrame。索引是时间，列名是属性名称（open, close 等）。

代码示例：

# 获取平安银行过去5天的开盘价和收盘价
# 返回的 DataFrame 列是 'open' 和 'close'
h = attribute_history('000001.XSHE', 5, unit='1d', fields=['open', 'close'])

3. 总结与建议

• 如果你需要计算某一只股票的 MACD、KDJ 等技术指标，需要同时用到该股票的最高价、最低价、收盘价等数据，请使用 attribute_history。
• 如果你需要计算股票池中所有股票的涨跌幅排名，或者获取所有股票昨天的收盘价来计算市值，请使用 history。

Q&A

Q: 这两个函数包含当前时间的数据吗？
A: 不包含。

• 当获取天频率数据时（unit='1d'），返回的是截止到前一个交易日的数据，即使是在收盘后调用也不包含当天。
• 当获取分钟频率数据时（unit='1m'），不包含当前这一分钟的数据，避免未来函数。
• 如果需要获取当前时刻的实时数据（如当前最新价、涨跌停价），请使用 get_current_data() 或 get_current_tick()。

Q: 如果我想获取多只股票的多个字段数据怎么办？
A: history 和 attribute_history 都不直接支持“多对多”的 DataFrame 返回。

• 方法一：使用 get_price 函数（通用性更强，支持多标的多字段，但在回测中要注意 end_date 的设置以避免未来函数）。
• 方法二：使用 history 获取不同字段多次，然后自行合并（效率较低）。
• 方法三：在循环中对每只股票调用 attribute_history（适合逐个处理股票逻辑的场景）。

Q: 这两个函数在研究环境（Notebook）中能用吗？
A: 文档中提到这两个是“回测环境/模拟专用API”。在研究环境中，建议使用 get_price 来获取历史数据，它在研究和回测中均可使用且功能更强大。