DolphinDB插件开发教程

What this page covers

• DolphinDB 插件支持概述与教程覆盖场景。
• 插件开发基础：函数类型、变量创建、异常处理、调用内置函数。
• 时间序列处理插件函数示例（msum）实现要点。
• 分布式 SQL 聚合函数与向量存储访问方式。
• 基于 mr/imr 的分布式算法插件示例（列均值）。
• 流订阅处理（handler）插件示例与可选日志。
• 外部数据源插件：数据源、schema、IO 与二进制平面文件示例。

技能认证特训营第二期正式开启（限时报名）

页面顶部包含一段限时报名相关的推广式行动号召内容。

• 该段落属于页面顶部的推广信息。
• 该推广信息以限时报名为核心表述。

DolphinDB插件开发教程

该部分给出文章标题，以及作者与发布日期等元信息。

• 作者信息在文中明确给出。
• 发布日期在文中明确给出。
• 文章主题为 DolphinDB 插件开发教程。

教程概述与覆盖的插件开发场景

该部分介绍 DolphinDB 的插件支持方式，并列出教程覆盖的插件开发应用场景。

• DolphinDB 支持动态加载外部插件以扩展功能。
• 插件以 C++ 实现。
• 插件编译产物为共享库文件（.so 或 .dll）。
• 教程覆盖时间序列数据处理相关插件函数开发。
• 教程覆盖分布式 SQL 聚合函数开发。

1. 如何开发插件

该部分讲解插件开发的基础概念与步骤，包括函数类型、变量创建与管理、异常处理，以及在插件中调用内置函数的方法。

• 插件函数可以从脚本中调用。
• Operator function 最多接受 2 个参数。
• System function 可接受任意数量参数，并支持会话访问操作。
• ConstantSP 是带引用计数的智能指针封装，引用计数为 0 时自动释放。
• 插件异常处理可使用 C++ 的 throw/try；异常类型在 Exceptions.h 中声明。

2. 如何开发支持时间序列数据处理的插件函数

该部分通过 msum 示例展示时间序列窗口计算的实现方式，强调向量缓冲访问与 NULL 处理等要点。

• msum 的签名为 ConstantSP msum(const ConstantSP &X, const ConstantSP &window)。
• msum 接收向量与窗口大小，并返回与输入等长的向量。
• 批量读取到缓冲区通常比逐元素 getDouble/getInt 更高效。
• DT_DOUBLE 的 NULL 使用宏 DBL_NMIN 表示，需要单独判断。
• 返回的前 windowSize-1 个元素为 NULL。

3. 如何开发用于处理分布式SQL的聚合函数

该部分介绍分布式 SQL 聚合函数插件的实现思路，包括向量存储模式差异、访问方式选择，以及通过脚本与 MapReduce 风格方式组织分布式版本。

• 分布式 SQL 聚合函数通常接收一个或多个向量，最终返回标量。
• DolphinDB 向量有 regular array 与 big array 两种存储模式。
• isFastMode 可用于区分 regular array 与 big array。
• 系统通常会同时实现分布式与非分布式版本，并选择更高效的版本调用。
• 远程节点存在数据时，插件需要在各远程节点加载。

3.3 随机访问大数组

该部分说明如何对 big array 使用位运算计算段偏移与段内偏移，从而实现随机访问。

• 随机访问 big array 需要计算 segment offset。
• 随机访问 big array 需要计算 in-segment offset。
• 该计算可通过 getSegmentSizeInBit 与位运算实现。
• 示例包含 index >> bits 与 index & mask 的用法。

3.4 应该选择哪种方式访问向量

该部分给出向量访问方式选择建议：缓冲式访问更通用；当存储模式与类型明确时可在特定场景使用直接底层访问。

• 缓冲式访问（get*Const/get*Buffer）更通用。
• 缓冲式访问通常是更推荐的默认选择。
• 直接访问（getDataArray/getDataSegment）适用于特定场景。
• 直接访问依赖对存储模式与数据类型的已知前提。

4. 如何开发支持新的分布式算法的插件函数

该部分展示如何用 C++ 编写 map/reduce/final 等自定义函数，并调用 DolphinDB 的 mr/imr 来实现分布式算法（列平均值示例）。

• Map-Reduce 是通用框架，DolphinDB 提供 mr 与 imr。
• 示例目标是计算分布式表中指定列的平均值。
• columnAvgMap 对分区数据求和并统计非空数量，返回 [sum, count] 元组。
• mr 的 map 函数仅允许一个参数；需要更多参数时可用偏函数应用。
• 数据位于远程节点时，需要在各数据节点加载插件。

5. 如何开发支持流数据处理的插件函数

该部分给出流订阅处理函数（handler）插件示例：从订阅消息中按索引提取字段并写入表，并说明 append 接口与可选错误日志配置。

• 订阅者通过 handler 函数处理接收的数据。
• 订阅消息可为 table 或 tuple，取决于 subscribeTable 的 msgAsTable 参数。
• 示例 handler 接收 msg(tuple) 与 indices，并将字段插入到 table。
• append 接口返回成功与否，并输出 insertedRows 或 errMsg。
• 如需记录 append 失败日志，可包含 Logger.h 并以 -DLOGGING_LEVEL_2 编译。

6. 如何开发支持外部数据源的插件函数

该部分讨论外部数据源插件的关键问题（数据源、schema、IO），并以二进制平面文件为例，覆盖 schema 提取、数据加载、分批导入与数据源生成等内容。

• 数据源是一种包含元数据的特殊数据对象，执行后得到表/矩阵/向量等数据实体。
• schema 描述列数、列名与数据类型，并建议提供快速获取 schema 的接口。
• DataInputStream 与 DataOutputStream 可抽象压缩、字节序与多种 IO 类型。
• 示例二进制格式每行 4 列，总计 32 字节/行。
• loadMyDataEx 示例用于避免超大文件全量载入内存的瓶颈。

Facts Index