DaZuiZui commented on issue #18846:
URL: https://github.com/apache/iotdb/issues/18846#issuecomment-6160207116
# 校正版功能定义:Table Model `PreparedStatement` 的结果列映射
> 本 issue 不新增 SQL 文法,也不改变解析规则;下面定义的是既有语法在 JDBC 客户端上的**结果列映射语义**,即修复后满足的行为契约。
## 1. 语法定义(受影响的语法面)
映射语义作用于所有带 `?` 占位符的 Table Model 查询,尤其是下面三类典型形态:
```sql
-- (a) 投影顺序与物化顺序不一致
SELECT b, a FROM t WHERE a > ?;
-- (b) 重复投影 / 别名共享同一物理列
SELECT a AS x, a AS y FROM t WHERE a > ?;
-- (c) 参数出现在 WHERE 中,投影含时间列
SELECT time, s1 FROM metrics WHERE device = ? AND s1 > ?;
```
要点:
- 投影列表的顺序决定**逻辑结果列序**,它与服务端 TsBlock 的**物理列序**可以不同;
- 两者的对应关系只由服务端下发的映射决定,客户端直接采用,不自行推导;
- 同一物理列可以被多个逻辑列引用((b) 即此情形),因此服务端可能下发**重复项**。
## 2. 功能描述
### 2.1 组件及其含义
| 组件 | 来源 | 含义 |
| --- | --- | --- |
| `columns` | `resp.getColumns()` | 逻辑结果列名;其顺序即结果集列序 |
| `columnIndex2TsBlockColumnIndexList` | `resp` | **权威映射**:逻辑列序号 → 物理
TsBlock 列序号 |
| `columnNameIndexMap` | `resp.columnNameIndexMap` |
客户端并不消费该字段。`IoTDBRpcDataSet` 以 `columnNameIndex`
形参接收它(`IoTDBRpcDataSet.java:99`)之后全文再无引用。真正用于"列名 → 序号"的是
`columnOrdinalMap`(`:61`,注释为 *"used because the server returns deduplicated
columns"*),由 `columnNameList` 在 `:181-184` 自建,同名以首次出现为准。因此只传这个字段无法保留映射——这正是 §4
的要点 |
| `dataTypeList` | `resp.getDataTypeList()` |
类型声明是**按逻辑列、而非按物理列**给出的。它按逻辑序索引——`IoTDBRpcDataSet.java:173` 读的是
`columnTypeList.get(i)`,`i` 走的是 `columnNameList`——且 `:59` 明写不做
deduplication。其长度等于 `columns.size()`,不等于物理块宽度 |
| `tableModel` | `resp.isSetTableModel() && resp.isTableModel()` |
表模型标志。注意它当前是**收下即丢**:`IoTDBRpcDataSet.java:112` 声明该形参后既不存储也不读取。尽管如此,仍必须转发,以与
`IoTDBStatement` 路径保持一致 |
| `ignoreTimeStamp` | `resp` | 树模型下是否隐藏时间列。据
`IoTDBRpcDataSet.java:114`,*"only used for tree model, table model this field
will always be true"*——故表模型下不会前置 `-1` |
| `charset` | 连接自身 | `getBytes(...)` 系列 getter
使用的字符集(`IoTDBJDBCResultSet.java:391,412`) |
### 2.2 规则
1. **映射原样采用**:客户端直接使用服务端下发的 `columnIndex2TsBlockColumnIndexList`,不得重建为恒等映射。
2. **允许重复**:`m[i]` 可以相等;重复引用的逻辑列取值与其所指的物理列一致。
3. **物理块宽度**取 `max(m) +
1`(`IoTDBRpcDataSet.java:163-166`);客户端据此预分配列类型数组,不得按逻辑列数分配。
4. **按列序号取与按列名取共用同一份映射**,两者取值必须一致。
5. **同名逻辑列以首次出现为准**(`:181-184`)。
6. 仅当映射缺失时,才回落到既有推导规则:树模型下时间列占位 `-1` 并整体右移一位,其余情况恒等。
7. `tableModel` 取自 `resp.isSetTableModel() && resp.isTableModel()`,不得硬编码。
### 2.3 类型
`dataTypeList` 的取值取自 `TSDataType`。枚举全集为 `BOOLEAN, INT32, INT64, FLOAT,
DOUBLE, TEXT, STRING, VECTOR, UNKNOWN, TIMESTAMP, DATE, BLOB,
OBJECT`。其中两个层次必须分开:
**a. 可能作为映射值列出现的类型**——`BOOLEAN, INT32, INT64, FLOAT, DOUBLE, TEXT, STRING,
DATE, BLOB, OBJECT`。(`VECTOR` 与 `UNKNOWN` 是枚举成员,但这条路径上不会产生。)
**b. `TIMESTAMP`**——表模型下不存在时间列,故它不会作为映射值列出现;它只来自树模型的 `-1` 时间列占位。
各类型在 getter 上的行为:
- **`OBJECT`**——非字符串 getter 抛 `SQLException`,携带
`OBJECT_ERR_MSG`(`IoTDBJDBCResultSet.java:74,313,335,385,406`);`getString` 经
`BytesUtils.parseObjectByteArrayToString` 正常工作(`IoTDBRpcDataSet.java:562-564`)。
- **`DATE`**——以 `INT32` 物化;`getDate` 即 `getInt` +
`DateUtils.parseIntToLocalDate`(`:597-601`),`getString` 经
`DateUtils.formatDate` 格式化(`:568-569`)。
- **`TEXT` / `STRING`**——以 `TSFileConfig.STRING_CHARSET`
解码,不是连接字符集(`:556-561`)。
- **`BLOB`**——以 `getBinary(...).getValues()` 返回(`:565-567`)。
- **多个逻辑列共享同一物理列时**,`dataTypeForTsBlockColumn`
会按逻辑列逐次写入(`:179`),因此后出现的逻辑列会覆盖该物理列先前记录的类型。当前代码不检测、也不拒绝这种冲突。
- **索引约束**——见 §4:越界取值当前不会抛 `SQLException`。
## 3. 例子
服务端下发 `columns = ["b","a"]`、`dataTypeList =
["INT32","INT32"]`、`columnIndex2TsBlockColumnIndexList = [1,0]`,物理 TsBlock 含两个
INT32 列,值分别为 `10`、`20`:
```java
PreparedStatement ps = conn.prepareStatement("SELECT b, a FROM t WHERE a >
?");
ps.setInt(1, 0);
ResultSet rs = ps.executeQuery();
rs.next();
rs.getInt(1); // 期望 20(逻辑列 b → 物理列 1)
rs.getInt("a"); // 期望 10(逻辑列 a → 物理列 0)
```
| `columns` | 映射 | 物理列值 | 期望 `[第1列, 第2列]` | 期望按名字取 |
| --- | --- | --- | --- | --- |
| `["b","a"]` | `[1,0]` | `[10, 20]` | `[20, 10]` | `b=20, a=10` |
| `["x","y"]` | `[0,0]` | `[10]` | `[10, 10]` | `x=10, y=10`(不得抛异常) |
| `["a","b"]` | `[0,1]` | `[10, 20]` | `[10, 20]` | 恒等情形,作不回归对照 |
同一响应在**当前**代码下的表现:映射被替换为恒等映射,于是第 1 行静默返回 `[10, 20]` 而非 `[20, 10]`;第 2 行把第 2
列解析为 `list.get(1)` = `1`,随后对只有一列的块调用 `curTsBlock.getColumn(1)`,抛
`ArrayIndexOutOfBoundsException`。
**服务端可达性。** 这不是纯人造
fixture。`DatasetHeader.setTableColumnToTsBlockIndexMap`(`DatasetHeader.java:100-107`)是拿每个输出符号在**子节点**输出符号列表中的位置来建映射的,因此投影顺序与扫描顺序不同即产生非恒等映射,同一符号出现两次即产生重复项。
## 4. 当前差异与修复
`IoTDBTablePreparedStatement.processQueryResult()`(`iotdb-client/jdbc/src/main/java/org/apache/iotdb/jdbc/IoTDBTablePreparedStatement.java:215-232`)调用的是
14 参的 `IoTDBJDBCResultSet` 构造器(`IoTDBJDBCResultSet.java:139-181`),后者把
`tableModel` 硬编码为 `false`(`:173`),并把映射替换为 `IntStream.range(0,
columnNameList.size())`(`:174`)。该构造器也从不给 `this.charset` 赋值,因此该字段保持初始化值
`TSFileConfig.STRING_CHARSET`(`:86`)。普通
`IoTDBStatement`(`:541-558`)走完整构造器、三项均正确转发,所以同一响应在两条路径上结果不同。
**修复。** 在 `IoTDBTablePreparedStatement.java` 中,把 `:218-232` 处的结果集构造换成完整构造器,在
`zoneId` 之后补:
```java
charset,
resp.isSetTableModel() && resp.isTableModel(),
new ArrayList<>(resp.getColumnIndex2TsBlockColumnIndexList())
```
`charset` 已在作用域内——继承自 `IoTDBStatement`,并由本类自己的构造器赋值(`:92-94`)——调用形态与
`IoTDBStatement.java:557-558` 一致。映射以防御性拷贝传入:`IoTDBRpcDataSet` 在
`!ignoreTimeStamp` 时会原地前置 `-1`(`:167-170`),而 thrift getter 返回的是响应内部持有的
list(`TSExecuteStatementResp.java:815-817`)。
### 关于索引 / 空位的要求
本次修复完整解决该 issue,且无需就边界检查单独决策。我先前那版要求"越界或落到空位应抛 `SQLException`,而不是
`ArrayIndexOutOfBoundsException`",该要求在此删除,而非留待他人拍板。它之所以不必要,在于映射自身的不变量:
- `getTsBlockColumnIndexForColumnIndex`(`IoTDBRpcDataSet.java:641-643`)是裸的
`columnIndex2TsBlockColumnIndexList.get(columnIndex - 1)`。
- 物理块宽度为 `max(m) + 1`,而任何合法逻辑列序号 `i` 都满足 `0 <= m[i] <= width -
1`。映射被原样采用后,`curTsBlock.getColumn(m[i])` 不可能越界。
- §3 报告的 `ArrayIndexOutOfBoundsException` 是恒等映射被套用到单列块上的产物,随映射本身一并消失。
对越界序号、未知列名与
`findColumn`(`IoTDBJDBCResultSet.java:537-543,617-619,633-637`)的边界校验属于独立的健壮性改进项,不构成本次修复的前置条件;`findColumnNameByIndex`(`:621-629`)已给出该写法的范本。
14 参的 `IoTDBJDBCResultSet`
构造器(`IoTDBJDBCResultSet.java:139-181`)在本次修改后不再有调用方。
## 5. 验收
1. §3 三行取值全部正确,且与同一响应的 `Statement` 路径一致;
2. 不再出现 `ArrayIndexOutOfBoundsException`;
3. 每个用例同时断言 `getXxx(int)`、`getXxx(String)` **与实际取值**——只断言元数据不算通过,元数据本身就是错的;
4. 覆盖重排列与重复投影/别名两类;
5. 测试载体:mock RPC 的单元用例在既有
`iotdb-client/jdbc/src/test/java/org/apache/iotdb/jdbc/IoTDBTablePreparedStatementTest.java`
上补充;真实服务端用例在既有
`integration-test/src/test/java/org/apache/iotdb/relational/it/db/it/IoTDBTablePreparedStatementJDBCIT.java`
与 `IoTDBTablePreparedStatementIT.java` 上补充——后者才是证明可达性的方式。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]