K 线数据 API¶

概述¶

get_kline() 用于查询币安永续合约的 K 线（蜡烛图）数据，底层通过 DolphinDB KlineMasterRepo 执行查询，支持 8 种周期、多标的批量查询和分页。

功能特性¶

单标的或多标的批量查询
8 种 K 线周期（1m 至 1d）
按需选择返回字段，减少数据量
分页支持（limit + offset）
复权类型选择（不复权 / 前复权 / 后复权）

API 接口¶

`get_kline()`¶

函数签名¶

client.get_kline(
    symbol: str | List[str],
    start_date: str,
    end_date: str,
    frequency: str = "1h",
    fields: str = "*",
    limit: int = 2_000_000,
    offset: int = 0,
    adjust_type: str = "none",
) -> pd.DataFrame

等价写法（通过子服务）：

client.kline.get_kline(symbol=..., start_date=..., end_date=..., ...)

参数说明¶

参数	类型	默认值	说明
`symbol`	`str \\| List[str]`	必填	合约代码，如 `"BTCUSDT"` 或 `["BTCUSDT", "ETHUSDT"]`
`start_date`	`str`	必填	起始日期，格式 `YYYY-MM-DD`（含当天）
`end_date`	`str`	必填	结束日期，格式 `YYYY-MM-DD`（含当天）
`frequency`	`str`	`"1h"`	K 线周期，见下方频率速查表
`fields`	`str`	`"*"`	返回字段，逗号分隔，`"*"` 表示全部字段
`limit`	`int`	`2_000_000`	最大返回行数
`offset`	`int`	`0`	分页偏移量（跳过前 N 行）
`adjust_type`	`str`	`"none"`	复权类型：`"none"` / `"pre"` / `"post"`

支持的 K 线周期¶

frequency	含义
`"1m"`	1 分钟
`"5m"`	5 分钟
`"15m"`	15 分钟
`"30m"`	30 分钟
`"1h"`	1 小时（默认）
`"2h"`	2 小时
`"4h"`	4 小时
`"1d"`	日线

不支持的周期

传入不在上表中的 frequency 值（如 "3m"、"6h"）会抛出 ValueError：

ValueError: invalid frequency: '6h'. Supported values: ['1d', '1h', '1m', '2h', '30m', '4h', '5m', '15m']

返回值¶

返回 pd.DataFrame，按 (datetime, symbol) 排序。无数据时返回空 DataFrame。

列名	类型	说明
`datetime`	`datetime`	K 线开始时间
`symbol`	`str`	合约代码
`open`	`float`	开盘价
`high`	`float`	最高价
`low`	`float`	最低价
`close`	`float`	收盘价
`volume`	`float`	成交量（张）
`turnover`	`float`	成交额（USDT）
`trade_count`	`int`	成交笔数
`taker_buy_volume`	`float`	主动买入成交量
`taker_buy_turnover`	`float`	主动买入成交额

使用 fields 参数过滤列

如只需要 OHLCV 核心字段，可指定：

fields="datetime,symbol,open,high,low,close,volume"

使用示例¶

单标的查询¶

import zer0data as zd

client = zd.Client()

df = client.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-01-31",
    frequency="1h",
)
print(f"数据形状: {df.shape}")
print(df.head())

多标的批量查询¶

df = client.get_kline(
    symbol=["BTCUSDT", "ETHUSDT", "SOLUSDT"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    frequency="1d",
)

# 按标的分组统计
print(df.groupby("symbol").size())

指定返回字段¶

# 只返回 OHLCV 核心字段，减少内存占用
df = client.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-12-31",
    frequency="1h",
    fields="datetime,symbol,open,high,low,close,volume",
)
print(df.columns.tolist())
# ['datetime', 'symbol', 'open', 'high', 'low', 'close', 'volume']

分页查询¶

PAGE_SIZE = 10_000

# 第 1 页
page1 = client.get_kline(
    symbol="BTCUSDT",
    start_date="2023-01-01",
    end_date="2023-12-31",
    frequency="1m",
    limit=PAGE_SIZE,
    offset=0,
)

# 第 2 页
page2 = client.get_kline(
    symbol="BTCUSDT",
    start_date="2023-01-01",
    end_date="2023-12-31",
    frequency="1m",
    limit=PAGE_SIZE,
    offset=PAGE_SIZE,
)

直接使用子服务¶

# client.get_kline(...) 与以下写法完全等价
df = client.kline.get_kline(
    symbol="BTCUSDT",
    start_date="2024-01-01",
    end_date="2024-01-31",
)

错误处理¶

try:
    df = client.get_kline(
        symbol="BTCUSDT",
        start_date="2024-01-01",
        end_date="2024-01-31",
        frequency="6h",  # 不支持的周期
    )
except ValueError as e:
    print(f"参数错误: {e}")

⚡ 性能优化建议¶

缩小时间范围：优先查询较短的时间窗口，避免单次返回千万行
指定 fields：只选择需要的列，降低 DolphinDB 传输压力
使用日线/小时线：分钟线数据量约是小时线的 60 倍，按需选择周期
分页处理大数据集：超过 100 万行时建议使用 limit + offset 分批获取

注意事项¶

日期格式：start_date / end_date 仅支持 YYYY-MM-DD 字符串，两端均含
空结果：查询时间段内无数据时返回空 DataFrame，不抛异常
默认 limit：limit 默认值为 200 万行，超大范围查询时请手动控制
DolphinDB 连接：使用前确保 DolphinDB 服务可访问，否则在调用时报连接错误

下一步： 查看合约元数据 API →