[SPARK-56207][SQL] Replace legacy error codes with named errors in DSv2 connector API

### What changes were proposed in this pull request?

  Replaced 18 _LEGACY_ERROR_TEMP_* error codes in the Data Source V2 (DSv2) connector API with properly named, descriptive error conditions. The affected interfaces are all in
  sql/catalyst/src/main/java/org/apache/spark/sql/connector/:

  - Read: Scan, PartitionReaderFactory, ContinuousPartitionReaderFactory
  - Write: Write, WriteBuilder, DeltaWrite, DeltaWriteBuilder, LogicalWriteInfo
  - Catalog: SupportsPartitionManagement, SupportsAtomicPartitionManagement
  - Util: V2ExpressionSQLBuilder

  New error names follow established Spark conventions (DATASOURCE_*, PARTITION_*, V2_EXPRESSION_SQL_BUILDER_*, UNEXPECTED_*) and are inserted alphabetically into error-conditions.json. All new entries
  include a sqlState (0A000 for unsupported operations, 42000 for illegal arguments) and messages ending with a period.

### Why are the changes needed?
  Legacy error codes (_LEGACY_ERROR_TEMP_*) are opaque and hard to search, cross-reference, or document. Named error codes make it easier for users and downstream connectors to identify and handle specific
  error conditions.

### Does this PR introduce _any_ user-facing change?
  Yes — error messages now include a sqlState and names are surfaced in error output, but the message text is preserved (with minor normalization: trailing periods added for consistency).

### How was this patch tested?
  Existing unit and integration tests cover these code paths. No behavioral changes were made.

### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude Code

Closes #54971 from dbtsai/sqlState.

Authored-by: DB Tsai <dbtsai@dbtsai.com>
Signed-off-by: Liang-Chi Hsieh <viirya@gmail.com>

Author: dbtsai

common/utils/src/main/resources/error/error-conditions.json

@@ -1773,12 +1773,66 @@
     ],
     "sqlState" : "42710"
   },
+  "DATA_SOURCE_BATCH_SCAN_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Batch scan is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_BATCH_WRITE_BUILDER_NOT_SUPPORTED" : {
+    "message" : [
+      "<class> does not support batch write."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_BATCH_WRITE_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Batch write is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_COLUMNAR_READER_NOT_SUPPORTED" : {
+    "message" : [
+      "<class> cannot create columnar reader."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_CONTINUOUS_SCAN_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Continuous scan is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_DELTA_BATCH_WRITE_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Delta batch write is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_DELTA_WRITE_BUILD_NOT_IMPLEMENTED" : {
+    "message" : [
+      "<class> does not implement build."
+    ],
+    "sqlState" : "0A000"
+  },
   "DATA_SOURCE_EXTERNAL_ERROR" : {
     "message" : [
       "Encountered error when saving to external data source."
     ],
     "sqlState" : "KD010"
   },
+  "DATA_SOURCE_METADATA_SCHEMA_NOT_IMPLEMENTED" : {
+    "message" : [
+      "<class> does not implement metadataSchema."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_MICRO_BATCH_SCAN_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Micro-batch scan is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
   "DATA_SOURCE_NOT_EXIST" : {
     "message" : [
       "Data source '<provider>' not found. Please make sure the data source is registered."
@@ -1791,6 +1845,24 @@
     ],
     "sqlState" : "42K02"
   },
+  "DATA_SOURCE_ROW_ID_SCHEMA_NOT_IMPLEMENTED" : {
+    "message" : [
+      "<class> does not implement rowIdSchema."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_STREAMING_WRITE_BUILD_NOT_SUPPORTED" : {
+    "message" : [
+      "<class> does not support streaming write."
+    ],
+    "sqlState" : "0A000"
+  },
+  "DATA_SOURCE_STREAMING_WRITE_NOT_SUPPORTED" : {
+    "message" : [
+      "<description>: Streaming write is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
   "DATA_SOURCE_TABLE_SCHEMA_MISMATCH" : {
     "message" : [
       "The schema of the data source table does not match the expected schema. If you are using the DataFrameReader.schema API or creating a table, avoid specifying the schema.",
@@ -5619,6 +5691,12 @@
     ],
     "sqlState" : "42000"
   },
+  "PARTITION_RENAME_NOT_SUPPORTED" : {
+    "message" : [
+      "Partition renaming is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
   "PARTITION_TRANSFORM_EXPRESSION_NOT_IN_PARTITIONED_BY" : {
     "message" : [
       "The expression <expression> must be inside 'partitionedBy'."
@@ -6952,6 +7030,18 @@
     ],
     "sqlState" : "42K09"
   },
+  "TRUNCATE_PARTITIONS_NOT_SUPPORTED" : {
+    "message" : [
+      "Truncating partitions is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
+  "TRUNCATE_PARTITION_NOT_SUPPORTED" : {
+    "message" : [
+      "Truncating partition is not supported."
+    ],
+    "sqlState" : "0A000"
+  },
   "TUPLE_INVALID_INPUT_SKETCH_BUFFER" : {
     "message" : [
       "Invalid call to <function>; only valid Tuple sketch buffers are supported as inputs (such as those produced by the corresponding `tuple_sketch_agg_*` function)."
@@ -7082,6 +7172,12 @@
     ],
     "sqlState" : "XX000"
   },
+  "UNEXPECTED_V2_EXPRESSION" : {
+    "message" : [
+      "Unexpected V2 expression: <expr>."
+    ],
+    "sqlState" : "XX000"
+  },
   "UNION_NOT_SUPPORTED_IN_RECURSIVE_CTE" : {
     "message" : [
       "The UNION operator is not yet supported within recursive common table expressions (WITH clauses that refer to themselves, directly or indirectly). Please use UNION ALL instead."
@@ -8314,6 +8410,18 @@
     ],
     "sqlState" : "42000"
   },
+  "V2_EXPRESSION_SQL_BUILDER_UDAF_NOT_SUPPORTED" : {
+    "message" : [
+      "<class> does not support user defined aggregate function: <funcName>."
+    ],
+    "sqlState" : "0A000"
+  },
+  "V2_EXPRESSION_SQL_BUILDER_UDF_NOT_SUPPORTED" : {
+    "message" : [
+      "<class> does not support user defined function: <funcName>."
+    ],
+    "sqlState" : "0A000"
+  },
   "VARIABLE_ALREADY_EXISTS" : {
     "message" : [
       "Cannot create the variable <variableName> because it already exists.",
@@ -10787,91 +10895,6 @@
       "CaseInsensitiveStringMap is read-only."
     ]
   },
-  "_LEGACY_ERROR_TEMP_3133" : {
-    "message" : [
-      "<class> does not implement rowIdSchema"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3134" : {
-    "message" : [
-      "<class> does not implement metadataSchema"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3135" : {
-    "message" : [
-      "<class> does not support batch write"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3136" : {
-    "message" : [
-      "<class> does not support streaming write"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3137" : {
-    "message" : [
-      "<description>: Batch write is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3138" : {
-    "message" : [
-      "<description>: Streaming write is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3139" : {
-    "message" : [
-      "<description>: Delta batch write is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3140" : {
-    "message" : [
-      "<class> does not implement build"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3141" : {
-    "message" : [
-      "<class> does not support user defined function: <funcName>"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3142" : {
-    "message" : [
-      "<class> does not support user defined aggregate function: <funcName>"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3143" : {
-    "message" : [
-      "Partition renaming is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3144" : {
-    "message" : [
-      "Partition truncate is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3145" : {
-    "message" : [
-      "Partitions truncate is not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3147" : {
-    "message" : [
-      "<description>: Batch scan are not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3148" : {
-    "message" : [
-      "<description>: Micro-batch scan are not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3149" : {
-    "message" : [
-      "<description>: Continuous scan are not supported"
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_3150" : {
-    "message" : [
-      "Cannot create columnar reader."
-    ]
-  },
   "_LEGACY_ERROR_TEMP_3152" : {
     "message" : [
       "Datatype not supported <dataType>"
@@ -11077,11 +11100,6 @@
       "<value> is not a boolean string."
     ]
   },
-  "_LEGACY_ERROR_TEMP_3207" : {
-    "message" : [
-      "Unexpected V2 expression: <expr>"
-    ]
-  },
   "_LEGACY_ERROR_TEMP_3208" : {
     "message" : [
       "The number of fields (<numFields>) in the partition identifier is not equal to the partition schema length (<schemaLen>). The identifier might not refer to one partition."

sql/catalyst/src/main/java/org/apache/spark/sql/connector/catalog/SupportsAtomicPartitionManagement.java

@@ -127,6 +127,6 @@ default boolean purgePartitions(InternalRow[] idents)
    */
   default boolean truncatePartitions(InternalRow[] idents)
       throws NoSuchPartitionException, SparkUnsupportedOperationException {
-    throw new SparkUnsupportedOperationException("_LEGACY_ERROR_TEMP_3145");
+    throw new SparkUnsupportedOperationException("TRUNCATE_PARTITIONS_NOT_SUPPORTED");
   }
 }

sql/catalyst/src/main/java/org/apache/spark/sql/connector/catalog/SupportsPartitionManagement.java

@@ -157,7 +157,7 @@ default boolean renamePartition(InternalRow from, InternalRow to)
         throws SparkUnsupportedOperationException,
                PartitionsAlreadyExistException,
                NoSuchPartitionException {
-      throw new SparkUnsupportedOperationException("_LEGACY_ERROR_TEMP_3143");
+      throw new SparkUnsupportedOperationException("PARTITION_RENAME_NOT_SUPPORTED");
     }
 
     /**
@@ -172,6 +172,6 @@ default boolean renamePartition(InternalRow from, InternalRow to)
      */
     default boolean truncatePartition(InternalRow ident)
         throws NoSuchPartitionException, SparkUnsupportedOperationException {
-      throw new SparkUnsupportedOperationException("_LEGACY_ERROR_TEMP_3144");
+      throw new SparkUnsupportedOperationException("TRUNCATE_PARTITION_NOT_SUPPORTED");
     }
 }

sql/catalyst/src/main/java/org/apache/spark/sql/connector/read/PartitionReaderFactory.java

@@ -18,6 +18,7 @@
 package org.apache.spark.sql.connector.read;
 
 import java.io.Serializable;
+import java.util.Map;
 
 import org.apache.spark.SparkUnsupportedOperationException;
 import org.apache.spark.annotation.Evolving;
@@ -51,7 +52,8 @@ public interface PartitionReaderFactory extends Serializable {
    * {@link InputPartition} class defined for the data source.
    */
   default PartitionReader<ColumnarBatch> createColumnarReader(InputPartition partition) {
-    throw new SparkUnsupportedOperationException("_LEGACY_ERROR_TEMP_3150");
+    throw new SparkUnsupportedOperationException(
+      "DATA_SOURCE_COLUMNAR_READER_NOT_SUPPORTED", Map.of("class", getClass().getName()));
   }
 
   /**

sql/catalyst/src/main/java/org/apache/spark/sql/connector/read/Scan.java

@@ -78,7 +78,7 @@ default String description() {
    */
   default Batch toBatch() {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3147", Map.of("description", description()));
+      "DATA_SOURCE_BATCH_SCAN_NOT_SUPPORTED", Map.of("description", description()));
   }
 
   /**
@@ -95,7 +95,7 @@ default Batch toBatch() {
    */
   default MicroBatchStream toMicroBatchStream(String checkpointLocation) {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3148", Map.of("description", description()));
+      "DATA_SOURCE_MICRO_BATCH_SCAN_NOT_SUPPORTED", Map.of("description", description()));
   }
 
   /**
@@ -112,7 +112,7 @@ default MicroBatchStream toMicroBatchStream(String checkpointLocation) {
    */
   default ContinuousStream toContinuousStream(String checkpointLocation) {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3149", Map.of("description", description()));
+      "DATA_SOURCE_CONTINUOUS_SCAN_NOT_SUPPORTED", Map.of("description", description()));
   }
 
   /**

sql/catalyst/src/main/java/org/apache/spark/sql/connector/read/streaming/ContinuousPartitionReaderFactory.java

@@ -17,6 +17,8 @@
 
 package org.apache.spark.sql.connector.read.streaming;
 
+import java.util.Map;
+
 import org.apache.spark.SparkUnsupportedOperationException;
 import org.apache.spark.annotation.Evolving;
 import org.apache.spark.sql.catalyst.InternalRow;
@@ -38,6 +40,7 @@ public interface ContinuousPartitionReaderFactory extends PartitionReaderFactory
 
   @Override
   default ContinuousPartitionReader<ColumnarBatch> createColumnarReader(InputPartition partition) {
-    throw new SparkUnsupportedOperationException("_LEGACY_ERROR_TEMP_3150");
+    throw new SparkUnsupportedOperationException(
+      "DATA_SOURCE_COLUMNAR_READER_NOT_SUPPORTED", Map.of("class", getClass().getName()));
   }
 }

sql/catalyst/src/main/java/org/apache/spark/sql/connector/util/V2ExpressionSQLBuilder.java

@@ -319,20 +319,20 @@ protected String visitInverseDistributionFunction(
   protected String visitUserDefinedScalarFunction(
       String funcName, String canonicalName, String[] inputs) {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3141",
-      Map.of("class", this.getClass().getSimpleName(), "funcName", funcName));
+      "V2_EXPRESSION_SQL_BUILDER_UDF_NOT_SUPPORTED",
+      Map.of("class", this.getClass().getName(), "funcName", funcName));
   }
 
   protected String visitUserDefinedAggregateFunction(
       String funcName, String canonicalName, boolean isDistinct, String[] inputs) {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3142",
-      Map.of("class", this.getClass().getSimpleName(), "funcName", funcName));
+      "V2_EXPRESSION_SQL_BUILDER_UDAF_NOT_SUPPORTED",
+      Map.of("class", this.getClass().getName(), "funcName", funcName));
   }
 
   protected String visitUnexpectedExpr(Expression expr) throws IllegalArgumentException {
     throw new SparkIllegalArgumentException(
-      "_LEGACY_ERROR_TEMP_3207", Map.of("expr", String.valueOf(expr)));
+      "UNEXPECTED_V2_EXPRESSION", Map.of("expr", String.valueOf(expr)));
   }
 
   protected String visitPartitionPredicate(PartitionPredicate partitionPredicate) {

sql/catalyst/src/main/java/org/apache/spark/sql/connector/write/DeltaWrite.java

@@ -32,6 +32,6 @@ public interface DeltaWrite extends Write {
   @Override
   default DeltaBatchWrite toBatch() {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3139", Map.of("description", description()));
+      "DATA_SOURCE_DELTA_BATCH_WRITE_NOT_SUPPORTED", Map.of("description", description()));
   }
 }

sql/catalyst/src/main/java/org/apache/spark/sql/connector/write/DeltaWriteBuilder.java

@@ -32,6 +32,6 @@ public interface DeltaWriteBuilder extends WriteBuilder {
   @Override
   default DeltaWrite build() {
     throw new SparkUnsupportedOperationException(
-      "_LEGACY_ERROR_TEMP_3140", Map.of("class", getClass().getName()));
+      "DATA_SOURCE_DELTA_WRITE_BUILD_NOT_IMPLEMENTED", Map.of("class", getClass().getName()));
   }
 }