DATA MODULE · 01

数据模块 / 使用文档

统一登记、读取与更新研究数据。用配置描述数据的位置和形态，用稳定接口屏蔽 Parquet、JSON 与目录分区之间的差异。

当前版本 v1.1阅读时间 约 8 分钟更新于 2026-10-28

DATA

ARCHITECTURE

架构介绍

数据模块位于所有研究流程的上游，以 DataConfig.ini 作为唯一注册表。业务代码只依赖统一的 Data Client，不直接感知文件位置、格式或供应商连接方式。

01 · SOURCES数据源

RQData · FRED
本机文件 · 人工维护

02 · REGISTRY配置注册表

DataConfig.ini
路径 · 字段 · 更新器

03 · SERVICE统一访问层

Local / HTTP Client
Schema · Query · Update

04 · CONSUMERS研究消费者

因子 · 策略
回测 · 分析

设计原则

配置描述“数据是什么、在哪里、怎样更新”；Reader 负责“怎样读取”；上层模块只使用稳定的数据集 ID。修改配置后需要重启数据服务，使注册表快照重新加载。

GETTING STARTED

使用说明

确认服务与目录

在控制台打开「数据」模块。服务状态为运行中后，目录会从 DataConfig 注册表载入；先通过预览确认字段和日期覆盖。

选择更新方式

auto 数据集可手动触发增量更新，也可加入每日计划；manual 数据集由人工维护，界面会显示原因。

通过稳定 ID 查询

在程序中使用数据集 ID 和日期范围，不拼接真实磁盘路径。大结果优先走 Python Client 或 Arrow HTTP 响应。

本机读取数据模块

PYTHON

from quant_platform_sdk import ResearchClient

# 本机模式直接读取 DataConfig 和物理文件，不经过 HTTP。
research = ResearchClient.local("PlatformConfig.ini")
data = research.data.context(as_of="2026-09-18")

latest = data.latest(
    "market_daily",
    fields=["open", "close"],
    order_book_ids=["000001.XSHE"],
)
history = data.history(
    "market_daily",
    lookback=20,
    fields=["close"],
)
print(latest.head(), history.shape)

↔同一调用契约，按部署位置切换后端

业务代码只在组合根选择 local 或 remote；进入 context 后的查询方法、日期语义与返回 DataFrame 保持一致。

LOCAL ROUTE

平台本机直接读文件

ResearchClient.local(PlatformConfig.ini)
Data 解析 DataConfig 与 Reader Adapter
Factor 合并 FactorConfig、旧分组与 FactorLibrary
上传因子在本机计算时网络请求数为 0

HTTP ROUTE

其他电脑通过服务读取

ResearchClient.remote(…)
Data 请求 Data Service，Factor 请求 Factor Service
Arrow 分页会自动协商服务端行数上限
FRP 前必须配置鉴权网关，不直接暴露服务端口

其他电脑 / HTTP 读取 Data 与 Factor

PYTHON

import os
from quant_platform_sdk import ResearchClient

# 已安装平台 SDK 时，使用统一只读网关。
research = ResearchClient.remote(
    base_url="http://82.156.35.38:18010",
    token=os.environ["QUANT_RESEARCH_TOKEN"],
)

data = research.data.context(as_of="2026-09-18")
factors = research.factors.context(as_of="2026-09-18")

bars = data.history("market_daily", lookback=20, fields=["close"])
alpha = factors.latest("alpha_v3", fields=["KDJ_K"])

# 如果网关统一提供 /data 与 /factors，也可以写：
# 未安装平台 SDK 时，下载下方最小包，使用 client.py。

READ CONTRACTavailable_dates(id)

列出在 as_of 截止前可用的日期

READ CONTRACTlatest_date(id)

取得最近可用日期

READ CONTRACTprevious_date(id, before=…)

向前定位一个或多个可用日期

READ CONTRACTcommon_date(ids)

取得多个数据集共同的最近日期

READ CONTRACTlatest(id)

读取 as_of 截止的最新截面

READ CONTRACTon_date(id, date)

读取指定日期；可显式允许 previous fallback

READ CONTRACThistory(id, lookback=…)

读取受 as_of 约束的历史窗口

READ CONTRACTtable(id)

读取非日分区表或完整表

Data 专用语义

宏观长表可使用 macro_latest(dataset_id, series_ids=…, fields=…) 按 as_of 选择每个序列当时已发布的最新观测。所有查询均支持 fields、order_book_ids 或 series 筛选；不要在业务代码中拼接磁盘路径。

远程访问安全边界

Client 可以发送 Bearer Token，但 8001 / 8002 / 8003 当前不自行校验令牌。通过 FRP 提供外网访问时，必须由前置 Gateway 完成 TLS、身份认证、授权、限流和审计；裸服务只监听本机地址。

TIP

自动更新未显式传入 end 时，北京时间 20:00 前默认更新到上一完成交易日，避免日终数据尚未产出造成误报。

UPLOAD CONTRACT

上传规范说明

数据模块以配置登记为主。新增本机数据时，先按约定落盘，再在 DataConfig.ini 声明存储、日期和逻辑字段；敏感凭据只允许放在本机 secret.ini 或环境变量中。

01命名与路径

数据集 ID 稳定、可读且全局唯一；路径相对数据根目录解析。禁止在研究代码中硬编码机器绝对路径。

[dataset.market_daily]

02分区与格式

推荐 Parquet。日频截面使用 YYYY-MM-DD.parquet；月分区使用 YYYY-MM.parquet 并在文件内保留 date。

layout = date_partitions

03字段与主键

明确 date、id、series、value 字段。股票日频数据通常以 (date, order_book_id) 保证唯一。

id_field = order_book_id

04更新与校验

auto 条目必须绑定已注册 updater；manual 条目说明维护原因。启动服务时会一次性校验完整配置。

update_method = auto

上传前检查

日期格式使用 YYYY-MM-DD；同一主键不得重复；字段类型在不同分区间保持一致；目录中不要混入不符合 file_pattern 的临时文件。

API REFERENCE

接口说明

前端统一访问同源 BFF 路径 /api/data/…，由 Next.js 转发到本机服务。业务错误使用 JSON detail.code 与 detail.message 描述。

BASE URL http://127.0.0.1:3000

方法路径说明

GET/api/data/catalog

读取已启用的数据目录、分组和更新能力

↗

GET/api/data/{datasetId}/schema

查看字段名、类型与逻辑主键

↗

GET/api/data/{datasetId}/preview

预览受限行数的数据样本

↗

POST/api/data/{datasetId}/query

按日期、字段与证券范围查询数据

↗

POST/api/data/updates

触发一个或多个数据集的增量更新

↗

GET/api/data/updates/tasks/{taskId}

轮询后台更新任务进度与逐项结果

↗

GET · PUT/api/data/updates/schedule

读取或保存每日自动更新计划

↗

200

请求成功同步结果或任务快照

400

参数不合法范围、字段或限制错误

404

资源不存在目录项、文件或任务缺失

422

契约校验失败类型或必填字段错误

500

执行失败上游或本机运行时错误

HTTP ACCESS & DOWNLOADS

HTTP 接口与客户端下载

其他电脑通过只读网关获取数据和因子。公网入口为 http://82.156.35.38:18010，局域网入口为 http://10.7.12.69:8010；地址变动时修改客户端 config.json。网页 3000 端口用于文档与控制台。

完整接口文档逐项目录、字段、日期、分页与错误码最小 Python 客户端5.3 KB · 空 Token · 无运行环境

安装 Python 3.11+，解压最小包。
把管理员提供的只读 Token 填入 token.txt。
执行 python test_connection.py 验证 HTTP 与鉴权（仅需标准库）。
执行 python -m pip install -r requirements.txt，再运行 python test_connection.py --full 和 python fetch_data.py demo。

下载内容

包含 test_connection.py、client.py、fetch_data.py、config.json、requirements.txt、README.txt 和空 token.txt；不包含真实凭据、平台源码、数据文件或 Python。网关仅开放读取接口，SDK 的 table、common_date 等完整本机方法不在公网最小范围内。

股票逐笔与十档盘口

market_tick_trades 为逐笔成交，market_tick_orders 为逐笔委托，market_tick_quotes 为十档盘口快照。目前是 2025 年 9 月历史 CSV 的手工导入；请限定单日、单只证券并分页读取。

最小客户端读取逐笔成交

PYTHON

from client import Client, save

client = Client()  # 从 config.json 和 token.txt 读取地址与凭据
trades = client.data(
    "market_tick_trades",
    start="2025-09-01", end="2025-09-01",
    ids=["000001.SZ"],  # 逐笔使用万得代码，日线使用 000001.XSHE
    fields=["时间", "成交价格", "成交数量"],
    limit=100,
)
save(trades, "output/trades.parquet")

逐笔字段语义

证券使用 000001.SZ / 600000.SH；原始字段（包括价格、数量和事件标志）按字符串保留，可能包含 NUL。价格缩放单位待核实，请勿自动除以 100 或 10000；推荐 Parquet 保留原值。逐笔记录不能以“日期 + 股票”作为唯一主键。完整字段与日期覆盖见接口文档。