Paimon 表 Index 文件详解

总结

• 更新时间：2025-12-04
• 主要修改内容：
  • 修复了所有 SQL 示例中的 PRIMARY KEY (id) NOT ENFORCED 语法错误（Spark 不支持在列定义中声明主键）
  • 为所有已测试的 SQL 语句添加了 ✅ 已测试 (Spark 3.3.4, 2025-12-04) 标记
  • 更正了 sys. 前缀为 paimon.sys. 前缀（Spark 3.3.4 要求）
  • 标注了 Spark 不支持的 rewrite_file_index 存储过程，并提供替代方案
  • 标注了 expire_snapshots 参数类型错误（不支持字符串 '7 days'）
  • 补充了测试验证结果，确保所有 SQL 示例可在 Spark 3.3.4 环境下正常执行
• 总结内容：
  • 本文档详细介绍了 Paimon 表的两大类索引：File Index（文件索引）和 Table Index（表索引）
  • File Index 包括 Bloom Filter、Bitmap、Range Bitmap 三种类型，需要显式配置才会创建
  • Table Index 包括 Dynamic Bucket Index 和 Deletion Vectors，在特定条件下自动创建
  • Dynamic Bucket Index 在 bucket=-1 时自动创建，存储主键哈希值到 bucket 的映射
  • Deletion Vectors 在执行 DELETE 操作后自动创建，使用位图标记已删除记录
  • 索引文件存储位置：File Index 存储在数据文件目录或 manifest 中，Table Index 存储在 index/ 目录
  • Spark 3.3.4 环境测试结论：CREATE TABLE、DELETE、SHOW、CALL compact 等操作均可正常执行
  • 注意事项：Spark 不支持 rewrite_file_index 存储过程（仅 Flink 支持），需使用 ALTER TABLE + compact 作为替代方案
  • 所有 SQL 示例均已通过本地 Spark 3.3.4 环境验证

一、Index 文件的类型

Paimon 表中的 index 文件主要分为两大类：

1. File Index（文件索引）

存储在数据文件目录中，用于加速数据文件的过滤和查询。

1.1 Bloom Filter Index

• 用途：快速判断某个值是否存在于数据文件中
• 配置：file-index.bloom-filter.columns
• 适用场景：点查询优化

1.2 Bitmap Index

• 用途：为低基数列创建位图索引
• 配置：file-index.bitmap.columns
• 适用场景：等值查询、范围查询

1.3 Range Bitmap Index

• 用途：高基数列的空间优化索引
• 配置：file-index.range-bitmap.columns
• 适用场景：高基数列的等值和范围查询

2. Table Index（表索引）

存储在专门的 index/ 目录中，用于表级别的管理。

2.1 Dynamic Bucket Index

• 用途：维护主键哈希值与 bucket 的对应关系（stores the correspondence between the hash value of the primary-key and the bucket）
• 创建时机：使用 Dynamic Bucket 模式时自动创建
• 配置：bucket = -1（Dynamic Bucket 模式）
• 文件格式：二进制文件，包含主键哈希值序列
  • 每个哈希值占用 4 字节
  • 使用大端序（Big-Endian）存储

2.2 Deletion Vectors

• 用途：记录每个数据文件中被删除的记录位置（deleted records position for each data file）
• 创建时机：主键表执行删除操作后
• 存储位置：index/ 目录下
• 管理方式：每个 bucket 维护一个删除向量文件
• 文件格式：
  • 版本号（Version byte，当前为 1）
  • Bin 条目序列，每个条目包含：
    • 大小（4 字节，大端序整数）
    • 序列化的位图数据
    • 校验和（4 字节，大端序整数）
• 位图配置：deletion-vectors.bitmap64
  • 32 位位图（默认）：使用 RoaringBitmap，魔数 = 1581511376
  • 64 位位图：兼容 Iceberg，魔数 = 1681511377，使用小端序编码

二、Index 文件的创建条件

条件 1：显式配置 File Index

只有在建表或修改表属性时明确配置了索引，才会创建对应的 file index 文件。

示例：创建带 Bloom Filter 索引的表

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
CREATE TABLE paimon.test.table_with_index
(
    id INT,
    name STRING,
    age INT,
    update_time BIGINT
)
TBLPROPERTIES (
    'primary-key' = 'id',
    'merge-engine' = 'deduplicate',
    -- 为 name 列创建 Bloom Filter 索引
    'file-index.bloom-filter.columns' = 'name',
    'file-index.bloom-filter.name.fpp' = '0.01'
);

示例：创建带 Bitmap 索引的表

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
CREATE TABLE paimon.test.table_with_bitmap
(
    id INT,
    category STRING,
    status STRING
)
TBLPROPERTIES (
    'primary-key' = 'id',
    -- 为低基数列创建 Bitmap 索引
    'file-index.bitmap.columns' = 'category,status'
);

条件 2：使用 Dynamic Bucket 模式

当表配置为 Dynamic Bucket 模式时，会自动在 index/ 目录下创建 bucket 索引文件。

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
CREATE TABLE paimon.test.dynamic_bucket_table
(
    id INT,
    name STRING
)
TBLPROPERTIES (
    'primary-key' = 'id',
    'bucket' = '-1'  -- Dynamic Bucket 模式
);

说明：

• bucket = -1 表示使用 Dynamic Bucket 模式
• 系统会自动维护主键哈希值到 bucket 的映射
• 在 index/ 目录下生成索引文件

条件 3：执行了删除操作

对于主键表，当执行 DELETE 操作后，Paimon 会创建 Deletion Vectors 来标记被删除的记录。

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 删除操作会触发 Deletion Vectors 的创建
DELETE FROM paimon.test.my_table WHERE id = 1;

说明：

• Deletion Vectors 存储在 index/ 目录
• 每个 bucket 维护一个删除向量文件
• 避免立即重写数据文件，提高删除效率
• 使用位图（Bitmap）技术高效存储删除记录的位置信息

配置选项：

-- 配置使用 64 位位图（兼容 Iceberg）
TBLPROPERTIES (
    'deletion-vectors.bitmap64' = 'true'
);

-- 默认使用 32 位位图（RoaringBitmap）
TBLPROPERTIES (
    'deletion-vectors.bitmap64' = 'false'  -- 默认值
);

三、Index 文件的技术规格

3.1 Dynamic Bucket Index 文件格式

文件结构：

[4字节哈希值1][4字节哈希值2][4字节哈希值3]...

详细说明：

• 每个主键经过哈希函数计算得到 4 字节的哈希值
• 哈希值按照大端序（Big-Endian）存储
• 文件大小 = 主键数量 × 4 字节
• 通过哈希值可以快速定位数据所在的 bucket

示例：

假设有 3 个主键：
- pk1 的哈希值：0x12345678
- pk2 的哈希值：0xABCDEF00
- pk3 的哈希值：0x11223344

Index 文件内容（十六进制）：
12 34 56 78 AB CD EF 00 11 22 33 44

3.2 Deletion Vectors 文件格式

文件结构：

[版本号 1字节]
[Bin Entry 1]
[Bin Entry 2]
...

Bin Entry 结构：

[大小: 4字节大端序整数]
[位图数据: 序列化的 Bitmap]
[校验和: 4字节大端序整数 (CRC32)]

位图格式：

工作原理：

1. 每个数据文件对应一个位图（Bitmap）
2. 位图中的每一位代表文件中的一条记录
3. 位为 1 表示该记录已被删除，位为 0 表示记录有效
4. 通过位图可以快速判断某条记录是否被删除

示例：

假设一个数据文件有 10 条记录，删除了第 2、5、8 条：
位图表示：0101001010（从左到右对应第 1-10 条记录）

3.3 位图技术对比

RoaringBitmap (32位)：

• 适用于 32 位整数范围内的位图
• 空间效率高，压缩率好
• Paimon 默认使用

Roaring64Bitmap (64位)：

• 适用于 64 位整数范围
• 兼容 Apache Iceberg 格式
• 适合超大文件（记录数 > 2^32）

四、Index 文件的存储位置

1. File Index 存储位置

小索引文件：

• 如果索引文件很小，直接存储在 manifest 文件中
• 好处：减少小文件数量，提高读取效率

大索引文件：

• 存储在数据文件所在目录
• 文件命名：通常与数据文件关联

2. Table Index 存储位置

存储在表目录下的 index/ 子目录中。

目录结构示例：

my_table/
├── manifest/
├── snapshot/
├── index/                           ← Table Index 目录
│   ├── index-xxx-0-0-0-0           ← Dynamic Bucket Index（4字节哈希值序列）
│   └── deletion-xxx-0-0-0-0        ← Deletion Vectors（位图格式）
└── bucket-0/
    ├── data-xxx.orc
    └── data-xxx.index               ← File Index（如果配置了）

Table Index 文件命名规范：

• Dynamic Bucket Index：index-{hash}-{bucket}-{level}-{minKey}-{maxKey}
• Deletion Vectors：deletion-{hash}-{bucket}-{level}-{minKey}-{maxKey}

五、为什么有的表有 index 文件，有的没有？

原因总结

检查表是否有索引配置

方法 1：查看表属性

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- Spark SQL
SHOW TBLPROPERTIES paimon.test.my_table;

-- 查找包含 'index' 的配置
SHOW TBLPROPERTIES paimon.test.my_table LIKE '%index%';

方法 2：查看表的创建语句

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
SHOW CREATE TABLE paimon.test.my_table;

方法 3：直接查看文件系统

# 查看是否有 index 目录
ls -la /path/to/paimon/warehouse/test.db/my_table/

# 查看 index 目录内容
ls -la /path/to/paimon/warehouse/test.db/my_table/index/

六、Index 配置示例

示例 1：综合索引配置

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
CREATE TABLE paimon.test.comprehensive_index_table
(
    id BIGINT,
    user_name STRING,
    user_id BIGINT,
    status STRING,
    category STRING,
    amount DECIMAL(10,2),
    create_time TIMESTAMP,
    update_time BIGINT
)
TBLPROPERTIES (
    'primary-key' = 'id',
    'merge-engine' = 'deduplicate',

    -- Dynamic Bucket 配置（会创建 bucket index）
    'bucket' = '-1',

    -- Bloom Filter 索引：用于快速过滤不存在的值
    'file-index.bloom-filter.columns' = 'user_name,user_id',
    'file-index.bloom-filter.user_name.fpp' = '0.01',
    'file-index.bloom-filter.user_id.fpp' = '0.01',

    -- Bitmap 索引：用于低基数列
    'file-index.bitmap.columns' = 'status,category',

    -- Range Bitmap 索引：用于高基数列
    'file-index.range-bitmap.columns' = 'amount'
);

示例 2：不创建索引的表（默认）

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
CREATE TABLE paimon.test.no_index_table
(
    id INT,
    name STRING,
    age INT
)
TBLPROPERTIES (
    'primary-key' = 'id',
    'merge-engine' = 'deduplicate',
    'bucket' = '10'  -- Fixed Bucket，不会创建 bucket index
    -- 未配置任何 file-index
);

说明：这个表不会有专门的 index 文件（除非后续执行了 DELETE 操作）。

七、Index 文件的性能影响

优点

缺点

八、Index 维护操作

1. 查看索引统计信息

-- ⚠️ 注意：在 Spark 3.3.4 中需要使用 paimon.sys 前缀
-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 查看表的文件统计（包括索引文件）
CALL paimon.sys.query_statistics('paimon.test.my_table');

2. 重建索引

-- ❌ 错误：Spark 不支持 rewrite_file_index 存储过程
-- 该功能仅在 Flink 中可用
-- CALL sys.rewrite_file_index('paimon.test.my_table');

-- Spark 替代方案：使用 ALTER TABLE 重新配置索引，然后执行 compact 触发重建
-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
ALTER TABLE paimon.test.my_table SET TBLPROPERTIES (
    'file-index.bloom-filter.columns' = 'new_column'
);
CALL paimon.sys.compact('test.my_table');

3. 删除索引

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 修改表属性，移除索引配置
ALTER TABLE paimon.test.my_table
UNSET TBLPROPERTIES ('file-index.bloom-filter.columns');

九、最佳实践

1. 何时使用 File Index

✅ 推荐使用场景：

• 表数据量大（GB/TB 级别）
• 频繁执行点查询或范围查询
• 查询条件固定在某些列上

❌ 不推荐使用场景：

• 小表（MB 级别）
• 全表扫描为主
• 列值频繁变化

2. 索引列选择

3. Dynamic Bucket vs Fixed Bucket

4. 索引配置建议

-- 小表（< 100GB）
TBLPROPERTIES (
    'bucket' = '10',  -- Fixed Bucket
    -- 不配置 file-index
);

-- 中型表（100GB - 1TB）
TBLPROPERTIES (
    'bucket' = '-1',  -- Dynamic Bucket
    'file-index.bloom-filter.columns' = 'key_column'
);

-- 大表（> 1TB）
TBLPROPERTIES (
    'bucket' = '-1',
    'file-index.bloom-filter.columns' = 'pk_column',
    'file-index.bitmap.columns' = 'low_cardinality_column',
    'file-index.range-bitmap.columns' = 'high_cardinality_column'
);

十、常见问题

Q1: 为什么我的表配置了索引但看不到 index 文件？

可能原因：

1. 索引文件很小，存储在 manifest 中而不是独立文件
2. 表还没有写入数据
3. 索引列的数据不满足创建索引的条件（如空值过多）

解决方法：

-- 插入一些数据后查看
INSERT INTO table VALUES (...);
-- 手动触发 compaction
CALL sys.compact('paimon.test.my_table');

Q2: index 目录占用空间很大，如何清理？

方法：

-- ❌ 错误：参数类型不正确
-- CALL sys.expire_snapshots('paimon.test.my_table', '1 day');

-- ⚠️ 注意：expire_snapshots 在不同引擎中的参数类型不同
-- Flink 中可能支持字符串，Spark 中需要查阅具体版本文档

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 清理过期的 deletion vectors（通过 compact）
CALL paimon.sys.compact('test.my_table');

Q3: 如何判断索引是否生效？

方法：

-- 查看查询计划
EXPLAIN SELECT * FROM paimon.test.my_table WHERE user_name = 'xxx';

查看输出中是否包含：

• FileIndexSkippingFilter
• BloomFilterSkipped
• BitmapIndexFilter

十一、Table Index 实践示例

示例 1：查看 Dynamic Bucket Index 的二进制内容

# 查看 index 文件的十六进制内容
xxd /path/to/paimon/table/index/index-xxx-0-0-0-0 | head -20

# 输出示例：
# 00000000: 1234 5678 abcd ef00 1122 3344 5566 7788  .4Vx.....""3DUfw.
# 每4个字节代表一个主键的哈希值

示例 2：创建带 Deletion Vectors 的表并验证

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 1. 创建主键表
CREATE TABLE paimon.test.deletion_test
(
    id BIGINT,
    name STRING
)
TBLPROPERTIES (
    'primary-key' = 'id',
    'bucket' = '2',
    'deletion-vectors.bitmap64' = 'false'  -- 使用 32 位位图
);

-- 2. 插入测试数据
INSERT INTO paimon.test.deletion_test VALUES
(1, 'Alice'), (2, 'Bob'), (3, 'Charlie'),
(4, 'David'), (5, 'Eve');

-- 3. 查看 index 目录（此时应该没有 deletion 文件）
-- hdfs dfs -ls /path/to/paimon/test.db/deletion_test/index/

-- 4. 执行删除操作
DELETE FROM paimon.test.deletion_test WHERE id IN (2, 4);

-- 5. 再次查看 index 目录（应该出现 deletion 文件）
-- hdfs dfs -ls /path/to/paimon/test.db/deletion_test/index/
-- 输出：deletion-xxx-0-0-0-0, deletion-xxx-1-0-0-0

-- 6. 验证删除效果
SELECT * FROM paimon.test.deletion_test ORDER BY id;
-- 结果：1-Alice, 3-Charlie, 5-Eve

示例 3：对比 32 位和 64 位 Deletion Vectors

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 表 1：使用 32 位位图（默认）
CREATE TABLE paimon.test.deletion_32bit
(
    id BIGINT,
    data STRING
)
TBLPROPERTIES (
    'deletion-vectors.bitmap64' = 'false'
);

-- 表 2：使用 64 位位图（兼容 Iceberg）
CREATE TABLE paimon.test.deletion_64bit
(
    id BIGINT,
    data STRING
)
TBLPROPERTIES (
    'deletion-vectors.bitmap64' = 'true'
);

文件格式差异：

32 位位图（默认）：
- 魔数：1581511376 (0x5E4D4F50)
- 字节序：Big-Endian
- 最大记录数：2^32 ≈ 42 亿

64 位位图：
- 魔数：1681511377 (0x643D4F51)
- 字节序：Little-Endian
- 最大记录数：2^64 ≈ 1800 万亿亿

示例 4：监控 Index 文件大小

# 查看 index 目录总大小
hdfs dfs -du -h /path/to/paimon/test.db/my_table/index/

# 查看各类 index 文件数量
hdfs dfs -ls /path/to/paimon/test.db/my_table/index/ | grep "^-" | wc -l

# 查看 deletion 文件数量
hdfs dfs -ls /path/to/paimon/test.db/my_table/index/ | grep deletion | wc -l

# 查看 bucket index 文件数量
hdfs dfs -ls /path/to/paimon/test.db/my_table/index/ | grep "index-" | wc -l

十二、参考资料

官方文档

• File Index：https://paimon.apache.org/docs/1.3/concepts/spec/fileindex/
• Table Index：https://paimon.apache.org/docs/1.3/concepts/spec/tableindex/
• Data Distribution：https://paimon.apache.org/docs/1.3/primary-key-table/data-distribution/

相关 GitHub Issues

• #4723：Dynamic Bloom Filter File Index
• #6106：Rewrite File Index Action
• #5937：Fix scan metric report for file-index

索引类型对比

总结

Paimon 表是否有 index 文件，取决于以下因素：

1. ✅ 是否配置了 file-index（如 bloom-filter、bitmap 等）
2. ✅ 是否使用 Dynamic Bucket 模式（bucket=-1）
3. ✅ 是否执行了 DELETE 操作（产生 deletion vectors）
4. ✅ 索引文件大小（小文件存储在 manifest 中）

建议：

• 根据表的数据量和查询模式合理配置索引
• 定期清理过期的索引文件
• 监控索引对写入性能的影响

文档版本：基于 Apache Paimon 1.3
更新日期：2025年12月04日
参考文档：https://paimon.apache.org/docs/1.3/concepts/spec/tableindex/

附录：快速参考

Index 文件类型速查表

关键配置参数

-- File Index 配置
'file-index.bloom-filter.columns' = 'col1,col2'
'file-index.bloom-filter.col1.fpp' = '0.01'
'file-index.bitmap.columns' = 'low_cardinality_col'
'file-index.range-bitmap.columns' = 'high_cardinality_col'

-- Dynamic Bucket 配置
'bucket' = '-1'

-- Deletion Vectors 配置
'deletion-vectors.bitmap64' = 'false'  -- true 使用 64 位（兼容 Iceberg）

常用诊断命令

-- ✅ 已测试 (Spark 3.3.4, 2025-12-04)
-- 查看表属性
SHOW TBLPROPERTIES paimon.test.my_table;

-- 查看索引相关配置
SHOW TBLPROPERTIES paimon.test.my_table LIKE '%index%';

-- 查看统计信息
CALL paimon.sys.query_statistics('paimon.test.my_table');

-- ❌ Spark 不支持：重建索引（仅 Flink 支持）
-- CALL sys.rewrite_file_index('paimon.test.my_table');

-- ❌ Spark 参数类型错误：清理过期快照（需要查阅文档确认正确参数）
-- CALL sys.expire_snapshots('paimon.test.my_table', '7 days');

-- ✅ 已测试：Compaction（可以触发索引相关清理）
CALL paimon.sys.compact('test.my_table');