Skip to content

ClickHouse 配置

zelqor 当前阶段已经具备第一版 ClickHouseProvider，可以直接读取：

  • 交易日历
  • 下一交易日
  • 指定交易日的股票 universe
  • 指定代码区间日线
  • 指定代码截至某日的最近 N 根日线
  • 指定交易日的全市场日线
  • 指定区间的全市场日线

当前 get_trading_dates(start_date, end_date) 的行为已经进一步收敛：

  • 先从 stock_day 取当前最大可用日期
  • 再用这个最大日期截断你传入的 end_date
  • 最后从 trade_days 返回有效交易日列表

这样交易日结果不会超出当前实际已有的日线数据范围。

当前默认表名与仓库现有口径一致：

  • stock_day
  • trade_days
  • security_master

时区约定

当前 ClickHouse 数据库中的数据按 UTC+8 口径存储和解释，也就是按 Asia/Shanghai 理解。

这意味着当前阶段以下字段都按上海时区交易日处理：

  • trade_days.datetime
  • stock_day.datetime
  • stock_day.date
  • provider 返回的 trade_date

当前 ClickHouseProvider 不做额外时区换算，而是假定数据库中的交易日口径已经是正确的 UTC+8 结果。

环境变量方式

最常用的方式是通过环境变量构造 ClickHouseConfig：

from zelqor.models import ClickHouseConfig

config = ClickHouseConfig.from_env()

支持的环境变量：

  • CH_HOST 或 CLICKHOUSE_IP
  • CH_USER 或 CLICKHOUSE_USER
  • CH_PASSWORD 或 CLICKHOUSE_PASSWORD

可选环境变量：

  • CH_PORT，默认 8123
  • CH_DATABASE，默认 tdxdata
  • CH_DAILY_TABLE，默认 stock_day
  • CH_TRADE_DAYS_TABLE，默认 trade_days
  • CH_SECURITY_TABLE，默认 security_master

配置文件方式

当前支持从 JSON 和 TOML 文件读取：

from zelqor.models import ClickHouseConfig

config = ClickHouseConfig.from_file("config.toml")

支持的 JSON 结构：

{
  "clickhouse": {
    "host": "127.0.0.1",
    "port": 8123,
    "database": "tdxdata",
    "user": "default",
    "password": "secret"
  }
}

支持的 TOML 结构：

[market_data.clickhouse]
host = "127.0.0.1"
port = 8123
database = "tdxdata"
user = "default"
password = "secret"

[market_data.source]
daily_table = "stock_day"

仓库内已经提供了一个示例文件：

  • config.example.toml

推荐做法是复制出本地私有配置：

Copy-Item config.example.toml config.toml

然后把 host、database、user、password 改成你的远程数据库信息。

与 Provider 配合使用

from zelqor.data.clickhouse import ClickHouseProvider
from zelqor.models import ClickHouseConfig

config = ClickHouseConfig.from_env()
provider = ClickHouseProvider(config)

bars = provider.get_bars(
    codes=["000001.SZ", "sh600000"],
    end_date="2025-03-25",
    count=15,
    as_numpy=False,
)

返回结构

  • get_bars(..., as_numpy=False) 返回 dict[str, pandas.DataFrame]
  • get_bars(..., as_numpy=True) 返回 dict[str, BarSeries]
  • get_daily_bars(..., as_numpy=True) 默认返回 dict[str, BarSeries]
  • get_market_bars(..., as_polars=True) 默认返回 polars.DataFrame
  • get_market_bars(..., as_polars=False) 返回 pandas.DataFrame
  • get_market_daily_bars(..., as_polars=True) 默认返回 polars.DataFrame
  • get_market_daily_bars(..., as_polars=False) 返回 pandas.DataFrame

其中 BarSeries 使用结构化 NumPy，字段口径固定为：

  • code
  • trade_date
  • open
  • high
  • low
  • close
  • pre_close
  • high_limit
  • low_limit
  • volume
  • amount

如果策略本身是“全市场批量筛选”模式，推荐优先用：

  • get_market_bars(...)
  • get_market_daily_bars(...)

先把整张市场日线表拉回本地，再结合 Polars 或 pandas 做筛选、排序和打分。

真实库联调测试

仓库内有一个真实 ClickHouse 联调测试文件：

  • tests/test_clickhouse_live_integration.py

这个测试会：

  • 从 CH_CONFIG_FILE 指向的文件读取配置
  • 如果没有设置，则默认读取仓库根目录下的 config.toml
  • 自动从 trade_days 中发现一个可用交易日
  • 自动从当天 universe 中挑一只股票
  • 验证 get_trading_dates
  • 验证 get_universe
  • 验证 get_daily_bars
  • 验证 get_bars

运行方式：

uv run --python .venv\Scripts\python.exe pytest tests/test_clickhouse_live_integration.py -q

如果配置文件不存在，测试会自动跳过。

当前边界

这一阶段已经实现了真实 SQL 查询与结果标准化，但还没有继续往上接：

  • Python 策略文件加载
  • selector 执行
  • 回测主循环
  • broker / portfolio / report