Skip to content

Commit 538b645

Browse files
committed
docs: attach requirements for apache#66816
1 parent d6c3470 commit 538b645

1 file changed

Lines changed: 315 additions & 0 deletions

File tree

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# File Scanner V2 Native Reader 支持 Iceberg/Paimon 文件路径与物理行位置
2+
3+
## 1. 功能背景
4+
5+
在排查湖表数据问题、定位异常记录以及构造行级数据操作时,需要知道每条查询结果来自哪个物理数据文件,以及它在该文件中的物理行位置。
6+
7+
本功能在 Doris File Scanner V2 的 Native Parquet/ORC Reader 中提供 Iceberg 和 Paimon 的文件路径与物理行位置 metadata columns。
8+
9+
## 2. 功能目标
10+
11+
支持用户在查询 Iceberg/Paimon 表时,显式查询每条可见记录对应的:
12+
13+
- 物理数据文件路径;
14+
- 物理数据文件内从 0 开始的绝对行位置。
15+
16+
具体列定义如下:
17+
18+
| 表格式 | 文件路径列 | 物理行位置列 |
19+
| --- | --- | --- |
20+
| Iceberg | `_file STRING` | `_pos BIGINT` |
21+
| Paimon | `__paimon_file_path STRING` | `__paimon_row_index BIGINT` |
22+
23+
列名和语义分别遵循:
24+
25+
- [Iceberg metadata column 规范](https://iceberg.apache.org/spec/?h=snapshot)
26+
- [Paimon hidden metadata column 定义](https://paimon.apache.org/docs/master/spark/sql-query/)
27+
28+
## 3. 术语与语义
29+
30+
### 3.1 文件路径
31+
32+
- 文件路径表示记录所在物理数据文件在 Iceberg/Paimon 元数据中记录的原始路径。
33+
- Iceberg `_file` 返回 Iceberg data file metadata 中记录的路径。
34+
- Paimon `__paimon_file_path` 返回 `RawFile.path()` 对应的路径。
35+
- 不得返回 BE 本地缓存路径、临时路径或 reader 内部路径。
36+
- 即使 Doris 为读取文件进行了 URI scheme 或 endpoint 归一化,对用户返回的仍应是表元数据中的原始路径。
37+
38+
### 3.2 物理行位置
39+
40+
- 物理行位置从 `0` 开始。
41+
- 行位置是相对于整个物理数据文件的绝对位置。
42+
- 行位置不是以下任一种序号:
43+
- File Scanner split 内偏移;
44+
- Parquet row group 内偏移;
45+
- ORC stripe 内偏移;
46+
- 过滤后的结果集序号;
47+
- 查询结果输出顺序。
48+
- `(file_path, row_position)` 在同一个表快照中可以唯一定位一条物理记录。
49+
- 数据文件经过 compaction 或 rewrite 后,同一逻辑记录的文件路径和物理行位置允许发生变化。
50+
51+
### 3.3 与逻辑 Row ID 的区别
52+
53+
本功能提供的是物理行位置,不提供跨文件重写保持稳定的逻辑 Row ID。
54+
55+
以下能力不在本需求范围内:
56+
57+
- Iceberg V3 `_row_id` 的新增或增强;
58+
- Paimon row-tracking `_ROW_ID`;
59+
- 根据逻辑 Row ID 定位、更新或删除记录。
60+
61+
## 4. 查询示例
62+
63+
### 4.1 Iceberg
64+
65+
```sql
66+
SELECT id, _file, _pos
67+
FROM iceberg_catalog.db.table
68+
WHERE _pos >= 0
69+
ORDER BY _file, _pos;
70+
```
71+
72+
### 4.2 Paimon
73+
74+
```sql
75+
SELECT id, __paimon_file_path, __paimon_row_index
76+
FROM paimon_catalog.db.table
77+
ORDER BY __paimon_file_path, __paimon_row_index;
78+
```
79+
80+
### 4.3 参与过滤和聚合
81+
82+
```sql
83+
SELECT _file, COUNT(*)
84+
FROM iceberg_catalog.db.table
85+
GROUP BY _file;
86+
```
87+
88+
```sql
89+
SELECT *
90+
FROM paimon_catalog.db.table
91+
WHERE __paimon_file_path = 's3://bucket/path/data.parquet'
92+
AND __paimon_row_index BETWEEN 100 AND 200;
93+
```
94+
95+
## 5. 支持范围
96+
97+
### 5.1 支持
98+
99+
- File Scanner V2;
100+
- Native Parquet Reader;
101+
- Native ORC Reader;
102+
- Iceberg 数据表;
103+
- 能够转换为 Native RawFile split 的 Paimon 数据表;
104+
- 普通扫描和谓词过滤;
105+
- lazy materialization;
106+
- runtime filter;
107+
- Iceberg position delete;
108+
- Iceberg equality delete;
109+
- Iceberg deletion vector;
110+
- Paimon deletion vector;
111+
- 文件 sub-split 并行扫描;
112+
- snapshot/time travel 查询。
113+
114+
### 5.2 不支持
115+
116+
- Paimon JNI Reader;
117+
- Paimon native/JNI 混合 split 的 metadata column 查询;
118+
- `force_jni_scanner=true` 下的 Paimon metadata column 查询;
119+
- File Scanner V1;
120+
- Iceberg/Paimon 非 Parquet、ORC 数据文件;
121+
- Paimon 稳定逻辑 `_ROW_ID`;
122+
- Iceberg V3 `_row_id` 的新增或增强。
123+
124+
### 5.3 不支持场景的行为
125+
126+
当查询引用本功能提供的 metadata columns,但实际 scan range 不能使用 File Scanner V2 Native Parquet/ORC Reader 时,必须明确报错。
127+
128+
禁止以下行为:
129+
130+
- 返回 `NULL`;
131+
- 返回默认值或错误值;
132+
- 忽略 metadata column;
133+
- 只返回 native split 的部分结果;
134+
- 在已经输出部分结果后再报错。
135+
136+
建议错误信息包含 metadata column、表格式和实际 reader 类型,例如:
137+
138+
```text
139+
Metadata column '<column>' is only supported by FileScannerV2 native
140+
Parquet/ORC reader for <table_format>; actual reader is <reader_type>.
141+
```
142+
143+
## 6. 验收标准
144+
145+
### AC-1:列定义与可见性
146+
147+
- Iceberg 提供:
148+
- `_file STRING NOT NULL`
149+
- `_pos BIGINT NOT NULL`
150+
- Paimon 提供:
151+
- `__paimon_file_path STRING NOT NULL`
152+
- `__paimon_row_index BIGINT NOT NULL`
153+
- 默认 `SELECT *` 不包含这些 metadata columns。
154+
- 用户可以在 `show_hidden_columns=false` 时显式引用这些列。
155+
- `show_hidden_columns=true` 时,`DESC` 和 `SELECT *` 能看到对应 metadata columns。
156+
- Metadata columns 不得被当成 Parquet/ORC 中的真实物理列读取。
157+
158+
### AC-2:文件路径正确性
159+
160+
- Iceberg `_file` 返回 Iceberg data file metadata 中记录的原始路径。
161+
- Paimon `__paimon_file_path` 返回 `RawFile.path()` 对应的原始路径。
162+
- 不得返回 BE 本地缓存路径、临时路径或内部 reader 路径。
163+
- 对 `s3a://`、`oss://` 等经过 Doris 存储路径归一化的文件,返回值仍应保持表元数据中的原始路径。
164+
- 同一个物理文件中的所有记录返回相同路径。
165+
166+
### AC-3:物理行位置正确性
167+
168+
- 第一条物理记录的行位置为 `0`。
169+
- 行位置跨 Parquet row group 连续。
170+
- 行位置跨 ORC stripe 连续。
171+
- 文件被切成多个 scan range 后,行位置仍然是文件级绝对位置。
172+
- 不同 split 不得产生重复或重叠的 `(file_path, row_position)`。
173+
- 多 BE 并行执行不能改变行位置。
174+
175+
### AC-4:过滤后保持原始行位置
176+
177+
假设物理文件包含行位置 `0,1,2,3,4`,查询过滤后只保留原始位置 `1,4`,返回结果必须仍为:
178+
179+
```text
180+
1
181+
4
182+
```
183+
184+
不得重新编号为:
185+
186+
```text
187+
0
188+
1
189+
```
190+
191+
以下过滤路径均须满足该要求:
192+
193+
- 普通 WHERE 谓词;
194+
- Parquet dictionary/page/row-group pruning;
195+
- ORC SARG/stripe pruning;
196+
- lazy materialization;
197+
- runtime filter。
198+
199+
### AC-5:Delete/DV 处理正确
200+
201+
- 被 Iceberg position delete 删除的记录不出现在结果中。
202+
- 被 Iceberg equality delete 删除的记录不出现在结果中。
203+
- 被 Iceberg/Paimon deletion vector 删除的记录不出现在结果中。
204+
- 删除过滤后,剩余记录的 row position 必须保持原始文件位置,不能重新编号。
205+
- Metadata columns 与业务列必须逐行对齐,不能出现错位。
206+
207+
### AC-6:Metadata column 表达式正确
208+
209+
以下场景结果正确:
210+
211+
- 仅投影文件路径;
212+
- 仅投影行位置;
213+
- 同时投影业务列、文件路径和行位置;
214+
- metadata column 出现在 `WHERE`;
215+
- metadata column 出现在 `ORDER BY`;
216+
- metadata column 出现在 `GROUP BY`;
217+
- metadata column 参与比较、范围和聚合表达式;
218+
- 多表 JOIN 中分别引用两张表的 metadata columns。
219+
220+
Metadata column 谓词暂不要求下推到文件 reader,但最终结果必须正确。
221+
222+
### AC-7:聚合下推正确性
223+
224+
对于以下查询:
225+
226+
```sql
227+
SELECT COUNT(*)
228+
FROM iceberg_table
229+
WHERE _file = '...';
230+
```
231+
232+
或者:
233+
234+
```sql
235+
SELECT COUNT(*)
236+
FROM paimon_table
237+
WHERE __paimon_row_index >= 100;
238+
```
239+
240+
- 不得使用会跳过 metadata predicate 的文件级或表级 COUNT 下推。
241+
- 如果当前聚合下推无法计算 metadata predicate,必须退化成实际扫描。
242+
- 不得返回未应用 metadata predicate 的文件总行数。
243+
244+
### AC-8:Native-only 边界
245+
246+
当查询引用 metadata columns 时:
247+
248+
- 所有 split 均为 File Scanner V2 Native Parquet/ORC:正常执行。
249+
- Paimon 全部为 JNI split:查询失败并明确提示不支持。
250+
- Paimon 同时包含 native 和 JNI split:整个查询失败。
251+
- `force_jni_scanner=true`:查询失败。
252+
- File Scanner V2 被关闭:查询失败。
253+
- 数据文件格式不是 Parquet/ORC:查询失败。
254+
- 必须在返回第一批结果前失败,不允许产生部分结果。
255+
256+
不引用 metadata columns 的已有 JNI、mixed split 和 File Scanner V1 查询行为保持不变。
257+
258+
### AC-9:Snapshot 与文件重写
259+
260+
- Snapshot/time travel 查询返回所选快照对应的数据文件路径和行位置。
261+
- 查询历史快照时,不得错误返回最新快照的文件路径。
262+
- compaction/rewrite 前后的 `(file_path, row_position)` 可以变化。
263+
- 同一快照重复查询时,结果必须一致,不受并发调度和 scan range 划分影响。
264+
265+
### AC-10:性能与资源
266+
267+
- 未引用 metadata columns 时,不增加行位置列物化,不产生可观测的额外数据文件 IO。
268+
- 引用 metadata columns 时,不额外读取数据文件中的物理列。
269+
- 文件路径应优先使用常量列或等价低内存表示,避免在中间 Block 中为每行重复复制完整路径字符串。
270+
- 行位置列的额外内存开销应接近 `8 × rows`。
271+
- 大文件、多 row group/stripe 扫描不能出现明显内存膨胀或 OOM。
272+
273+
## 7. 风险点
274+
275+
| 编号 | 风险描述 | 来源 | 影响面 | 严重程度 |
276+
| --- | --- | --- | --- | --- |
277+
| R1 | row position 被计算成 split/row-group/stripe 内偏移 | 白盒 | 返回错误定位信息 | P0 |
278+
| R2 | 谓词、lazy read、delete/DV 后 metadata 与业务列错位 | 黑盒+白盒 | 错误数据定位 | P0 |
279+
| R3 | Paimon mixed split 静默返回 NULL 或部分结果 | 黑盒 | Wrong result | P0 |
280+
| R4 | metadata predicate 被 COUNT 下推跳过 | 白盒 | 聚合结果错误 | P0 |
281+
| R5 | 返回路径是归一化路径或本地缓存路径 | 黑盒 | 无法和表元数据关联 | P1 |
282+
| R6 | 文件 sub-split 产生重复行号 | 白盒 | 行定位不唯一 | P1 |
283+
| R7 | metadata column 被错误识别为物理列 | 白盒 | Missing column 或读取失败 | P1 |
284+
| R8 | 每行复制长文件路径导致内存膨胀 | 白盒 | 性能退化或 OOM | P2 |
285+
| R9 | 新功能影响未引用 metadata column 的旧查询 | 兼容性 | 查询行为回归 | P1 |
286+
287+
## 8. 核心测试用例
288+
289+
| 用例 | 目标 | 覆盖风险 | 测试维度 | 前置条件 | 负载描述 | 执行预期 |
290+
| --- | --- | --- | --- | --- | --- | --- |
291+
| TC-01 | 验证 Iceberg Parquet 基本语义 | R1、R5、R7 | 功能/正确性 | 多 row group Iceberg Parquet 表 | 查询 `_file/_pos` | 路径正确,位置从 0 开始且跨 row group 连续 |
292+
| TC-02 | 验证 Iceberg ORC 基本语义 | R1、R5、R7 | 功能/正确性 | 多 stripe Iceberg ORC 表 | 查询 `_file/_pos` | 路径正确,位置跨 stripe 连续 |
293+
| TC-03 | 验证过滤和 lazy materialization | R1、R2 | 正确性 | 数据物理位置已知 | 使用列谓词、runtime filter、lazy read | 返回原始物理位置,不重新编号 |
294+
| TC-04 | 验证 Iceberg delete | R2 | 正确性 | 分别构造 position/equality/DV delete | 查询 metadata columns | 删除行不返回,剩余行位置保持不变 |
295+
| TC-05 | 验证 Paimon native 与 DV | R1、R2、R5 | 正确性 | Native Parquet/ORC Paimon 表,包含 DV | 查询路径和行位置 | DV 行被过滤,剩余位置与原文件一致 |
296+
| TC-06 | 验证文件 sub-split | R1、R6 | 正确性/性能 | 小 `file_split_size`,单文件切成多个 range | 并行扫描全部 range | `(path,row_index)` 无重复、无遗漏 |
297+
| TC-07 | 验证 JNI/mixed split 拒绝 | R3、R9 | 异常/兼容性 | JNI、mixed、force JNI 三种场景 | 引用 metadata columns | 整个查询在返回结果前明确失败;普通列查询不受影响 |
298+
| TC-08 | 验证 metadata predicate 与 COUNT | R4 | 正确性 | 多文件且文件行数已知 | `COUNT(*) WHERE path/position predicate` | 不错误下推,计数与实际扫描一致 |
299+
| TC-09 | 验证 snapshot/time travel | R5、R6 | 正确性 | rewrite 前后两个快照 | 分别查询两个快照 | 各自返回对应快照的文件路径和行位置 |
300+
| TC-10 | 验证资源开销 | R8、R9 | 性能 | 大文件、长对象存储路径 | 对比投影/不投影 metadata columns | 无额外文件 IO;未投影无明显开销;路径不在中间 Block 中按行重复大量分配 |
301+
302+
## 9. 覆盖度检查
303+
304+
- R1:TC-01、TC-02、TC-03、TC-05、TC-06 覆盖。
305+
- R2:TC-03、TC-04、TC-05 覆盖。
306+
- R3:TC-07 覆盖。
307+
- R4:TC-08 覆盖。
308+
- R5:TC-01、TC-02、TC-05、TC-09 覆盖。
309+
- R6:TC-06、TC-09 覆盖。
310+
- R7:TC-01、TC-02 覆盖。
311+
- R8:TC-10 覆盖。
312+
- R9:TC-07、TC-10 覆盖。
313+
314+
所有 P0/P1 风险均至少由一个核心测试用例覆盖。
315+

0 commit comments

Comments
 (0)