Apache Iceberg REST Catalog中createTransaction方法覆盖表默认值的问题分析

问题背景

在Apache Iceberg项目中，REST Catalog提供了一个重要的功能——允许用户通过REST API来管理Iceberg表。最近发现了一个关于表属性默认值处理的bug，当用户尝试在创建事务时覆盖表默认属性时，系统会抛出"Multiple entries with same key"的异常。

问题现象

当使用REST Catalog构建表时，如果同时满足以下两个条件：

1. 表有一个默认属性（例如"default-key2"）
2. 用户尝试在创建事务时覆盖这个默认属性

系统会抛出IllegalArgumentException异常，提示存在重复的键值对。例如，当用户尝试将"default-key2"的值从"catalog-default-key2"覆盖为"catalog-overridden-key2"时，系统会报错。

技术原因分析

这个问题的根本原因在于PR #11646引入了REST会话目录中可配置的表默认属性功能，但实现不完整。具体来说：

1. 在REST会话目录的create方法中，使用了buildKeepingLast来正确处理属性覆盖
2. 但是其他构建器终端方法（如createTransaction）没有采用相同的处理逻辑
3. 当用户尝试覆盖默认属性时，系统会同时保留原始默认值和覆盖值，导致键冲突

解决方案

修复这个问题的正确做法是：

1. 确保所有表构建器的终端方法（包括createTransaction）都使用buildKeepingLast逻辑
2. 统一处理属性覆盖的优先级：用户显式设置的属性 > 表默认属性 > 目录默认属性
3. 保持与create方法一致的行为，避免出现不一致的情况

影响范围

这个问题主要影响以下使用场景：

• 使用REST Catalog创建表事务
• 表配置了默认属性
• 用户尝试在创建事务时覆盖这些默认属性

对于不使用REST Catalog或者不覆盖表默认属性的用户，不会遇到这个问题。

最佳实践建议

在使用Iceberg REST Catalog时，建议开发者：

1. 明确了解表属性的优先级顺序
2. 在覆盖默认属性时，检查使用的API方法是否支持属性覆盖
3. 如果遇到类似问题，可以考虑升级到包含修复的版本
4. 在自定义表属性时，避免与系统默认属性使用相同的键名

这个问题已经在最新版本中得到修复，开发者可以放心使用表属性覆盖功能。