DaZuiZui commented on issue #18846:
URL: https://github.com/apache/iotdb/issues/18846#issuecomment-6142744199

   # 校正版功能定义:Table Model `PreparedStatement` 的结果列映射
   
   > 本文取代我在本 issue 上先前那条定义。那一版有两处把组件含义写错、类型清单混了两层,均已标注 **⚠ 
已修正**;它还把一个索引要求和一个交付不了该要求的修复绑在了一起——见 §4。
   > 本 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-176`),后者把 
`tableModel` 硬编码为 `false`,并把映射替换为 `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(),
   resp.getColumnIndex2TsBlockColumnIndexList()
   ```
   
   `charset` 已在作用域内——继承自 `IoTDBStatement`,并由本类自己的构造器赋值(`:92-94`)——调用形态与 
`IoTDBStatement.java:557-558` 一致。
   
   ### 修正:关于索引 / 空位的要求
   
   我先前那版要求"越界或落到空位应抛 `SQLException`,而不是 `ArrayIndexOutOfBoundsException`",同时又声称 
`IoTDBRpcDataSet` 无需改动。这两句不可能同时成立,且上面的修复**并不**交付前一句。现状是:
   
   - `getTsBlockColumnIndexForColumnIndex`(`IoTDBRpcDataSet.java:641-643`)是裸的 
`columnIndex2TsBlockColumnIndexList.get(columnIndex - 1)`——对 `columnIndex` 
没有任何边界检查。
   - JDBC getter 只 catch `StatementExecutionException`(如 
`IoTDBJDBCResultSet.java:537-543`),因此越界序号会以 `IndexOutOfBoundsException` 
冒出,未知列名以 `IllegalArgumentException` 冒出(`:633-637`),而 `findColumn` 遇到未知列名会 
NPE(`:617-619`)。
   - 正确的写法就在隔壁一个方法里:`findColumnNameByIndex`(`:621-629`)校验 `<= 0` 与 `> 
columnNameList.size()`,并抛携带 `COLUMN_INDEX_SHOULD_START_FROM_1` / 
`COLUMN_INDEX_OUT_OF_RANGE` 的 `StatementExecutionException`。
   
   因此这部分应当作**独立决策项**,我更希望由 maintainer 明确拍板,而不是被悄悄塞进本次修复:
   
   - **(a)** 本次只做构造器替换,并从中删去 `SQLException` 那条要求;或
   - **(b)** 额外给 `getTsBlockColumnIndexForColumnIndex` / 
`getTsBlockColumnIndexForColumnName` 补上同样的边界检查,并在 JDBC 层做异常转换——这对既有调用方属于行为变更。
   
   ## 5. 验收
   
   1. §3 三行取值全部正确,且与同一响应的 `Statement` 路径一致;
   2. 不再出现 `ArrayIndexOutOfBoundsException`;
   3. 每个用例同时断言 `getXxx(int)`、`getXxx(String)` **与实际取值**——只断言元数据不算通过,元数据本身就是错的;
   4. 覆盖重排列与重复投影/别名两类;
   5. 
测试载体:`iotdb-client/jdbc/src/test/java/org/apache/iotdb/jdbc/IoTDBTablePreparedStatementTest.java`
 承接 mock RPC 的单元用例,另加 
`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]

Reply via email to