shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringAPI key requirement unconfirmed

dolphindb

Complete technical documentation and best practices for DolphinDB time-series database. It includes 1490 technical documents + 3 official white papers, covering all scenarios such as database design, stream computing, quantitative backtesting, function queries, etc.

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

DolphinDB 技术决策与文档导航

何时调用：遇到 DolphinDB/DolphinScript 任务，或在代码中看到 dfs://、createPartitionedTable、context by、streamTable、Backtest:: 等专有线索时使用；已有 DolphinDB 上下文的分区、流计算、回测和排障问题同样适用。

技能版本 2.2.0 · 本地文档快照 含 Server 3.00.6 发布说明 · 实际运行版本 以目标 Server 与插件为准。 资料 2,883 篇带正文的 HTML 页面目录 + 既有白皮书蒸馏层 + 历史 doc_*.md 镜像。新手先读 关于 DolphinDB。

使用顺序

  1. 确认目标 Server 与相关插件的实际版本；未知时在代码和建议中标明版本前提。版本升级先查 版本与兼容性 与 来源核查卡。
  2. 按任务选择下表的能力卡，再核对具体函数的参数、类型、版本条件和输入输出表结构。完成标准是每个关键 API 都有可定位的原文路径。
  3. 在仓库中先用 最新文档目录 搜标题；需查正文时运行 python3 scripts/latest_docs.py search '关键词'，随后运行 python3 scripts/latest_docs.py show funcs/c/createPartitionedTable.html。脚本默认读取同级 dolphindb_doc/documentation.latest.zh/，其他位置用 --root 指定。
  4. 交付代码前列出版本、数据 schema、外部插件/配置、验证查询；未连接 Server 时明确代码是按文档核验的骨架。

| 任务 | 先读 | | --- | --- | | API 签名、兼容性、旧目录条目 | 版本与来源核查 | | OLAP/TSDB/PKEY/IOT 选型与建库建表 | 四引擎选型 | | 流计算窗口、迟到数据、快照与 Orca 恢复 | 流计算与恢复 | | Backtest 事件策略、行情结构与新旧接口 | 新版回测闭环 | | 具体错误码、新函数或未蒸馏主题 | 最新文档目录 或正文检索脚本 |

⚡ 蒸馏知识层（写代码前优先查阅）

下列内容源自较早的 3.00.4 白皮书蒸馏，可用于理解架构；遇到存储引擎、流引擎高可用或 Backtest 接口问题，先读上方按新快照核验的能力卡，再用最新目录核对函数页。

  • 🎯 cheatsheet.md — 存储引擎选型、流引擎选择矩阵、撮合/回放/策略语言判据、关键阈值。
  • 📇 glossary.md — 三领域约 85 术语一句话定义。
  • 🧩 patterns.md — 23 个可复用模式（何时用 / 如何 / 权衡）。

蒸馏章节（references/distilled/chapters/，每章 2–3K tokens，按需加载）：

| # | 章节 | 关键主题 | |---|------|---------| | ch01 | 分布式架构与集群 | 节点角色、2PC/MVCC 事务、计算存储分离 | | ch02 | TSDB 与 OLAP 白皮书精读 | 原有两引擎细节；PKEY/IOT 见四引擎选型卡 | | ch03 | SQL 与库内计算 | DolphinScript、函数模式、元编程、函数视图、mr | | ch04 | 安全容灾 / 运维 / 生态 | Raft 高可用、副本、异步复制、备份、作业调度 | | ch05 | 流表与发布订阅 | streamTable、keyedStreamTable、subscribeTable、持久化 | | ch06 | 流计算引擎（核心） | 12 引擎选择、ReactiveState、TimeSeries、CrossSectional、AsofJoin | | ch07 | 流批一体 / 运维 / API | replay、异构回放、streamFilter、流批一体；高可用按版本核验 | | ch08 | 回放与模拟撮合 | replay/replayDS、createMatchEngine、insertMsg、撮合模式 | | ch09 | 旧白皮书回测案例 | 旧接口及策略语言案例；新代码先读新版回测闭环卡 |

主题 → 章节：

  • 存储引擎选型 / 分区 → 四引擎选型卡、ch02、ch01 · SQL/库内计算 → ch03 · 高可用/容灾 → 流计算与恢复卡、ch04、ch07
  • 流引擎选择 / K线 / 因子流式 → ch06 · 流表订阅 → ch05 · 回放 → ch07, ch08
  • 模拟撮合 → ch08 · 回测引擎 / 策略语言 → 新版回测闭环卡、ch09 · 元编程/函数视图 → ch03

🚀 快速上手代码

可直接改用的骨架。完整选型判据见 cheatsheet.md，深入见对应章节。

1. TSDB 分区表（按证券和时间点查、去重 → 四引擎选型卡）

// 组合分区: VALUE(日期) + HASH(股票代码)
db_date = database(, VALUE, 2024.01.01..2024.12.31)
db_sym  = database(, HASH, [SYMBOL, 10])
db = database("dfs://stock_data", COMPO, [db_date, db_sym], engine="TSDB")

schemaTable = table(1:0, `trade_date`trade_time`symbol`price`volume,
                    [DATE, TIMESTAMP, SYMBOL, DOUBLE, LONG])

pt = db.createPartitionedTable(
    table=schemaTable, tableName="stock_tick",
    partitionColumns=`trade_date`symbol,
    sortColumns=`symbol`trade_time,  // 多列时末列可为时间或整型
    keepDuplicates=LAST)             // 对全部 sortColumns 相同的记录保留最后一条

写入前从 trade_time 生成 trade_date，并确保日期落在已定义的 VALUE 分区内。engine 是 database 的参数，createPartitionedTable 不接受该参数；建表只复制 schema，写入需另行 append! 或 tableInsert。

2. OLAP 分区表（批量分析 → ch02）

db = database("dfs://stock_analysis", VALUE, 2024.01M..2024.12M, engine="OLAP")
schemaTable = table(1:0, `trade_date`symbol`open`high`low`close`volume,
                    [DATE, SYMBOL, DOUBLE, DOUBLE, DOUBLE, DOUBLE, LONG])
pt = db.createPartitionedTable(
    table=schemaTable, tableName="daily_kline",
    partitionColumns=`trade_date)

3. 实时 K 线合成（流计算 → ch05, ch06）

// 1. 创建流表
share streamTable(1:0, `time`sym`price`vol, [TIMESTAMP, SYMBOL, DOUBLE, INT]) as tickStream
share streamTable(1:0, `time`sym`open`high`low`close`volume,
                  [TIMESTAMP, SYMBOL, DOUBLE, DOUBLE, DOUBLE, DOUBLE, LONG]) as klineStream

// 2. 时序聚合引擎（1 分钟窗口）
tsEngine = createTimeSeriesEngine(
    name="kline_1min", windowSize=60000, step=60000,
    metrics=<[first(price), max(price), min(price), last(price), sum(vol)]>,
    dummyTable=tickStream, outputTable=klineStream, timeColumn=`time, keyColumn=`sym)

// 3. 订阅流表 + 4. 插入测试
subscribeTable(tableName="tickStream", actionName="kline", handler=append!{tsEngine})
insert into tickStream values(2024.01.01T09:30:00.000, `600000, 10.5, 1000)
insert into tickStream values(2024.01.01T09:31:00.000, `600000, 10.6, 200)

示例采用事件时间；窗口结束后的下一条数据才触发前一窗口输出。输出表列顺序须与引擎的时间列、分组列和指标结果一致。3.00.5 及之后引擎 raftGroup 不生效，恢复方案见 流计算与恢复。

4. 股票分钟行情回测骨架（新版事件接口 → 回测卡）

对照 官方快速上手 与 接口说明。下例中的 minuteBars 是待准备的行情表，列名与类型须按股票回测配置核对；本骨架尚未在 Server 上运行。

loadPlugin("Backtest")

// 1. 分钟行情触发 onBar；msg 以证券代码为键
def onBar(mutable context, msg, indicator){
    for(sym in msg.keys()){
        pos = Backtest::getPosition(context.engine, sym)
        if(pos.longPosition < 1){
            price = msg[sym].close
            Backtest::submitOrder(context.engine,
                (sym, context.tradeTime, 5, price, 100, 1), "buy")
        }
    }
}

// 2. 配置与回调按名称绑定
config = {startDate: 2024.01.01, endDate: 2024.01.01,
          strategyGroup: `stock, cash: 1000000.,
          commission: 0.00015, tax: 0.001, dataType: 3}
callbacks = {onBar: onBar}

// 3. 准备 minuteBars 后创建引擎、执行并结束回测
engine = Backtest::createBacktester("minuteDemo", config, callbacks, false)
Backtest::appendQuotationMsg(engine, minuteBars)
Backtest::appendEndMarker(engine)
tradeDetails = Backtest::getTradeDetails(engine)
returnSummary = Backtest::getReturnSummary(engine)

createBacktestEngine 是仍可兼容的旧接口；其回调按位置传参，且不支持 JIT。不同资产、行情频率和 Server/插件版本需先查各自配置页。 重复执行骨架前，应更换引擎名称，或先确认可以删除已有同名引擎。

5. 高级 SQL（时序专用 → ch03）

// Context By - 组内窗口计算
select trade_date, symbol, close, movingAvg(close, 5) as ma5, movingAvg(close, 20) as ma20
from loadTable("dfs://stock", "daily") context by symbol

// Pivot By - 数据透视
select close from loadTable("dfs://stock", "daily")
where symbol in `600000`600001`600002 pivot by trade_date, symbol

// Asof Join - 时序非精确关联（取时间就近的一条）
select * from tick_data aj snapshot_data
on tick_data.time = snapshot_data.time and tick_data.symbol = snapshot_data.symbol

📚 资源索引

官方白皮书原文（蒸馏层来源，需逐行细节时查）：

最新文档：2,883 篇正文页面见 LATEST_CATALOG.md；本地全文用 scripts/latest_docs.py 搜索。历史 CATALOG.md 对应旧镜像，编号文件有碰撞，遇到标题与内容不符按原始 URL 复核。 常用参考：数据库分区 · TSDB · PKEY · IOT · Orca 外部：官网 · 文档中心 · 社区 · GitHub

📊 版本

  • 2.2.0（2026-09-23）接入 2,883 篇本地中文正文目录；增加版本、四引擎、流恢复和新版回测能力卡；修正建库参数和回测接口。
  • 2.1.0（2026-07-01）新增白皮书蒸馏知识层（9 章 + cheatsheet + glossary + patterns）。
  • 2.0.0 新增 CATALOG.md 文档索引、快速导航、代码示例、文档分类。

维护：每次 Server 或插件升级时核对 rn/ 与相关接口页，再更新能力卡及代码骨架。