JoinQuant 数据 API：get_bars 函数 include_now 参数详解

在 JoinQuant（聚宽）平台中，若需要获取包含当前正在进行且尚未结束的分钟 Bar 数据（即包含当前时刻的快照数据），最直接且推荐的方法是使用 get_bars 函数，并设置参数 include_now=True。

以下是具体的实现方法和代码示例。

核心方法：get_bars

get_bars 是聚宽获取行情数据的核心函数，通过设置 include_now=True，它会将当前时刻的 Tick 数据合成到最后一根 Bar 中返回。

代码示例

# -*- coding: utf-8 -*-
from jqdata import *

def initialize(context):
    # 设置我们要操作的股票
    g.security = '000001.XSHE'
    # 设置基准
    set_benchmark('000300.XSHG')
    # 开启动态复权模式(真实价格)
    set_option('use_real_price', True)
    # 每天盘中运行
    run_daily(handle_trade, 'every_bar')

def handle_trade(context):
    # 获取过去5分钟的数据，并且包含当前这一分钟（尚未走完）的数据
    # unit='1m' 表示1分钟线
    # include_now=True 是关键，表示包含当前正在进行的Bar
    bars = get_bars(g.security, count=5, unit='1m',
                    fields=['date', 'open', 'high', 'low', 'close', 'volume'],
                    include_now=True, df=True)
    
    # 打印数据查看
    # 最后一行的 'close' 即为当前的最新价
    # 最后一行的 'high'/'low' 为当前这一分钟截至目前的最高/最低价
    log.info("\n" + str(bars))
    
    # 获取当前最新价格（即最后一根Bar的收盘价）
    current_price = bars['close'].iloc[-1]
    log.info("当前分钟（含未结束）最新价: " + str(current_price))

关键参数说明

在 get_bars(security, count, unit, fields, include_now, ...) 函数中：

1. include_now=True：

   • 这是实现需求的核心参数。
   • 当设为 True 时，返回的数据最后一条是当前时刻所在的 Bar。
   • 例如：策略时间是 09:33:20，unit='1m'。
     • include_now=False（默认）：返回的最后一条数据时间是 09:33（代表 09:32:00-09:33:00 的完整数据）。
     • include_now=True：返回的最后一条数据时间是 09:34（代表 09:33:00-09:33:20 的合成数据），其 close 为最新价，volume 为这20秒的累积成交量。

2. unit：

   • 设置为 '1m' 获取 1 分钟线。也可以设置为 '5m', '15m' 等。如果设置为 '5m' 且 include_now=True，最后一根 Bar 将包含当前 5 分钟周期内截至目前的合成数据。

3. df=True (可选)：

   • 建议设置为 True，返回 pandas.DataFrame 格式，便于后续的数据处理和计算。

注意事项

1. 未来函数风险：在回测模式下，get_bars 获取分钟数据通常不会引入未来函数（除非你显式指定了未来的 end_dt）。但在编写策略逻辑时请注意，包含 include_now=True 的 Bar 是变动的。在这一分钟结束前，High、Low、Close、Volume 都会随着新的 Tick 到来而改变。
2. 与其他 API 的区别：
   • history() / attribute_history()：通常只返回已完成的时间单位数据，不包含当前正在进行的 Bar。
   • get_price()：虽然也可以获取数据，但在处理“当前分钟”的逻辑上不如 get_bars 的 include_now 参数直观和可控。
3. 合成逻辑：当 include_now=True 时，系统实际上是利用当前的 Tick 数据与已有的分钟数据进行实时合成。

Q&A

Q: get_bars 和 get_current_data 有什么区别？
A: get_current_data() 获取的是当前时刻的快照（如涨跌停价、最新价、是否停牌等），它返回的是一个对象，不包含历史序列。而 get_bars(include_now=True) 返回的是时间序列数据（K线），既包含历史 K 线，也包含当前这一根正在形成的 K 线，适合用于计算技术指标（如计算包含当前价格的 MA5）。

Q: 如果我在 09:30:05 调用 get_bars(unit='1m', include_now=True) 会返回什么？
A: 会返回包含 09:31 (标签时间) 的 Bar。虽然这一分钟才过了5秒，但系统会根据这5秒的 Tick 生成一根 K 线，其 Open、High、Low、Close 可能相同（如果只有一笔成交），Volume 为这5秒的成交量。

Q: include_now=True 可以用于日线 (unit='1d') 吗？
A: 可以。如果在盘中调用 get_bars(unit='1d', include_now=True)，返回的最后一条数据就是当天的日 K 线（截至调用时刻），其 Close 为最新价，High/Low 为当天的最高/最低价。这在盘中判断日线形态时非常有用。