ZH Mapping and Backend Limits

Home · GitHub

English | 简体中文

TsGate 2.1.0： 本页使用 com.alandevise.tsgate.*。从 2.0.0 升级时须更新 import、反射类名和包扫描配置，并重新编译。Central 2.0.0 保留 com.alandevise.tsdb.*。详见迁移步骤与发布状态。

后端能力与边界

能力	IoTDB 表模型	InfluxDB 3 Core	InfluxDB OSS 1.x	openGemini 默认引擎
POJO / 批量写入、普通读、tag/field 过滤	支持	支持	支持	支持
原生查询语言	SQL	SQL	InfluxQL	InfluxQL
时间游标 / offset 分页	支持	支持	支持；相同时间多行仍需注意游标的固有限制	支持；相同时间多行仍需注意游标的固有限制
FIELD 排序 / 严格复合游标	支持	支持	明确报 UNSUPPORTED_OPERATION	明确报 UNSUPPORTED_OPERATION
聚合 / tag 分组 / UTC 或固定偏移窗口	支持	支持	支持；窗口聚合必须显式设置起止时间	支持；窗口聚合必须显式设置起止时间
地区时区自然日 / DST	有界 CASE 自然日分桶	有界 CASE 自然日分桶	暂不支持地区日历窗口，明确报错	暂不支持地区日历窗口，明确报错
分页总数	服务端 COUNT / 子查询	服务端 COUNT / 子查询	流式扫描逻辑结果行计数，受响应字节上限保护	流式扫描逻辑结果行计数，受响应字节上限保护
原生 client Bean	ITableSessionPool	com.influxdb.v3.client.InfluxDBClient	org.influxdb.InfluxDB	兼容的 org.influxdb.InfluxDB

openGemini 一列描述 2.1.0 适配器，组合复用 InfluxDB1 兼容实现并保留统一查询边界，范围为已验证的 1.4.1/1.5.2 默认引擎部署，不覆盖 COLUMNSTORE、Arrow 或全部原生功能。准确验证范围见 OpenGemini 接入指南。

本地 OpenGemini 扩展另有 measurement 名预检、精确空表错误归一与原生健康桥接。新 measurement/tag series 的索引可能在写入确认后才对查询可见，需要读到具体数据点的业务应设置截止时间并在读侧轮询。只有精确的 measurement not found 错误会在明确指定 measurement 的结构化统一 query 中转为空行、count 中转为零；原生 executeQuery 与借用原生 client 的 DTO 保留服务端错误，包括多个 measurement 或子查询的错误。measurement 名含 ,、;、/、\，等于 . / .. 或含不可打印字符时，整个批次在 I/O 前被拒绝。兼容原生 client 的稳定代理用真实 X-Geminidb-Version 响应头处理 ping() / version()，其他原生方法照常委托。

InfluxDB 3 严格游标兼容性取决于服务端与 SQL 策略组合：tsdb.influxdb.strict-cursor-sql 默认 or，union-all 是结构化续页的显式替代方案。应使用兼容性与验证列出的准确组合，不能认为所有 3.x 均支持两种查询形态。该开关不会改写原生 SQL，也不会为 InfluxDB 1.x 增加严格游标。union-all 模式对严格游标与聚合的组合报 UNSUPPORTED_OPERATION，包括第一页。

最终 m 个游标键在 UNION 策略下最多生成 m 个互斥分支，每个分支重复业务条件与时间范围，合并后再做全局排序分页。它保留混合 ASC/DESC 排序、模板补齐的 time/tag 键及响应行数/字节保护，但可能增加服务端扫描和排序开销；这些响应上限不能限制数据库的扫描量或 CPU。两种策略均不提供跨页快照，不接受缺键/null 游标，也不提高时间戳精度。详见分页。

InfluxDB 1.x 使用 MEAN 对应统一 API 的 AVG，IN/BETWEEN 翻译为等价条件；不会将 InfluxDB 3 SQL 原样发送给 1.x。 InfluxQL 的 LIMIT/OFFSET 是每个 series 的限制，因此 tag 分组查询会先读取受限的全部分组结果，再全局排序分页； 分组结果超过 max-query-rows 或响应超过字节上限时即失败，即使请求的单页较小。普通计数采用不保留全部行的流式扫描，避免 COUNT(*) 按 field 非空值计数造成总行数错误。 InfluxDB 1.x 显式列选择需要注解实体，且至少包含一个 @TGField；仅选 tag 会明确拒绝，不返回误导性的空结果。 原始 TSDBQuery 没有实体元数据时可保留空的 selectColumns 使用 SELECT *，或改用原生 InfluxQL；窗口查询不能把聚合别名 / group tag 命名为 window_start。 InfluxDB 1.x 的物理时间列固定为 time，不支持自定义时间列；原生查询不支持返回多个语句结果，服务端返回 partial 结果时明确失败。

查询结果映射

查询结果最终映射为业务承接对象，承接类需要可访问的无参构造方法；普通 Java record 不能直接作为查询 DTO：

• 带有 TSDB 注解的字段按注解物理列名匹配，列缺失时不会回退到 Java 字段名。
• 无注解字段优先按返回列原名匹配字段名，其次支持大小写无关匹配和下划线转驼峰匹配。
• 无注解 DTO 中名为 time / timestamp 的字段，还可匹配返回的 time、Time、_time、timestamp 时间别名；带注解字段仍遵循物理列名规则。
• 返回列多于承接对象字段时会被忽略；承接对象字段找不到返回列时保留构造后的字段值。
• long/int/short/byte/BigInteger 转换要求整数精确可表示：非法文本、小数截断和越界均抛 METADATA_ERROR，不会用 0 或 null 替代错误值。
• boolean 文本仅接受忽略大小写及首尾空白的 true / false；其他文本（包括 1、yes）报错，不会静默变为 false。
• float / double 拒绝 NaN、Infinity、溢出和非零值下溢为 0；普通 IEEE 754 舍入仍存在。两个 InfluxDB adapter 与 openGemini 兼容适配器均按 BigDecimal 解析 JSON 小数，避免解析阶段先转 Double；映射到 BigDecimal 可保留响应提供的十进制数字，无法恢复数据库存储前已损失的精度。已经由其他来源读取成 Float / Double 的值只保留该二进制值，不能恢复原始精度。
• Instant 文本转换保留纳秒；long / Date 的时间语义是毫秒。源 null 映射到引用类型仍为 null，映射到 primitive 保留构造后的字段值。
• 映射异常包含字段、源类型、目标类型等上下文，底层转换异常保留为 cause。

Map 结果类型

Map.class 与 LinkedHashMap.class 返回 LinkedHashMap，保留结果列顺序；HashMap.class 返回 HashMap；TreeMap.class 返回按键排序的 TreeMap。其他 Map 接口或子类在数据库 I/O 前报 ARGUMENT_ERROR，即使查询结果为空也会校验。不反射调用任意 Map 构造器。规则适用于模板查询/结果接口，普通 POJO 映射保持原有行为。

常见限制

可移植测试源码与可复用 Docker 配置在各模块 src/test/ 中纳入版本控制。本地夹具、凭据和运行报告保留在 .local-test/ 并由 Git 忽略；共享运行器与 GitHub 工作流提供可复现检查，详见测试与发布。

• 当前只支持 IoTDB 表模型，不支持 IoTDB 树模型转换口子。
• 统一 TGTemplate 面向当前唯一启用的 adapter；允许同时引入多个依赖，但不支持同时启用多个后端或双写。
• 链式查询按后端能力表提供支持；复杂 JOIN、子查询、数据库私有函数等应使用 executeQuery(...) 或借用的原生 client，并遵循对应入口限制。
• 同一字段在同一库表中应保持稳定类型，避免 IoTDB 类型冲突或 InfluxDB field 类型混淆。

---

← 分页与原生查询 · 兼容性、验证与成熟度 →

2.1.0 中的 OpenGemini

实测 1.4.1/1.5.2 的 Influx 兼容 HTTP 写入路径会先把整数字段转换为 float64，再存储为整数。整数协议后缀也不能避免这一转换：9007199254740993i 读回为 9007199254740992。因此 OpenGemini 适配器在 I/O 前检查整个批次，只接受 signed-int64 范围内且可由 IEEE 754 float64 精确表示的整数字段。-2^53 至 2^53 之间的整数全部精确；2^53+2、Long.MIN_VALUE 等部分更大绝对值的整数也精确。2^53+1、Long.MAX_VALUE 和 Long.MIN_VALUE+1 在写前返回 ARGUMENT_ERROR、NOT_COMMITTED、零物理请求，不强制转换，也不编码成字符串。公共结构化 query/count 同样预检整数过滤字面量，包括 IN/BETWEEN 的每个值，避免服务端数值比较舍入后错误匹配。 极大整数型 BigDecimal 过滤值先与 signed-int64 边界比较再转换为整数，避免超大指数绕过检查或触发无界展开。Float/Double 及非整数查询字面量仍遵循普通浮点语义；已有 BigDecimal 字段校验继续生效。Epoch 毫秒时间戳走独立的时间路径。原生 SQL 与借用原生客户端写入绕过这些检查，保留服务端精度边界；该校验也不保证聚合累加无溢出或浮点运算精确。此限制针对本次 HTTP 适配，不代表 openGemini 的所有引擎或其他写入协议。

TsGate 2.1.0 包含独立的 OpenGemini adapter 与 starter。配置、默认引擎边界及准确版本测试见 OpenGemini 接入指南，迁移要求见 2.1.0 发布说明。