DaZuiZui commented on issue #18846:
URL: https://github.com/apache/iotdb/issues/18846#issuecomment-6141729566
# Functional definition: result column mapping for Table Model
`PreparedStatement`
> This issue adds no new grammar and changes no parsing rule. What follows
defines the **result-column-mapping semantics** of already-existing syntax on
the JDBC client — i.e. the behaviour contract the fix must satisfy.
## 1. Syntax definition (affected surface)
The mapping semantics apply to every Table Model query using `?`
placeholders, in particular the three shapes below:
```sql
-- (a) projection order differs from the materialized order
SELECT b, a FROM t WHERE a > ?;
-- (b) repeated projection / aliases sharing one physical column
SELECT a AS x, a AS y FROM t WHERE a > ?;
-- (c) parameter in WHERE, time column in the projection
SELECT time, s1 FROM metrics WHERE device = ? AND s1 > ?;
```
Key points:
- The projection list fixes the **logical result-column order**, which may
differ from the **physical column order** of the server's TsBlock.
- The correspondence between the two is determined solely by the mapping the
server sends; the client must not derive it on its own.
- One physical column may be referenced by several logical columns (case
(b)).
## 2. Functional description
### 2.1 Components and their meanings
| Component | Source | Meaning |
| --- | --- | --- |
| `columns` | `resp.getColumns()` | Logical result column names; their order
is the result-set column order |
| `columnIndex2TsBlockColumnIndexList` | `resp` | **Authoritative mapping**:
logical column index → physical TsBlock column index |
| `columnNameIndexMap` | `resp` | Column name → logical column index |
| `dataTypeList` | `resp` | Type declaration of each physical column, same
length as `columns` |
| `tableModel` | `resp` | Table-model flag; when `true` no tree-model time
column exists |
| `ignoreTimeStamp` | `resp` | Whether the time column is hidden in the tree
model |
| `charset` | the connection | Character set used to decode string fields |
### 2.2 Rules
1. **Adopt the mapping as sent.** The client uses the server-provided
`columnIndex2TsBlockColumnIndexList` verbatim and must not rebuild it as an
identity mapping.
2. **Duplicates are allowed.** `m[i]` values may repeat; a repeated logical
column must return exactly the value of the physical column it first refers to.
3. **Physical block width** is `max(m) + 1`; the client sizes its
column-type arrays from that, not from the number of logical columns.
4. **Index-based and name-based reads share the same mapping** and must
agree.
5. **Duplicate logical column names resolve to the first occurrence.**
6. Only when the mapping is absent does the client fall back to the existing
derivation (tree model: `-1` placeholder for the time column plus a shift;
identity otherwise).
7. `tableModel` must come from `resp.isSetTableModel() &&
resp.isTableModel()` and must not be hard-coded.
### 2.3 Supported data types
- Values are decoded per `dataTypeList`: `INT32`, `INT64`, `FLOAT`,
`DOUBLE`, `BOOLEAN`, `TEXT`, `STRING`, `TIMESTAMP`, `DATE`, `BLOB`.
- When several logical columns share one physical column, that column's type
declaration must be self-consistent and values are returned per the declared
type.
- Index constraint: index-based getters take 1-based external ordinals; in
the table model the valid range is `[1, columns.size()]`. An out-of-range or
empty slot must raise `SQLException`, not `ArrayIndexOutOfBoundsException`.
## 3. Examples
The server sends `columns = ["b","a"]`, `dataTypeList = ["INT32","INT32"]`,
`columnIndex2TsBlockColumnIndexList = [1,0]`, and the physical TsBlock holds
two columns with values `10` and `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); // expected 20 (logical b → physical 1)
rs.getInt("a"); // expected 10 (logical a → physical 0)
```
| `columns` | mapping | physical values | expected `[col 1, col 2]` |
expected by name |
| --- | --- | --- | --- | --- |
| `["b","a"]` | `[1,0]` | `[10, 20]` | `[20, 10]` | `b=20, a=10` |
| `["x","y"]` | `[0,0]` | `[10]` | `[10, 10]` | `x=10, y=10` (must not
throw) |
| `["a","b"]` | `[0,1]` | `[10, 20]` | `[10, 20]` | identity case,
regression control |
## 4. Current divergence and minimal fix
`IoTDBTablePreparedStatement.processQueryResult()` uses the short
`IoTDBJDBCResultSet` constructor, which does not forward the mapping,
`tableModel` or `charset`: the mapping is replaced by an identity mapping and
`tableModel` is hard-coded to `false`. Ordinary `IoTDBStatement` uses the full
constructor and forwards all three correctly, so the same response yields
different results on the two paths.
Minimal fix: switch to the full constructor and pass, after `zoneId`,
```java
charset,
resp.isSetTableModel() && resp.isTableModel(),
resp.getColumnIndex2TsBlockColumnIndexList()
```
No change is needed in `IoTDBRpcDataSet`.
## 5. Acceptance
1. All three rows in section 3 return the expected values, identical to the
`Statement` path for the same response.
2. No `ArrayIndexOutOfBoundsException`.
3. Every case asserts `getXxx(int)`, `getXxx(String)` and the actual values
— **asserting metadata alone does not pass**, because the metadata itself is
what is wrong.
4. Both shapes are covered: reordered columns, and repeated
projections/aliases.
--
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]