[spark] assign reserved row tracking field id for uniform tables (#4803)

<!--
Thanks for sending a pull request!  Here are some tips for you:
1. If this is your first time, please read our contributor guidelines:
https://github.com/delta-io/delta/blob/master/CONTRIBUTING.md
2. If the PR is unfinished, add '[WIP]' in your PR title, e.g., '[WIP]
Your PR title ...'.
  3. Be sure to keep the PR description updated to reflect all changes.
  4. Please write your PR title to summarize what this PR proposes.
5. If possible, provide a concise example to reproduce the issue for a
faster review.
6. If applicable, include the corresponding issue number in the PR title
and link it in the body.
-->



#### Which Delta project/connector is this regarding?
<!--
Please add the component selected below to the beginning of the pull
request title
For example: [Spark] Title of my pull request
-->

- [x] Spark
- [ ] Standalone
- [ ] Flink
- [ ] Kernel
- [ ] Other (fill in here)

## Description

<!--
- Describe what this PR changes.
- Describe why we need the change.
 
If this PR resolves an issue be sure to include "Resolves #XXX" to
correctly link and close the issue upon merge.
-->

For uniform tables, to make the materialized row id column and row
commit version column is understandable by Iceberg, we need to assign
the corresponding parquet field id to these two columns.

## How was this patch tested?

<!--
If tests were added, say they were added here. Please make sure to test
the changes thoroughly including negative and positive cases if
possible.
If the changes were tested in any way other than unit tests, please
clarify how you tested step by step (ideally copy and paste-able, so
that other reviewers can test and check, and descendants can verify in
the future).
If the changes were not tested, please explain why.
-->

## Does this PR introduce _any_ user-facing changes?

<!--
If yes, please clarify the previous behavior and the change this PR
proposes - provide the console output, description and/or an example to
show the behavior difference if possible.
If possible, please also clarify if this is a user-facing change
compared to the released Delta Lake versions or within the unreleased
branches such as master.
If no, write 'No'.
-->

Author: KaiqiJinWow

spark/src/main/scala/org/apache/spark/sql/delta/RowCommitVersion.scala

@@ -16,6 +16,7 @@
 
 package org.apache.spark.sql.delta
 
+import org.apache.spark.sql.delta.DeltaColumnMapping.PARQUET_FIELD_ID_METADATA_KEY
 import org.apache.spark.sql.delta.actions.{Metadata, Protocol}
 import org.apache.spark.sql.util.ScalaExtensions._
 
@@ -35,9 +36,10 @@ object RowCommitVersion {
   def createMetadataStructField(
       protocol: Protocol,
       metadata: Metadata,
-      nullable: Boolean = false): Option[StructField] =
+      nullable: Boolean = false,
+      shouldSetIcebergReservedFieldId: Boolean): Option[StructField] =
     MaterializedRowCommitVersion.getMaterializedColumnName(protocol, metadata)
-      .map(MetadataStructField(_, nullable))
+      .map(MetadataStructField(_, nullable, shouldSetIcebergReservedFieldId))
 
   /**
    * Add a new column to `dataFrame` that has the name of the materialized Row Commit Version column
@@ -56,22 +58,35 @@ object RowCommitVersion {
 
     val rowCommitVersionColumn =
       DeltaTableUtils.getFileMetadataColumn(dataFrame).getField(METADATA_STRUCT_FIELD_NAME)
-    preserveRowCommitVersionsUnsafe(dataFrame, materializedColumnName, rowCommitVersionColumn)
+    val shouldSetIcebergReservedFieldId = IcebergCompat.isGeqEnabled(snapshot.metadata, 3)
+
+    preserveRowCommitVersionsUnsafe(
+      dataFrame,
+      materializedColumnName,
+      rowCommitVersionColumn,
+      shouldSetIcebergReservedFieldId
+    )
   }
 
   private[delta] def preserveRowCommitVersionsUnsafe(
       dataFrame: DataFrame,
       materializedColumnName: String,
-      rowCommitVersionColumn: Column): DataFrame = {
+      rowCommitVersionColumn: Column,
+      shouldSetIcebergReservedFieldId: Boolean): DataFrame = {
     dataFrame
       .withColumn(materializedColumnName, rowCommitVersionColumn)
-      .withMetadata(materializedColumnName, MetadataStructField.metadata(materializedColumnName))
+      .withMetadata(
+        materializedColumnName,
+        MetadataStructField.metadata(materializedColumnName, shouldSetIcebergReservedFieldId))
   }
 
   object MetadataStructField {
     private val METADATA_COL_ATTR_KEY = "__row_commit_version_metadata_col"
 
-    def apply(materializedColumnName: String, nullable: Boolean = false): StructField =
+    def apply(
+        materializedColumnName: String,
+        nullable: Boolean = false,
+        shouldSetIcebergReservedFieldId: Boolean): StructField =
       StructField(
         METADATA_STRUCT_FIELD_NAME,
         LongType,
@@ -80,17 +95,32 @@ object RowCommitVersion {
         // injected before the optimizer pass by the [[GenerateRowIDs] rule at which point the Row
         // commit version field is non-nullable.
         nullable,
-        metadata = metadata(materializedColumnName))
+        metadata = metadata(materializedColumnName, shouldSetIcebergReservedFieldId))
 
     def unapply(field: StructField): Option[StructField] =
       Option.when(isValid(field.dataType, field.metadata))(field)
 
-    def metadata(materializedColumnName: String): types.Metadata = new MetadataBuilder()
-      .withMetadata(
-        FileSourceGeneratedMetadataStructField.metadata(
-          METADATA_STRUCT_FIELD_NAME, materializedColumnName))
-      .putBoolean(METADATA_COL_ATTR_KEY, value = true)
-      .build()
+    def metadata(
+        materializedColumnName: String,
+        shouldSetIcebergReservedFieldId: Boolean): types.Metadata = {
+      val metadataBuilder = new MetadataBuilder()
+        .withMetadata(
+          FileSourceGeneratedMetadataStructField.metadata(
+            METADATA_STRUCT_FIELD_NAME, materializedColumnName))
+        .putBoolean(METADATA_COL_ATTR_KEY, value = true)
+
+      // If IcebergCompatV3 or higher is enabled, assign the field ID of Delta
+      // Row commit version column to match the reserved `_last_updated_sequence_number`
+      // field defined in the Iceberg spec.
+      // This ensures that Iceberg can recognize and track the same column for row lineage purposes.
+      if (shouldSetIcebergReservedFieldId) {
+        metadataBuilder.putLong(
+          PARQUET_FIELD_ID_METADATA_KEY,
+          IcebergConstants.ICEBERG_ROW_TRACKING_LAST_UPDATED_SEQUENCE_NUMBER_FIELD_ID
+        )
+      }
+      metadataBuilder.build()
+    }
 
     /** Return true if the column is a Row Commit Version column. */
     def isRowCommitVersionColumn(structField: StructField): Boolean =
@@ -103,12 +133,21 @@ object RowCommitVersion {
     }
   }
 
-  def columnMetadata(materializedColumnName: String): types.Metadata =
-    MetadataStructField.metadata(materializedColumnName)
+  def columnMetadata(
+      materializedColumnName: String,
+      shouldSetIcebergReservedFieldId: Boolean): types.Metadata =
+    MetadataStructField.metadata(materializedColumnName, shouldSetIcebergReservedFieldId)
 
   object MetadataAttribute {
-    def apply(materializedColumnName: String): AttributeReference =
-      DataTypeUtils.toAttribute(MetadataStructField(materializedColumnName))
+    def apply(
+        materializedColumnName: String,
+        shouldSetIcebergReservedFieldId: Boolean): AttributeReference =
+      DataTypeUtils
+        .toAttribute(
+          MetadataStructField(
+            materializedColumnName,
+            shouldSetIcebergReservedFieldId = shouldSetIcebergReservedFieldId
+          ))
         .withName(materializedColumnName)
 
     def unapply(attr: Attribute): Option[Attribute] =

spark/src/main/scala/org/apache/spark/sql/delta/RowId.scala

@@ -16,6 +16,7 @@
 
 package org.apache.spark.sql.delta
 
+import org.apache.spark.sql.delta.DeltaColumnMapping.PARQUET_FIELD_ID_METADATA_KEY
 import org.apache.spark.sql.delta.actions.{Action, AddFile, DomainMetadata, Metadata, Protocol}
 import org.apache.spark.sql.delta.actions.TableFeatureProtocolUtils.propertyKey
 import org.apache.spark.sql.util.ScalaExtensions._
@@ -183,17 +184,22 @@ object RowId {
   val QUALIFIED_COLUMN_NAME = s"${FileFormat.METADATA_NAME}.${ROW_ID}"
 
   /** Column metadata to be used in conjunction [[QUALIFIED_COLUMN_NAME]] to mark row id columns */
-  def columnMetadata(materializedColumnName: String): types.Metadata =
-    RowIdMetadataStructField.metadata(materializedColumnName)
+  def columnMetadata(
+      materializedColumnName: String,
+      shouldSetIcebergReservedFieldId: Boolean): types.Metadata =
+    RowIdMetadataStructField.metadata(materializedColumnName, shouldSetIcebergReservedFieldId)
 
   /**
    * The field readers can use to access the generated row id column. The scanner's internal column
    * name is obtained from the table's metadata.
    */
-  def createRowIdField(protocol: Protocol, metadata: Metadata, nullable: Boolean)
-  : Option[StructField] =
+  def createRowIdField(
+    protocol: Protocol,
+    metadata: Metadata,
+    nullable: Boolean,
+    shouldSetIcebergReservedFieldId: Boolean): Option[StructField] =
     MaterializedRowId.getMaterializedColumnName(protocol, metadata)
-      .map(RowIdMetadataStructField(_, nullable))
+      .map(RowIdMetadataStructField(_, nullable, shouldSetIcebergReservedFieldId))
 
   /*
    * A specialization of [[FileSourceGeneratedMetadataStructField]] used to represent RowId columns.
@@ -209,21 +215,38 @@ object RowId {
 
     val ROW_ID_METADATA_COL_ATTR_KEY = "__row_id_metadata_col"
 
-    def metadata(materializedColumnName: String): types.Metadata = new MetadataBuilder()
-      .withMetadata(
-        FileSourceGeneratedMetadataStructField.metadata(RowId.ROW_ID, materializedColumnName))
-      .putBoolean(ROW_ID_METADATA_COL_ATTR_KEY, value = true)
-      .build()
+    def metadata(
+        materializedColumnName: String,
+        shouldSetIcebergReservedFieldId: Boolean): types.Metadata = {
+      val metadataBuilder = new MetadataBuilder()
+        .withMetadata(
+          FileSourceGeneratedMetadataStructField.metadata(RowId.ROW_ID, materializedColumnName))
+        .putBoolean(ROW_ID_METADATA_COL_ATTR_KEY, value = true)
+
+      // If IcebergCompatV3 or higher is enabled, assign the field ID of Delta row id column
+      // to match the reserved `_row_id` field defined in the Iceberg spec.
+      // This ensures that Iceberg can recognize and track the same column for row lineage purposes.
+      if (shouldSetIcebergReservedFieldId) {
+        metadataBuilder.putLong(
+          PARQUET_FIELD_ID_METADATA_KEY,
+          IcebergConstants.ICEBERG_ROW_TRACKING_ROW_ID_FIELD_ID
+        )
+      }
+      metadataBuilder.build()
+    }
 
-    def apply(materializedColumnName: String, nullable: Boolean = false): StructField =
+    def apply(
+         materializedColumnName: String,
+         nullable: Boolean = false,
+         shouldSetIcebergReservedFieldId: Boolean): StructField =
       StructField(
         RowId.ROW_ID,
         LongType,
         // The Row ID field is used to read the materialized Row ID value which is nullable. The
         // actual Row ID expression is created using a projection injected before the optimizer pass
         // by the [[GenerateRowIDs] rule at which point the Row ID field is non-nullable.
         nullable,
-        metadata = metadata(materializedColumnName))
+        metadata = metadata(materializedColumnName, shouldSetIcebergReservedFieldId))
 
     def unapply(field: StructField): Option[StructField] =
       if (isRowIdColumn(field)) Some(field) else None
@@ -241,8 +264,14 @@ object RowId {
 
   object RowIdMetadataAttribute {
     /** Creates an attribute for writing out the materialized column name */
-    def apply(materializedColumnName: String): AttributeReference =
-      DataTypeUtils.toAttribute(RowIdMetadataStructField(materializedColumnName))
+    def apply(
+        materializedColumnName: String,
+        shouldSetIcebergReservedFieldId: Boolean): AttributeReference =
+      DataTypeUtils
+        .toAttribute(
+          RowIdMetadataStructField(
+            materializedColumnName,
+            shouldSetIcebergReservedFieldId = shouldSetIcebergReservedFieldId))
         .withName(materializedColumnName)
 
     def unapply(attr: Attribute): Option[Attribute] =
@@ -302,7 +331,10 @@ object RowId {
       snapshot.protocol, snapshot.metadata, snapshot.deltaLog.tableId)
 
     val rowIdColumn = DeltaTableUtils.getFileMetadataColumn(dataFrame).getField(ROW_ID)
-    preserveRowIdsUnsafe(dataFrame, materializedColumnName, rowIdColumn)
+    val shouldSetIcebergReservedFieldId = IcebergCompat.isGeqEnabled(snapshot.metadata, 3)
+
+    preserveRowIdsUnsafe(
+      dataFrame, materializedColumnName, rowIdColumn, shouldSetIcebergReservedFieldId)
   }
 
   /**
@@ -314,9 +346,12 @@ object RowId {
   private[delta] def preserveRowIdsUnsafe(
       dataFrame: DataFrame,
       materializedColumnName: String,
-      rowIdColumn: Column): DataFrame = {
+      rowIdColumn: Column,
+      shouldSetIcebergReservedFieldId: Boolean): DataFrame = {
     dataFrame
       .withColumn(materializedColumnName, rowIdColumn)
-      .withMetadata(materializedColumnName, columnMetadata(materializedColumnName))
+      .withMetadata(
+        materializedColumnName,
+        columnMetadata(materializedColumnName, shouldSetIcebergReservedFieldId))
   }
 }

spark/src/main/scala/org/apache/spark/sql/delta/RowTracking.scala

@@ -74,11 +74,16 @@ object RowTracking {
       metadata: Metadata,
       nullableConstantFields: Boolean,
       nullableGeneratedFields: Boolean): Iterable[StructField] = {
-    RowId.createRowIdField(protocol, metadata, nullableGeneratedFields) ++
+    val needSetRowTrackingFieldIdForUniform =
+      IcebergCompat.isGeqEnabled(metadata, requiredVersion = 3)
+
+    RowId.createRowIdField(
+      protocol, metadata, nullableGeneratedFields, needSetRowTrackingFieldIdForUniform) ++
       RowId.createBaseRowIdField(protocol, metadata, nullableConstantFields) ++
       DefaultRowCommitVersion.createDefaultRowCommitVersionField(
         protocol, metadata, nullableConstantFields) ++
-      RowCommitVersion.createMetadataStructField(protocol, metadata, nullableGeneratedFields)
+      RowCommitVersion.createMetadataStructField(
+        protocol, metadata, nullableGeneratedFields, needSetRowTrackingFieldIdForUniform)
   }
 
   /**

spark/src/main/scala/org/apache/spark/sql/delta/UniversalFormat.scala

@@ -338,6 +338,12 @@ object IcebergConstants {
   val ICEBERG_TBLPROP_METADATA_LOCATION = "metadata_location"
   val ICEBERG_PROVIDER = "iceberg"
   val ICEBERG_NAME_MAPPING_PROPERTY = "schema.name-mapping.default"
+
+  // Reserved field ID for the `_row_id` column
+  // Iceberg spec: https://iceberg.apache.org/spec/?h=row#reserved-field-ids
+  val ICEBERG_ROW_TRACKING_ROW_ID_FIELD_ID = 2147483540L
+  // Reserved field ID for the `_last_updated_sequence_number` column
+  val ICEBERG_ROW_TRACKING_LAST_UPDATED_SEQUENCE_NUMBER_FIELD_ID = 2147483539L
 }
 
 object HudiConstants {

spark/src/main/scala/org/apache/spark/sql/delta/commands/merge/ClassicMergeExecutor.scala

@@ -432,14 +432,16 @@ trait ClassicMergeExecutor extends MergeOutputGeneration {
         (if (cdcEnabled) Seq(CDC_TYPE_NOT_CDC) else Seq())
 
     // Generate output columns.
+    val needSetRowTrackingFieldIdForUniform = IcebergCompat.isGeqEnabled(deltaTxn.metadata, 3)
     val outputCols = generateWriteAllChangesOutputCols(
       targetWriteCols,
       rowIdColumnExpressionOpt,
       rowCommitVersionColumnExpressionOpt,
       outputColNames,
       noopCopyExprs,
       clausesWithPrecompConditions,
-      cdcEnabled
+      cdcEnabled,
+      needSetRowTrackingFieldIdForUniform = needSetRowTrackingFieldIdForUniform
     )
 
     val preOutputDF = if (cdcEnabled) {
@@ -450,7 +452,9 @@ trait ClassicMergeExecutor extends MergeOutputGeneration {
           noopCopyExprs,
           rowIdColumnExpressionOpt.map(_.name),
           rowCommitVersionColumnExpressionOpt.map(_.name),
-          deduplicateCDFDeletes)
+          deduplicateCDFDeletes,
+          needSetRowTrackingFieldIdForUniform = needSetRowTrackingFieldIdForUniform
+      )
     } else {
       // change data capture is off, just output the normal data
       joinedAndPrecomputedConditionsDF