数据 - get_data 详解

JHData.get_data() 是 jh_quant.data 最核心的方法，提供统一的数据获取体验。

方法签名

def get_data(
    self,
    data_type: DataTypes,
    bypass_cache: bool = False,
    **kwargs,
) -> JhDataType

时间参数（start / end）

通过 start 和 end 参数指定数据的时间范围：

df = jh.get_data(
    DataTypes.AK_STOCK_ZH_A_HIST_QFQ,
    symbol="000001",
    start="2024-01-01",
    end="2024-12-31",
)

支持的时间颗粒度

日期格式	示例	适用数据源
`YYYY-MM-DD`	`"2024-01-01"`	所有数据源
`YYYY-MM`	`"2024-01"`	`ak_` 数据源
`YYYY-MM-DD HH:MM:SS`	`"2024-01-01 09:30:00"`	`ak_` 分钟线

akshare 源（ak_ 前缀）：支持三种格式
tushare 源（ts_ 前缀）：仅支持 YYYY-MM-DD 格式
JiuHuang 源（jh_ 前缀）：仅支持 YYYY-MM-DD 格式

# 按月查询宏观经济数据
df = jh.get_data(
    DataTypes.AK_MACRO_CHINA_CPI,
    start="2024-01",
    end="2024-12",
)

symbol 参数

单个标的

df = jh.get_data(DataTypes.AK_STOCK_ZH_A_HIST_QFQ, symbol="000001")

批量查询（逗号分隔）

df = jh.get_data(
    DataTypes.AK_STOCK_ZH_A_HIST_QFQ,
    symbol="000001,600519,300750",
    start="2024-01-01",
    end="2024-12-31",
)

tushare 源的 ts_code 参数同样支持：

df = jh.get_data(
    DataTypes.TS_DAILY_QFQ,
    ts_code="000001.SZ,600519.SH,300750.SZ",
    start="2024-01-01",
    end="2024-12-31",
)

symbol 格式

akshare 源：纯数字代码，如 "000001"、"600519"
tushare 源：带交易所后缀，如 "000001.SZ"、"600519.SH"

批量分片

当 symbol 列表很长时，系统会自动将列表二分，分批下载后合并。

缓存机制

缓存命中逻辑

查询远程总数：先调用 API 获取符合条件的数据总量
比较本地缓存：查询本地缓存中符合条件的记录数
缓存命中：本地数量 == 远程数量 → 直接返回缓存数据
缓存过期：本地数量 > 远程数量 → 清除缓存表后重新下载
缓存未命中：本地数量 < 远程数量 → 从 API 下载数据，写入缓存

跳过缓存

df = jh.get_data(
    DataTypes.AK_STOCK_ZH_A_HIST_QFQ,
    symbol="000001",
    start="2024-01-01",
    end="2024-12-31",
    bypass_cache=True,
)

对于实时数据，建议使用 bypass_cache=True

手动清除缓存

jh.clear_cache(DataTypes.AK_STOCK_ZH_A_HIST_QFQ)

bypass_cache 参数

`bypass_cache` 值	行为
`False`（默认）	优先使用本地缓存
`True`	跳过缓存，强制从 API 下载

返回值

get_data() 返回 JhDataType，一个包装了 pd.DataFrame 的对象：

df = jh.get_data(DataTypes.AK_STOCK_ZH_A_HIST_QFQ, symbol="000001")

# 和普通 DataFrame 一样使用
print(df.head())
print(df["close"].mean())

# 额外的便捷属性
print(df.jh_dt)          # 数据类型
print(df.code_col)       # code 列名
print(df.date_col)       # date 列名

# 转回普通 DataFrame
plain = df.to_df()

get_data_total（预查数据量）

total = jh.get_data_total(
    DataTypes.AK_STOCK_ZH_A_HIST_QFQ,
    symbol="000001",
    start="2020-01-01",
    end="2024-12-31",
)
print(f"共 {total} 条数据")

if total < 100000:
    df = jh.get_data(DataTypes.AK_STOCK_ZH_A_HIST_QFQ, symbol="000001",
                     start="2020-01-01", end="2024-12-31")