Databricks创建Delta表时userMetadata初始提交值未写入问题

原因分析 #

这是因为使用saveAsTable创建Delta表的初始写入操作，默认不会将userMetadata参数记录到Delta事务历史中。Delta Lake的userMetadata是为事务提交设计的自定义元数据字段，但初始创建表的底层处理逻辑和后续的追加、覆盖等数据修改事务存在差异：在早期Delta版本（甚至部分当前版本的实现）中，建表的初始化步骤并不会捕获userMetadata参数，只有后续针对已有表的数据修改事务才会生效。

解决方法 #

如果需要在初始创建表时也记录userMetadata，可以通过以下两种方式实现：

方法1：先创建空表并指定元数据，再写入初始数据 #

先通过SQL语句创建带有初始userMetadata的空Delta表，再将初始数据追加进去：

tableName = "myCatalog.mySchema.metaDataTest"
# 创建空表并设置初始userMetadata
spark.sql(f"""
CREATE TABLE {tableName} (LastName STRING, FirstName STRING)
USING delta
TBLPROPERTIES ('delta.userMetadata' = 'Initial Commit')
""")
# 写入初始数据
df1.write.mode("append").format("delta").saveAsTable(tableName)

方法2：使用save路径写入后注册为表 #

先将数据写入指定路径（此时userMetadata会被正常记录到事务历史），再将路径注册为表：

tableName = "myCatalog.mySchema.metaDataTest"
savePath = "/dbfs/path/to/your/delta/table"
# 写入数据到路径，userMetadata会被记录
df1.write.format("delta").option("userMetadata", "Initial Commit").save(savePath)
# 将路径注册为Catalog中的表
spark.sql(f"CREATE TABLE {tableName} USING delta LOCATION '{savePath}'")

内容的提问来源于Stack Exchange，提问作者Shawn Eary