[SPARK-54501][SQL] Improve error handling for Hive metastore partition filter failures

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

This PR refactors the error handling for Hive metastore partition filter failures by migrating from the legacy error code _LEGACY_ERROR_TEMP_2193 to a properly defined error condition INTERNAL_ERROR_HIVE_METASTORE_PARTITION_FILTER with SQL state 58030. The error message is restructured to include the underlying exception details.

### Why are the changes needed?

The previous error message was verbose and lacked important diagnostic information. The legacy error code needed to be migrated to a proper error condition with an appropriate SQL state for better error categorization.

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

Yes. Users will see an improved error message that includes the actual exception details and clearer guidance.

### How was this patch tested?

Updated existing unit tests in HivePartitionFilteringSuite and ExternalCatalogSuite to verify the new error condition.

### Was this patch authored or co-authored using generative AI tooling?

Generated-by: Claude Sonnet 4.5

Closes #53212 from ganeshashree/SPARK-54501.

Authored-by: Ganesha S <[email protected]>
Signed-off-by: Wenchen Fan <[email protected]>

Author: ganeshas-db

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

@@ -2436,6 +2436,14 @@
     ],
     "sqlState" : "XX000"
   },
+  "INTERNAL_ERROR_HIVE_METASTORE_PARTITION_FILTER" : {
+    "message" : [
+      "Failed to get partition metadata by filter from Hive metastore.",
+      "To work around this issue, set '<hiveMetastorePartitionPruningFallbackOnException>' to true. Note that this may result in degraded performance as Spark will fetch all partition metadata instead of filtering at the metastore level.",
+      "To report this issue, visit: https://issues.apache.org/jira/browse/SPARK"
+    ],
+    "sqlState" : "XX000"
+  },
   "INTERNAL_ERROR_MEMORY" : {
     "message" : [
       "<message>"
@@ -9028,11 +9036,6 @@
       "Partition filter cannot have both `\"` and `'` characters."
     ]
   },
-  "_LEGACY_ERROR_TEMP_2193" : {
-    "message" : [
-      "Caught Hive MetaException attempting to get partition metadata by filter from Hive. You can set the Spark configuration setting <hiveMetastorePartitionPruningFallbackOnException> to true to work around this problem, however this will result in degraded performance. Please report a bug: https://issues.apache.org/jira/browse/SPARK."
-    ]
-  },
   "_LEGACY_ERROR_TEMP_2194" : {
     "message" : [
       "Unsupported Hive Metastore version <version>. Please set <key> with a valid version."

sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryExecutionErrors.scala

@@ -1667,7 +1667,7 @@ private[sql] object QueryExecutionErrors extends QueryErrorsBase with ExecutionE
 
   def getPartitionMetadataByFilterError(e: Exception): SparkRuntimeException = {
     new SparkRuntimeException(
-      errorClass = "_LEGACY_ERROR_TEMP_2193",
+      errorClass = "INTERNAL_ERROR_HIVE_METASTORE_PARTITION_FILTER",
       messageParameters = Map(
         "hiveMetastorePartitionPruningFallbackOnException" ->
           SQLConf.HIVE_METASTORE_PARTITION_PRUNING_FALLBACK_ON_EXCEPTION.key),

sql/catalyst/src/test/scala/org/apache/spark/sql/catalyst/catalog/ExternalCatalogSuite.scala

@@ -573,7 +573,7 @@ abstract class ExternalCatalogSuite extends SparkFunSuite {
         // then be caught and converted to a RuntimeException with a descriptive message.
         case ex: RuntimeException if ex.getMessage.contains("MetaException") =>
           throw new AnalysisException(
-            errorClass = "_LEGACY_ERROR_TEMP_2193",
+            errorClass = "INTERNAL_ERROR_HIVE_METASTORE_PARTITION_FILTER",
             messageParameters = Map(
               "hiveMetastorePartitionPruningFallbackOnException" ->
                 SQLConf.HIVE_METASTORE_PARTITION_PRUNING_FALLBACK_ON_EXCEPTION.key))

sql/hive/src/test/scala/org/apache/spark/sql/hive/client/HivePartitionFilteringSuite.scala

@@ -26,6 +26,7 @@ import org.apache.hadoop.hive.serde2.`lazy`.LazySimpleSerDe
 import org.apache.hadoop.mapred.TextInputFormat
 import org.scalatest.BeforeAndAfterAll
 
+import org.apache.spark.SparkRuntimeException
 import org.apache.spark.sql.catalyst.TableIdentifier
 import org.apache.spark.sql.catalyst.catalog._
 import org.apache.spark.sql.catalyst.catalog.ExternalCatalogUtils.DEFAULT_PARTITION_NAME
@@ -142,11 +143,14 @@ class HivePartitionFilteringSuite(version: String)
 
   test(s"getPartitionsByFilter should fail when $fallbackKey=false") {
     withSQLConf(fallbackKey -> "false") {
-      val e = intercept[RuntimeException](
-        clientWithoutDirectSql.getPartitionsByFilter(
-          clientWithoutDirectSql.getRawHiveTable("default", "test"),
-          Seq(attr("ds") === 20170101)))
-      assert(e.getMessage.contains("Caught Hive MetaException"))
+      checkError(
+        exception = intercept[SparkRuntimeException](
+          clientWithoutDirectSql.getPartitionsByFilter(
+            clientWithoutDirectSql.getRawHiveTable("default", "test"),
+            Seq(attr("ds") === 20170101))),
+        condition = "INTERNAL_ERROR_HIVE_METASTORE_PARTITION_FILTER",
+        parameters = Map("hiveMetastorePartitionPruningFallbackOnException" ->
+          SQLConf.HIVE_METASTORE_PARTITION_PRUNING_FALLBACK_ON_EXCEPTION.key))
     }
   }