feat: add DolphinDB v2.x + v3.x adapters (MTW writes + native query API)

[JackieTien97]

Summary

• 新增 dolphindb-3.0 和 dolphindb-2.0 两个 Maven 模块，适配 DolphinDB v2.x / v3.x 作为 iot-benchmark 测试目标
• 写入采用 DolphinDB 官方推荐的 MultithreadedTableWriter（每 client 线程一个 MTW 实例，threadCount=1，保持与其它适配器一致的并发语义）；查询使用 原生 DBConnection API（dolphindb-javaapi 未注册 JDBC SPI）
• 单宽表 device_data，DFS 复合分区：一级 RANGE(ts) 按 7 天、二级 HASH([SYMBOL, 1000]) on deviceId，对齐 DolphinDB 官方 IoT 示例
• 11 种 SensorType 全覆盖（BOOLEAN/INT32/INT64/FLOAT/DOUBLE/TEXT/STRING/BLOB/TIMESTAMP/DATE/OBJECT）；core 加 DolphinDB 例外允许非 IoTDB 数据库使用 STRING/BLOB/TIMESTAMP/DATE/OBJECT
• 两个模块代码完全同构（Java API 在 v2/v3 之间无破坏性变更），仅 pom 依赖版本不同：
  • dolphindb-3.0 → com.dolphindb:dolphindb-javaapi:3.00.0.2
  • dolphindb-2.0 → com.dolphindb:dolphindb-javaapi:2.00.11.1

Key changes

范畴	内容
core 集成	DBType / DBVersion (DolphinDB_2 / DolphinDB_3) / DBSwitch (DB_DOLPHINDB_2 / DB_DOLPHINDB_3) / Constants / Config / ConfigDescriptor / config.properties / DBFactory
新增配置	DOLPHINDB_PARTITION_DAYS=7、DOLPHINDB_DEVICE_HASH_BUCKETS=1000
新增模块	dolphindb-3.0/、dolphindb-2.0/（各含 pom + assembly + log4j + DolphinDB.java + 单元测试）
文档	README × 2、DifferentTestDatabase × 2、OperationSupportMatrix × 2
设计/计划	docs/superpowers/specs/2026-05-28-dolphindb-support-design.md、docs/superpowers/plans/2026-05-28-dolphindb-support.md

Test plan

• mvn test -pl core,dolphindb-3.0,dolphindb-2.0 通过（含两个模块的 DolphinDBTypeMapTest，各覆盖 11 个 SensorType）
• mvn spotless:check 通过
• DolphinDB v3.x 本地 Docker（dolphindb/dolphindb:v3.00.5）端到端跑通：
  • Smoke test（OPERATION_PROPORTION=1:0:...）：INGESTION okOperation=1000、failOperation=0、~131K point/s；DolphinDB 侧 count(*)=100000、distinct deviceId=10
  • Mixed test（OPERATION_PROPORTION=1:1:...:1，LOOP=500）：13 个操作（Write + Q1–Q12）全部 okOperation>0 且 failOperation=0
• DolphinDB v2.x 本地 Docker（dolphindb/dolphindb:v2.00.18）端到端跑通：
  • Smoke test：INGESTION okOperation=1000、failOperation=0、~147K point/s；DolphinDB 侧 count(*)=100000、distinct deviceId=10
  • Mixed test：13 个操作全部 okOperation>0 且 failOperation=0，零代码改动（v2 vs v3 Java API 表面无差异）

Follow-ups（不阻塞本 PR）

• awaitDrain() 增加超时上限（DolphinDB 假死时避免无限阻塞）
• convertValue DATE 路径加显式 LocalDate 强制路径

🤖 Generated with Claude Code

[JackieTien97]

Review：DolphinDB 适配器（对照 iotdb-2.0 表模型）

整体接入质量不错。先说确认没问题的部分：core 接入（DBType / DBVersion / DBSwitch / Constants / DBFactory / 三个 enum）逐一核对全部正确——DOLPHINDB2_CLASS / DOLPHINDB3_CLASS 的全限定类名与实际 dolphindb2.DolphinDB / dolphindb3.DolphinDB 精确匹配，DBFactory 的 DB_DOLPHINDB_2/3 → DOLPHINDB2/3_CLASS 映射无误，没有 ClassNotFound 风险。ConfigDescriptor 里三处被“放宽”的校验（DEVICE_NUM_PER_WRITE、TABLE/TREE 两个 insert-mode 守卫）都是白名单式新增或收敛到 IoTDB，对 Influx/Timescale 等其它库无副作用；数据类型例外（STRING/BLOB/TIMESTAMP/DATE/OBJECT）也是严格三库白名单，不削弱其它库校验。DDL（per-group DFS、TSDB 引擎、复合分区、sortColumns、keepDuplicates=LAST、atomic='CHUNK'）方向正确。dolphindb-2.0 与 dolphindb-3.0 的 DolphinDB.java 逐字节相同（仅 package 行不同），符合“Java API v2/v3 无破坏性变更”的说明。

下面按严重程度排序，重点是查询语义 / 写入计数是否对齐 iotdb-2.0 表模型。所有“iotdb-2.0 表模型行为”均已核对到具体行号。

阻塞级（逻辑错误，直接影响结果正确性 / 可比性）

1. 查询点数口径错误（executeQueryAndCount L733）：用了 rows * QUERY_SENSOR_NUM * QUERY_DEVICE_NUM，而 iotdb-2.0 表模型是 rows * QUERY_SENSOR_NUM（SessionStrategy L367-368，不乘 QUERY_DEVICE_NUM）。非聚合查询会多计 QUERY_DEVICE_NUM 倍。
2. latestPointQuery 语义错误（L506-519）：全局 last() 单行 vs 参考的 last_by(...) + GROUP BY device_id 每设备一行。
3. 聚合查询缺 GROUP BY deviceId（aggRange/aggValue/aggRangeValue，L394-473）：DolphinDB 塌缩成单行 vs 参考每设备一行。
4. groupByQuery 丢设备维度（L476-503）：只 GROUP BY bar(time,g) vs 参考 group by device_id, date_bin(...)，且未投影桶列。
5. setOpQuery 子查询丢时间/设备列（L612-638）：集合运算只按值列去重，行标识错误。

健壮性 / 设计

6. 值过滤未按类型处理（L364-392 等）：对所有 sensor 拼 > <double>，参考对 DATE 列 CAST(... AS DATE)、阈值转 int。
7. awaitDrain 无超时（L316-323）：服务端 hang 会永久阻塞写线程（PR 已列为 follow-up，建议本 PR 直接修）。
8. MTW 13 个 positional 参数可读性差（L647-664）；threadCount=1+每 batch awaitDrain 的同步写取舍建议在注释写明。

次要 / 确认项

9. 分区右边界按理想时间跨度估算（L196），建议确认乱序写入不越界。
10. 配置项 rename IoTDB_TABLE_TIME_COLUMN → TABLE_TIME_COLUMN：对老 IoTDB 用户是静默失效的兼容性破坏（老 key 不再被读取，回落默认 time，无报错），建议在 release note / 迁移说明里提示。TableStrategy.java 的 38 行改动经核对是纯机械 rename，对现有 IoTDB 表模型用户行为不变。

关于“写入方式是否最优”：用 MTW（官方推荐）+ native DBConnection 查询（javaapi 未注册 JDBC SPI）方向正确；主要欠缺是 threadCount=1 退化成同步写（取舍可接受但建议注释说明）和 awaitDrain 无超时。

核心结论：接入框架没问题，问题集中在 1-5 的查询语义 / 计数口径——这些会让 DolphinDB 的查询结果和吞吐与 IoTDB 表模型不可比，建议对齐后再合入。（注：因我是本 PR 作者，GitHub 不允许对自己的 PR 提交 “Request changes”，故以 Comment 形式提交，请把上述 1-5 视为需要修改项。）

[JackieTien97]

逻辑错误（最重要）：结果点数口径与 iotdb-2.0 表模型不一致，会让吞吐统计失真。

iotdb-2.0 表模型的口径（SessionStrategy.executeQueryAndGetStatusImpl L365-368）是：

long resultPointNum = line.get();              // line = 实际遍历到的结果行数
if (config.getIoTDB_DIALECT_MODE().equals(SQLDialect.TABLE)) {
  resultPointNum *= config.getQUERY_SENSOR_NUM();   // 只乘 sensor 数
}

即 实际结果行数 * QUERY_SENSOR_NUM，对所有 query 统一处理，不乘 QUERY_DEVICE_NUM（因为表模型里设备维度由结果行/GROUP BY device_id 承载，行里已经包含设备）。

这里 DolphinDB 用的是 rows * QUERY_SENSOR_NUM * QUERY_DEVICE_NUM，多了一个 QUERY_DEVICE_NUM 因子。对 precise / range / valueRange / 两个 OrderByDesc / setOp 这些非聚合查询，result.rows() 已经包含所有设备的行（deviceId IN (...)），再乘 QUERY_DEVICE_NUM 就是把设备数算了两遍——相对参考实现多计 QUERY_DEVICE_NUM 倍。

默认配置 QUERY_DEVICE_NUM=1 时数值上看不出来；一旦 QUERY_DEVICE_NUM>1（多设备查询）points/s 会被整体放大，和 IoTDB 不可比。

建议对齐为 points = rows * config.getQUERY_SENSOR_NUM()，去掉 QUERY_DEVICE_NUM。

[JackieTien97]

逻辑错误：latestPointQuery 与 iotdb-2.0 表模型语义不一致。

iotdb-2.0 表模型（TableStrategy.getLatestPointQuerySql L341-356 + addGroupByClauseIfNecessary L335-337）是 per-device 最新：

SELECT device_id, last(time), last_by(s_0, time), last_by(s_1, time), ...
FROM <tbl> WHERE (device_id = 'd_0' OR ...) GROUP BY device_id

即用 last_by(sensor, time) + GROUP BY device_id，每个设备给出各自最新一行。

这里 DolphinDB 是：

SELECT last(s_0), last(s_1), ... FROM <tbl> WHERE deviceId IN ('d_0', ...)

last() 作用在整个多设备结果集上、且没有 GROUP BY deviceId，返回的是跨所有设备的单个全局最新值，只有 1 行。这既不是“每设备最新”语义，也会和上面的点数 bug 叠加放大误差。

建议对齐 last_by(...) ... context by deviceId（DolphinDB 的 per-partition 最新可用 context by deviceId 配合 last/last_by），返回每设备一行。两边都不带时间谓词，这点一致。

[JackieTien97]

逻辑错误：聚合查询缺少 GROUP BY deviceId，与 iotdb-2.0 表模型“每设备一行聚合”不一致。

iotdb-2.0 表模型（TableStrategy.getAggQuerySqlHead L206-223 + addAggWhereClause L331）对 aggRange / aggValue / aggRangeValue 都是：

SELECT device_id, <agg>(s_0), <agg>(s_1), ... FROM <tbl> WHERE ... AND (device_id...) GROUP BY device_id

→ 投影 device_id 并 GROUP BY device_id，返回 N_device 行（每设备一行聚合）。

这里 DolphinDB 三个聚合查询都是 SELECT agg(s_i) ... AND deviceId IN (...)，没有 GROUP BY，会把所有被选设备聚合成单行。这导致：返回行数（1 vs N_device）、聚合工作量、以及最终点数都与参考不一致（点数 bug 见上）。

建议这三个聚合查询补 GROUP BY deviceId，并在 SELECT 投影 deviceId，对齐 TableStrategy。

[JackieTien97]

逻辑错误：groupByQuery 只按时间桶分组，丢了设备维度，且未投影桶列。

iotdb-2.0 表模型（TableStrategy.getGroupByQuerySQL L234-262）是按 设备 + 时间桶 双维分组，并投影两者：

SELECT device_id, date_bin(<g>ms, time), <agg>(s_0), ...
FROM <tbl> WHERE time>=.. AND time<=.. AND (device_id...)
group by device_id, date_bin(<g>ms, time)

这里 DolphinDB 是 ... GROUP BY bar(time, g l)：只按时间桶分组（无 deviceId），且 SELECT 里没有桶列。结果是跨设备塌缩、且无法和时间桶对齐。

建议对齐为 GROUP BY deviceId, bar(time, g) 并把 deviceId, bar(...) AS bucket 投影出来（下方 groupByQueryOrderByDesc 已经用了 bar(...) AS bucket，可统一）。

[JackieTien97]

逻辑错误：setOpQuery 子查询只投影 sensor 值列、且没有把设备维度纳入投影，集合运算行标识不正确。

iotdb-2.0 表模型每个子查询是 getSimpleQuerySqlHead + range where（含 time + device 过滤），但投影也是 sensor 列；DolphinDB 这里子查询同样只投影 sensorColumns(...)，没有 timeColumn、没有 deviceId。

UNION/INTERSECT/EXCEPT 会基于“仅值列”的元组去重/求交：不同时间戳、不同设备但读数恰好相同的行会被错误合并，得到的集合不是“按时间范围内的行做集合运算”。

建议子查询至少投影 timeColumn（通常还应包含 deviceId）以保持行标识，对齐参考实现。

[JackieTien97]

健壮性（liveness）：awaitDrain 无超时上限，DolphinDB 卡住时会永久阻塞写线程。

while (true) {
  MultithreadedTableWriter.Status st = mtw.getStatus();
  if (st.unsentRows == 0) return;
  if (st.hasError()) return;
  Thread.sleep(1);
}

若后台发送线程卡住但既不报错、unsentRows 也不归零（服务端 hang / 连接断开），该循环会一直转，挂死整个 data client 线程；Thread.sleep(1) 也偏紧；返回 void，调用方无法区分“drain 完”还是“出错/超时”。

PR 描述已把此项列为 follow-up——建议本 PR 直接加 deadline（如复用写超时配置）并返回 boolean，避免合入留坑。

[JackieTien97]

可维护性（建议）：MTW 13 个 positional 参数建议加名字注释；threadCount=1 的取舍点明利弊。

new MultithreadedTableWriter(host, port, user, pwd, dbPath, tableName, false, false, null, batchSize, 0.01f, 1, timeColumn, null, Mode.M_Append, null) 这一长串位置参数可读性较差，建议为关键位加注释（batchSize / throttle=0.01f / threadCount=1 / partitionCol=timeColumn / mode）。

另外 threadCount=1 + 每个 batch 末尾 awaitDrain 同步 flush，等于把 MTW 当“带缓冲的同步写”用——若是有意对齐其它 adapter 的并发语义（每 client 一个 writer），建议在类注释里写明，避免被误认为漏配；这也确实放弃了 MTW 多线程管道的吞吐优势，属设计取舍。

[JackieTien97]

确认项（分区右边界）：endMs 用 LOOP*BATCH_SIZE_PER_WRITE*POINT_STEP 估算 +1 天。

该估算假设数据时间跨度 = LOOP * BATCH_SIZE_PER_WRITE * POINT_STEP。在乱序写入（IS_OUT_OF_ORDER/OUT_OF_ORDER_RATIO）或 DEVICE_NUM_PER_WRITE>1 改变时间推进方式时，真实最大时间戳可能超出估算，落在 VALUE 分区范围外会写失败。+1 天右边距能吸收一部分，建议确认乱序场景下边界安全（或对越界给出明确报错）。

[JackieTien97]

同 dolphindb-3.0：点数口径 rows * QUERY_SENSOR_NUM * QUERY_DEVICE_NUM 多了 QUERY_DEVICE_NUM 因子；iotdb-2.0 表模型是 rows * QUERY_SENSOR_NUM。 两模块代码逐字节相同，请一并修改。

[JackieTien97]

同 dolphindb-3.0：latestPointQuery 用全局 last() 而非 per-device last_by + GROUP BY device_id，会塌缩成 1 行。 两模块代码逐字节相同，请一并修改。