Spark使用Iceberg Nessie Catalog无元数据记录问题排查

以下是导致Nessie无元数据记录的常见原因及对应解决方法：

1. Spark未绑定Nessie Catalog为默认Catalog #

若仅配置了Nessie Catalog但未指定为当前会话的默认Catalog，写入操作会默认使用Spark原生的spark_catalog，导致元数据不会同步到Nessie。解决方式：

• 写入时显式指定Nessie Catalog前缀：

  INSERT INTO nessie.db.table_name ...
  

• 或在代码中设置默认Catalog：

  spark.conf().set("spark.sql.defaultCatalog", "nessie");
  

2. 缺失Nessie关键配置参数 #

Nessie Catalog的配置中，必须指定catalog-impl、uri和ref（默认分支），否则无法将元数据同步到Nessie服务。完整核心配置示例：

spark.sql.catalog.nessie=org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.nessie.catalog-impl=org.apache.iceberg.nessie.NessieCatalog
spark.sql.catalog.nessie.uri=http://localhost:19120/api/v1
spark.sql.catalog.nessie.ref=main
spark.sql.catalog.nessie.warehouse=s3a://minio-warehouse-path
spark.sql.catalog.nessie.io-impl=org.apache.iceberg.aws.s3.S3FileIO

其中ref参数指定元数据写入的目标分支，未配置时Nessie无法接收元数据。

3. 表创建未关联Nessie Catalog #

若创建表时未指定Nessie Catalog前缀，表会被注册到Spark默认Catalog，仅数据存储在MinIO，但元数据不会同步到Nessie。正确的建表语句需包含Nessie Catalog命名空间：

CREATE TABLE nessie.my_db.my_table (id INT, name STRING)
USING iceberg
LOCATION 's3a://minio-bucket/my-table';

4. 版本兼容性问题 #

Iceberg与Nessie的版本不匹配会导致元数据提交失败。需确保两者版本兼容，例如：

• Iceberg 1.3.x 对应 Nessie 0.6.x+
• Iceberg 1.4.x 对应 Nessie 0.8.x+
  检查依赖版本，确保一致（以Maven为例）：

<dependency>
    <groupId>org.apache.iceberg</groupId>
    <artifactId>iceberg-spark-runtime-3.3_2.12</artifactId>
    <version>1.3.1</version>
</dependency>
<dependency>
    <groupId>org.projectnessie</groupId>
    <artifactId>nessie-spark-extensions-3.3_2.12</artifactId>
    <version>0.7.1</version>
</dependency>

5. 写入操作未触发元数据提交 #

部分场景下，Spark写入操作可能因异常或配置问题未触发Iceberg的commit流程，导致Nessie无元数据记录。需确保：

• 写入代码无异常，作业正常完成
• 使用DataFrameWriter时指定Nessie表路径：

  df.write()
    .format("iceberg")
    .mode(SaveMode.Append)
    .save("nessie.my_db.my_table");
  

• 若使用SQL写入，确保语句执行完成且无报错

内容的提问来源于stack exchange，提问作者PowerfullDeveloper