[VARIANT] Add enableVariantShredding Table Property and VariantShredding-preview table feature in Delta-Spark (#4521)

<!--
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

Add the preview table feature for Variant Shredding (see
#4033) enabled by the new
enableVariantShredding table property. Spark will check if the
`enableVariantShredding` table property is enabled before writing
shredded data to Delta tables, when support for shredded writes is
implemented in Spark.

## How was this patch tested?

Unit test

## 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'.
-->
No

Author: harshmotw-db

spark/src/main/resources/error/delta-error-classes.json

@@ -2317,6 +2317,12 @@
     ],
     "sqlState" : "42809"
   },
+  "DELTA_SHREDDING_TABLE_PROPERTY_DISABLED" : {
+    "message" : [
+      "Attempted to write shredded Variants but the table does not support shredded writes. Consider setting the table property enableVariantShredding to true."
+    ],
+    "sqlState" : "0A000"
+  },
   "DELTA_SOURCE_IGNORE_DELETE" : {
     "message" : [
       "Detected deleted data (for example <removedFile>) from streaming source at version <version>. This is currently not supported. If you'd like to ignore deletes, set the option 'ignoreDeletes' to 'true'. The source table can be found at path <dataPath>."

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

@@ -549,6 +549,13 @@ trait DeltaConfigsBase extends DeltaLogging {
     validationFunction = _ => true,
     helpMessage = "needs to be a boolean.")
 
+  val ENABLE_VARIANT_SHREDDING = buildConfig[Boolean](
+    key = "enableVariantShredding",
+    defaultValue = "false",
+    fromString = _.toBoolean,
+    validationFunction = _ => true,
+    helpMessage = "needs to be a boolean.")
+
   /**
    * Whether this table will automatically optimize the layout of files during writes.
    */

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

@@ -2827,6 +2827,13 @@ trait DeltaErrorsBase
     )
   }
 
+  def variantShreddingUnsupported(): Throwable = {
+    new DeltaSparkException(
+      errorClass = "DELTA_SHREDDING_TABLE_PROPERTY_DISABLED",
+      messageParameters = Array.empty
+    )
+  }
+
   def unsupportSubqueryInPartitionPredicates(): Throwable = {
     new DeltaAnalysisException(
       errorClass = "DELTA_UNSUPPORTED_SUBQUERY_IN_PARTITION_PREDICATES",

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

@@ -61,6 +61,7 @@ import org.apache.spark.sql.catalyst.expressions._
 import org.apache.spark.sql.catalyst.plans.logical.UnsetTableProperties
 import org.apache.spark.sql.catalyst.types.DataTypeUtils.toAttributes
 import org.apache.spark.sql.catalyst.util.{CharVarcharUtils, ResolveDefaultColumns}
+import org.apache.spark.sql.internal.SQLConf
 import org.apache.spark.sql.types.{StructField, StructType}
 import org.apache.spark.util.{Clock, Utils}
 
@@ -964,6 +965,18 @@ trait OptimisticTransactionImpl extends DeltaTransaction
     }
   }
 
+  // Make sure shredded writes are only performed if the shredding table property was set.
+  private def assertShreddingStateConsistent() = {
+    if (!DeltaConfigs.ENABLE_VARIANT_SHREDDING.fromMetaData(metadata)) {
+      val isVariantShreddingSchemaForced =
+        spark.sessionState.conf
+          .getConfString("spark.sql.variant.forceShreddingSchemaForTest", "").nonEmpty
+      if (isVariantShreddingSchemaForced) {
+        throw DeltaErrors.variantShreddingUnsupported()
+      }
+    }
+  }
+
   /**
    * Must make sure that deletion vectors are never added to a table where that isn't allowed.
    * Note, statistics recomputation is still allowed even though DVs might be currently disabled.
@@ -2176,6 +2189,9 @@ trait OptimisticTransactionImpl extends DeltaTransaction
     val assertDeletionVectorWellFormed = getAssertDeletionVectorWellFormedFunc(spark, op)
     actions.foreach(assertDeletionVectorWellFormed)
 
+    // Make sure shredded writes are only performed if the shredding table property was set
+    assertShreddingStateConsistent()
+
     // Make sure this operation does not include default column values if the corresponding table
     // feature is not enabled.
     if (!protocol.isFeatureSupported(AllowColumnDefaultsTableFeature)) {

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

@@ -370,6 +370,7 @@ object TableFeature {
       InCommitTimestampTableFeature,
       VariantTypePreviewTableFeature,
       VariantTypeTableFeature,
+      VariantShreddingPreviewTableFeature,
       CatalogOwnedTableFeature,
       CoordinatedCommitsTableFeature,
       CheckpointProtectionTableFeature)
@@ -713,6 +714,17 @@ object VariantTypeTableFeature extends ReaderWriterFeature(name = "variantType")
   }
 }
 
+object VariantShreddingPreviewTableFeature
+    extends ReaderWriterFeature(name = "variantShredding-preview")
+    with FeatureAutomaticallyEnabledByMetadata {
+  override def automaticallyUpdateProtocolOfExistingTables: Boolean = true
+
+  override def metadataRequiresFeatureToBeEnabled(
+      protocol: Protocol, metadata: Metadata, spark: SparkSession): Boolean = {
+    DeltaConfigs.ENABLE_VARIANT_SHREDDING.fromMetaData(metadata)
+  }
+}
+
 object DeletionVectorsTableFeature
   extends ReaderWriterFeature(name = "deletionVectors")
   with RemovableFeature

spark/src/test/scala-spark-master/org/apache/spark/sql/delta/DeltaVariantShreddingSuite.scala

@@ -0,0 +1,218 @@
+/*
+ * Copyright (2025) The Delta Lake Project Authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.spark.sql.delta
+
+import scala.collection.JavaConverters._
+
+import org.apache.hadoop.conf.Configuration
+import org.apache.hadoop.fs.Path
+
+import org.apache.spark.SparkException
+import org.apache.spark.sql.{QueryTest, Row}
+import org.apache.spark.sql.catalyst.TableIdentifier
+import org.apache.spark.sql.delta.actions.AddFile
+import org.apache.spark.sql.delta.test.{DeltaSQLCommandTest, DeltaSQLTestUtils, TestsStatistics}
+import org.apache.spark.sql.internal.SQLConf
+import org.apache.spark.sql.test.SharedSparkSession
+
+import org.apache.parquet.hadoop.ParquetFileReader
+import org.apache.parquet.hadoop.metadata.ParquetMetadata
+import org.apache.parquet.schema.{GroupType, MessageType, Type}
+
+class DeltaVariantShreddingSuite
+  extends QueryTest
+    with SharedSparkSession
+    with DeltaSQLCommandTest
+    with DeltaSQLTestUtils
+    with TestsStatistics {
+
+  import testImplicits._
+
+  private def numShreddedFiles(path: String, validation: GroupType => Boolean = _ => true): Int = {
+    def listParquetFilesRecursively(dir: String): Seq[String] = {
+      val deltaLog = DeltaLog.forTable(spark, dir)
+      val files = deltaLog.snapshot.allFiles
+      files.collect().map { file: AddFile =>
+        file.absolutePath(deltaLog).toString
+      }
+    }
+
+    val parquetFiles = listParquetFilesRecursively(path)
+
+    def hasStructWithFieldNamesInternal(schema: List[Type], fieldNames: Set[String]): Boolean = {
+      schema.exists {
+        case group: GroupType if group.getFields.asScala.map(_.getName).toSet == fieldNames =>
+          true
+        case group: GroupType =>
+          hasStructWithFieldNamesInternal(group.getFields.asScala.toList, fieldNames)
+        case _ => false
+      }
+    }
+
+    def hasStructWithFieldNames(schema: MessageType, fieldNames: Set[String]): Boolean = {
+      schema.getFields.asScala.exists {
+        case group: GroupType if group.getFields.asScala.map(_.getName).toSet == fieldNames &&
+          validation(group) =>
+          true
+        case group: GroupType =>
+          hasStructWithFieldNamesInternal(group.getFields.asScala.toList, fieldNames)
+        case _ => false
+      }
+    }
+
+    val requiredFieldNames = Set("value", "metadata", "typed_value")
+    val conf = new Configuration()
+    parquetFiles.count { p =>
+      val reader = ParquetFileReader.open(conf, new Path(p))
+      val footer: ParquetMetadata = reader.getFooter
+      val isShredded =
+        hasStructWithFieldNames(footer.getFileMetaData().getSchema, requiredFieldNames)
+      reader.close()
+      isShredded
+    }
+  }
+
+  test("variant shredding table property") {
+    withTable("tbl") {
+      sql("CREATE TABLE tbl(s STRING, i INTEGER) USING DELTA")
+      val (deltaLog, snapshot) = DeltaLog.forTableWithSnapshot(spark, TableIdentifier("tbl"))
+      assert(!snapshot.protocol
+        .isFeatureSupported(VariantShreddingPreviewTableFeature),
+        s"Table tbl contains ShreddedVariantTableFeature descriptor when its not supposed to"
+      )
+      sql(s"ALTER TABLE tbl " +
+        s"SET TBLPROPERTIES('${DeltaConfigs.ENABLE_VARIANT_SHREDDING.key}' = 'true')")
+      assert(getProtocolForTable("tbl")
+        .readerAndWriterFeatures.contains(VariantShreddingPreviewTableFeature))
+    }
+    withTable("tbl") {
+      sql(s"CREATE TABLE tbl(s STRING, i INTEGER) USING DELTA " +
+        s"TBLPROPERTIES('${DeltaConfigs.ENABLE_VARIANT_SHREDDING.key}' = 'true')")
+      assert(getProtocolForTable("tbl")
+        .readerAndWriterFeatures.contains(VariantShreddingPreviewTableFeature))
+    }
+    assert(DeltaConfigs.ENABLE_VARIANT_SHREDDING.key == "delta.enableVariantShredding")
+  }
+
+  test("Spark can read shredded table containing the shredding table feature") {
+    withTable("tbl") {
+      withTempDir { dir =>
+        val schema = "a int, b string, c decimal(15, 1)"
+        val df = spark.sql(
+          """
+            | select id i, case
+            | when id = 0 then parse_json('{"a": 1, "b": "2", "c": 3.3, "d": 4.4}')
+            | when id = 1 then parse_json('{"a": [1,2,3], "b": "hello", "c": {"x": 0}}')
+            | when id = 2 then parse_json('{"A": 1, "c": 1.23}')
+            | end v from range(0, 3, 1, 1)
+            |""".stripMargin)
+
+        sql("CREATE TABLE tbl (i long, v variant) USING DELTA " +
+          s"TBLPROPERTIES ('${DeltaConfigs.ENABLE_VARIANT_SHREDDING.key}' = 'true') " +
+          s"LOCATION '${dir.getAbsolutePath}'")
+        assert(getProtocolForTable("tbl")
+          .readerAndWriterFeatures.contains(VariantShreddingPreviewTableFeature))
+        withSQLConf(SQLConf.VARIANT_WRITE_SHREDDING_ENABLED.key -> true.toString,
+          SQLConf.VARIANT_ALLOW_READING_SHREDDED.key -> true.toString,
+          SQLConf.VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST.key -> schema) {
+
+          df.write.format("delta").mode("append").saveAsTable("tbl")
+          // Make sure the actual parquet files are shredded
+          assert(numShreddedFiles(dir.getAbsolutePath, validation = { field: GroupType =>
+            field.getName == "v" && (field.getType("typed_value") match {
+              case t: GroupType =>
+                t.getFields.asScala.map(_.getName).toSet == Set("a", "b", "c")
+              case _ => false
+            })
+          }) == 1)
+          checkAnswer(
+            spark.read.format("delta").load(dir.getAbsolutePath).selectExpr("i", "to_json(v)"),
+            df.selectExpr("i", "to_json(v)").collect()
+          )
+        }
+      }
+    }
+  }
+
+  test("Test shredding property controls shredded writes") {
+    val schema = "a int, b string, c decimal(15, 1)"
+    val df = spark.sql(
+      """
+        | select id i, case
+        | when id = 0 then parse_json('{"a": 1, "b": "2", "c": 3.3, "d": 4.4}')
+        | when id = 1 then parse_json('{"a": [1,2,3], "b": "hello", "c": {"x": 0}}')
+        | when id = 2 then parse_json('{"A": 1, "c": 1.23}')
+        | end v from range(0, 3, 1, 1)
+        |""".stripMargin)
+    // Table property not present or false
+    Seq("", s"TBLPROPERTIES ('${DeltaConfigs.ENABLE_VARIANT_SHREDDING.key}' = 'false') ")
+      .foreach { tblProperties =>
+      withTable("tbl") {
+        withTempDir { dir =>
+          sql("CREATE TABLE tbl (i long, v variant) USING DELTA " + tblProperties +
+            s"LOCATION '${dir.getAbsolutePath}'")
+          withSQLConf(SQLConf.VARIANT_WRITE_SHREDDING_ENABLED.key -> true.toString,
+            SQLConf.VARIANT_ALLOW_READING_SHREDDED.key -> true.toString,
+            SQLConf.VARIANT_FORCE_SHREDDING_SCHEMA_FOR_TEST.key -> schema) {
+
+            val e = intercept[DeltaSparkException] {
+              df.write.format("delta").mode("append").saveAsTable("tbl")
+            }
+            checkError(e, "DELTA_SHREDDING_TABLE_PROPERTY_DISABLED", parameters = Map())
+            assert(e.getMessage.contains(
+              "Attempted to write shredded Variants but the table does not support shredded " +
+                "writes. Consider setting the table property enableVariantShredding to true."))
+            assert(numShreddedFiles(dir.getAbsolutePath, validation = { field: GroupType =>
+              field.getName == "v" && (field.getType("typed_value") match {
+                case t: GroupType =>
+                  t.getFields.asScala.map(_.getName).toSet == Set("a", "b", "c")
+                case _ => false
+              })
+            }) == 0)
+            checkAnswer(
+              spark.read.format("delta").load(dir.getAbsolutePath).selectExpr("i", "to_json(v)"),
+              Seq()
+            )
+          }
+        }
+      }
+    }
+  }
+
+  test("Set table property to invalid value") {
+    withTable("tbl") {
+      sql("CREATE TABLE tbl(s STRING, i INTEGER) USING DELTA")
+      val (deltaLog, snapshot) = DeltaLog.forTableWithSnapshot(spark, TableIdentifier("tbl"))
+      assert(!snapshot.protocol
+        .isFeatureSupported(VariantShreddingPreviewTableFeature),
+        s"Table tbl contains ShreddedVariantTableFeature descriptor when its not supposed to"
+      )
+      checkError(
+        intercept[SparkException] {
+          sql(s"ALTER TABLE tbl " +
+            s"SET TBLPROPERTIES('${DeltaConfigs.ENABLE_VARIANT_SHREDDING.key}' = 'bla')")
+        },
+        "_LEGACY_ERROR_TEMP_2045",
+        parameters = Map(
+          "message" -> "For input string: \"bla\""
+        )
+      )
+      assert(!getProtocolForTable("tbl")
+        .readerAndWriterFeatures.contains(VariantShreddingPreviewTableFeature))
+    }
+  }
+}

spark/src/test/scala-spark-master/org/apache/spark/sql/delta/DeltaVariantSuite.scala

@@ -1,5 +1,5 @@
 /*
- * Copyright (2021) The Delta Lake Project Authors.
+ * Copyright (2025) The Delta Lake Project Authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.