DolphinDB CTP 行情插件最佳实践指南

What this page covers

• 背景与适用范围：CTP 介绍、插件能力、环境要求与兼容警告。
• 安装插件：登录、查看插件版本、安装与返回路径说明。
• 加载插件：loadPlugin、重复加载处理与重启说明。
• 从订阅到标准化处理，再到分布式数据库落盘的整体流程。
• 节点启动时自动订阅部署：startup.dos 与 startup 参数。
• FAQ：合约代码获取、字段处理与去重、定时任务与预加载插件。

技能认证特训营第二期报名提示

页面顶部包含活动报名入口与福利优惠提示。

• 该区域用于引导读者进行活动报名。
• 该区域包含福利或优惠相关提示信息。

DolphinDB CTP 行情插件最佳实践指南（标题与作者日期）

文章展示标题，并提供作者署名与发布日期信息。

• 文章包含发布日期信息。
• 文章包含作者署名信息。

背景与适用范围（CTP 介绍、插件能力、环境要求与兼容警告）

介绍 CTP 系统、DolphinDB CTP 行情插件能力、推荐 SDK 版本、文章目标与运行环境限制，并提示 CTP/CTPMini 不兼容风险。

• CTP 是上海期货信息技术有限公司为期货公司开发的期货经纪业务管理系统。
• DolphinDB CTP 行情插件可订阅期货市场实时行情并查询商品信息数据。
• 插件基于上期所官方提供的 CTP C++ API 实现。
• 推荐使用的 CTP C++ API 版本为 v6.6.8 或 v6.6.9。
• 运行环境要求 DolphinDB server 与插件版本不低于 2.00.11。
• 当前仅支持 Linux 系统。
• 支持 CTP 与 CTPMini 两种 SDK 类型。
• CTP 与 CTPMini 的 API 与后台系统不互相兼容，错误匹配可能导致 crash。

基本使用介绍

说明节点启动后通过 DolphinDB 客户端连接并执行示例代码的基本方式。

• 可使用 GUI 客户端连接节点执行示例代码。
• 可使用 VS Code 客户端连接节点执行示例代码。
• 可使用 Web UI 客户端连接节点执行示例代码。

安装插件（登录、查看插件版本、安装）

给出安装前登录、查询远程插件版本信息以及安装 ctp 插件的步骤与返回路径说明。

• 安装插件前需要登录有创建权限的账号（示例为 admin/123456）。
• 可用 listRemotePlugins 查看当前 DolphinDB 支持的插件版本信息。
• listRemotePlugins("ctp") 返回插件名与版本信息两列。
• installPlugin("ctp") 会下载与当前 server 版本适配的插件文件。
• installPlugin("ctp") 的返回值为插件描述文件 PluginCtp.txt 的安装路径。
• installPlugin 会从远程文件服务器拉取插件文件，可能需要一定时间。

加载插件（loadPlugin、重复加载处理、重启说明）

说明如何加载 ctp 插件、首次加载返回内容、重复加载报错及 try-catch 处理方式，并提示重启后需重新加载。

• 在脚本中调用插件接口前，需要先 loadPlugin 加载插件。
• loadPlugin 可使用插件名或相对/绝对路径加载。
• 首次 loadPlugin 成功后，会返回该插件提供的函数列表（示例说明）。
• 重复 loadPlugin 会报错：The module [ctp] is already in use.
• 可使用 try-catch 捕获重复加载错误，避免中断后续脚本执行。
• 节点重启后需要重新加载插件。

通过 CTP 行情插件将实时行情数据写入分布式数据库（总览与流程）

以多个交易所期货期权行情为例，给出从订阅到流表、标准化处理到落盘分布式数据库的整体流程与关键注意事项。

• 示例覆盖多个交易所的期货期权交易数据订阅与入库场景。
• 订阅实时交易数据并写入 ctpMarketDataStream 持久化流表。
• 对数据进行标准化处理并写入 ctpMarketStream 持久化流表。
• 订阅 ctpMarketStream 并将数据写入分布式数据库落盘。
• 避免 CTP 插件连接到 CTPMini 后台（或反向）以降低不兼容风险。

参数配置（连接配置、流表与入库配置）

给出 CTP 连接参数、订阅合约列表来源、流表容量与表名、目标库表名等配置，并解释关键配置项含义。

• 连接参数 ip 为 STRING 标量或向量，表示行情服务器 IP。
• 连接参数 port 为 INT 标量或向量；向量长度需与 ip 一致。
• 连接参数 config 为字典：key 为 STRING，value 为 BOOL。
• config.ConcatTime=true 会生成 tradeTime 字段（TIME）。
• config.ReceivedTime=true 会生成 receivedTime 字段（NANOTIMESTAMP）。
• marketTBCapacity 表示流数据表内存最多保留行数（示例为 2000000）。
• 原始行情持久化流表示例名称为 ctpMarketDataStream。
• 标准化行情持久化流表示例名称为 ctpMarketStream。
• 分布式数据库示例为 dfs://ctp_market_data，目标表示例为 ctp_market。

清理环境（可选）

提供取消订阅与删除流表的脚本以便示例可重复执行。

• 清理脚本使用 ops 库。
• 对流表执行 unsubscribeAll 取消订阅。
• 对流表执行 dropStreamTable(force=true) 进行删除。

建立 CTP 连接

使用 ctp::connect 连接行情服务器并返回句柄。

• ctp::connect 用于创建与 CTP 行情服务器的连接。
• ctp::connect 返回连接句柄。
• 示例形式为 conn = ctp::connect(ip, port, config)。

创建库表（原始流表、分布式库表、标准化流表）

创建并持久化共享流表、建立分布式数据库与分区表结构，以及创建与分布式表结构一致的标准化持久化流表并可选设置过滤列。

• 可用 ctp::getSchema 获取原始行情表结构并创建持久化流表。
• 使用 enableTableShareAndPersistence 前需在配置中指定 persistenceDir。
• cacheSize 可用于控制建表时预分配内存大小及流表内存最大行数。
• 示例创建分布式库 dfs://ctp_market_data，并设置 engine='TSDB' 与 atomic='CHUNK'。
• 示例分布式表 ctp_market 设置 sortColumns 与 keepDuplicates=ALL。
• 五档量价字段可存为 ArrayVector（DOUBLE[] 与 LONG[]）。
• 标准化持久化流表可与分布式表 schema 保持一致并持久化共享。
• 可选设置 setStreamTableFilterColumn(unified_code) 作为过滤列。

订阅流数据表并写入分布式数据库（subscribeTable、handler 标准化函数）

先订阅原始行情流表做预处理写入标准化流表，再订阅标准化流表实时写入分布式数据库，并解释 batchSize、throttle、handler 等参数及标准化示例。

• 可订阅 ctpMarketDataStream 并将处理结果写入 ctpMarketStream。
• 可订阅 ctpMarketStream 并写入分布式表 ctp_market。
• 写库流程可使用 loadTable 作为 handler。
• subscribeTable 的 handler 为必选参数。
• batchSize 为正数时，未处理消息数达到阈值才处理。
• throttle 单位秒，默认 1；在 batchSize 未达时按时间触发处理。
• 满足 batchSize 或 throttle 任一条件即可触发一次写库。
• fixedLengthArrayVector 可将 Bid/Ask 的 1-5 档字段合并为数组列。

订阅 CTP 行情并写入流数据表

调用 ctp::subscribe 订阅合约范围，行情数据写入指定流表。

• ctp::subscribe 用于订阅指定范围的合约行情数据。
• 订阅后的行情数据会进入流数据表。
• 示例形式为 ctp::subscribe(conn, ctpSubType, objByName(ctpSubTBName), ids)。

查询行情接收情况（ctp::getStatus）

使用 ctp::getStatus 查询接收状态并解释关键字段含义。

• ctp::getStatus 用于查询 CTP 行情接收情况。
• 盘中启动时 firstMsgTime 与 lastMsgTime 不为空（说明性描述）。
• lastMsgTime 表示收到最后一条数据的系统时刻（说明性描述）。
• processedMsgCount 表示已处理的数据量（说明性描述）。

节点启动时自动订阅部署（startup.dos 与 startup 参数）

展示 DolphinDB 启动流程，并说明通过配置 startup 参数执行 startup.dos 以实现节点启动时自动订阅部署及注意事项。

• 流程图展示节点从初始化到执行脚本与启动服务的顺序（图示说明）。
• 配置 startup 参数后才会执行 startup.dos。
• 单节点在 dolphindb.cfg 配置 startup；集群在 cluster.cfg 配置。
• startup 可配置绝对或相对路径；相对路径有搜索顺序说明。
• startup 参数示例为 startup=/DolphinDB/server/startup.dos。
• 将业务代码加入 startup.dos 并设置 startup 参数，可实现节点启动时自动订阅部署。
• CTP 账户信息需要根据实际环境修改。

常见问题解答（FAQ）

回答合约代码获取、原始行情字段处理与去重、以及定时任务设置与启动时预加载插件等问题。

• 可用 ctp::queryInstrument 或 ctpMini::queryInstrument 查询合约代码信息表并提取 ids。
• queryInstrument 需要有效的 CTP 交易端账号；行情端账号无法获取结果。
• 可通过读取 CSV 或查询分布式静态表构建合约信息表作为替代方案。
• 原始行情数据中的 ExchangeID 字段为全空值（问题描述）。
• 可依赖静态信息表，用 InstrumentID 与 trade_code 关联补全 exchange 信息。
• trade_date 表示交易日期；夜盘与日盘可归为同一 trade_date（定义说明）。
• action_date 表示实际日期，即数据生成的真实日期（定义说明）。
• 不同交易所对 ActionDay 与 TradingDay 的规则不一致，需要用户自行处理。
• temporalAdd 可按交易日历进行日期加减计算（示例说明）。
• CTP 服务器可能在每天早上 6-8 点重复发送前一天夜盘行情（现象描述）。
• 可用 tradeTime 与 receivedTime 作为过滤条件进行重复数据过滤（示例说明）。
• 启用 tradeTime 与 receivedTime 字段需在连接时设置 ConcatTime=true 与 ReceivedTime=true。
• 可使用 scheduleJob 定时连接与关闭 CTP 以避免收盘后接收测试数据。
• 定时任务初始化会用到 CTP 插件函数，因此需要启动时自动加载 CTP 插件。
• 可配置 preloadModules=plugins::ctp 让节点启动时自动加载插件。

附录（参考文档与脚本资源）

提供启动脚本与自动订阅教程链接，并给出相关脚本与 CSV 资源入口。

• 启动脚本教程链接：https://docs.dolphindb.cn/zh/tutorials/Startup.html
• 节点启动时流计算自动订阅教程链接：https://docs.dolphindb.cn/zh/tutorials/streaming_auto_sub.html
• 资源链接（future_basic.csv）：https://docs.dolphindb.cn/zh/plugins/script/ctp_best_practice/future_basic.csv

Facts Index