[SPARK-44328][SQL] Assign names to the error class _LEGACY_ERROR_TEMP_[2325-2328]

### What changes were proposed in this pull request?
The pr aims to assign names to the error class _LEGACY_ERROR_TEMP_[2325-2328].

### Why are the changes needed?
Improve the error framework.

### Does this PR introduce _any_ user-facing change?
'No'.

### How was this patch tested?
Exists test cases updated and added new test cases.

Closes #41889 from beliefer/SPARK-44328.

Authored-by: Jiaan Geng <[email protected]>
Signed-off-by: Max Gekk <[email protected]>

Author: beliefer

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

@@ -221,6 +221,38 @@
       "Failed to set permissions on created path <path> back to <permission>."
     ]
   },
+  "CANNOT_UPDATE_FIELD" : {
+    "message" : [
+      "Cannot update <table> field <fieldName> type:"
+    ],
+    "subClass" : {
+      "ARRAY_TYPE" : {
+        "message" : [
+          "Update the element by updating <fieldName>.element."
+        ]
+      },
+      "INTERVAL_TYPE" : {
+        "message" : [
+          "Update an interval by updating its fields."
+        ]
+      },
+      "MAP_TYPE" : {
+        "message" : [
+          "Update a map by updating <fieldName>.key or <fieldName>.value."
+        ]
+      },
+      "STRUCT_TYPE" : {
+        "message" : [
+          "Update a struct by updating its fields."
+        ]
+      },
+      "USER_DEFINED_TYPE" : {
+        "message" : [
+          "Update a UserDefinedType[<udtSql>] by updating its fields."
+        ]
+      }
+    }
+  },
   "CANNOT_UP_CAST_DATATYPE" : {
     "message" : [
       "Cannot up cast <expression> from <sourceType> to <targetType>.",
@@ -2965,11 +2997,6 @@
       "3. set \"spark.sql.legacy.allowUntypedScalaUDF\" to \"true\" and use this API with caution."
     ]
   },
-  "UPDATE_FIELD_WITH_STRUCT_UNSUPPORTED" : {
-    "message" : [
-      "Cannot update <table> field <fieldName> type: update a struct by updating its fields."
-    ]
-  },
   "VIEW_ALREADY_EXISTS" : {
     "message" : [
       "Cannot create view <relationName> because it already exists.",
@@ -5688,26 +5715,6 @@
       "Number of dynamic partitions created is <numWrittenParts>, which is more than <maxDynamicPartitions>. To solve this try to set <maxDynamicPartitionsKey> to at least <numWrittenParts>."
     ]
   },
-  "_LEGACY_ERROR_TEMP_2325" : {
-    "message" : [
-      "Cannot update <table> field <fieldName> type: update a map by updating <fieldName>.key or <fieldName>.value."
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_2326" : {
-    "message" : [
-      "Cannot update <table> field <fieldName> type: update the element by updating <fieldName>.element."
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_2327" : {
-    "message" : [
-      "Cannot update <table> field <fieldName> type: update a UserDefinedType[<udtSql>] by updating its fields."
-    ]
-  },
-  "_LEGACY_ERROR_TEMP_2328" : {
-    "message" : [
-      "Cannot update <table> field <fieldName> to interval type."
-    ]
-  },
   "_LEGACY_ERROR_TEMP_2330" : {
     "message" : [
       "Cannot change nullable column to non-nullable: <fieldName>."

docs/sql-error-conditions-cannot-update-field-error-class.md

@@ -0,0 +1,48 @@
+---
+layout: global
+title: CANNOT_UPDATE_FIELD error class
+displayTitle: CANNOT_UPDATE_FIELD error class
+license: |
+  Licensed to the Apache Software Foundation (ASF) under one or more
+  contributor license agreements.  See the NOTICE file distributed with
+  this work for additional information regarding copyright ownership.
+  The ASF licenses this file to You 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.
+---
+
+SQLSTATE: none assigned
+
+Cannot update `<table>` field `<fieldName>` type:
+
+This error class has the following derived error classes:
+
+## ARRAY_TYPE
+
+Update the element by updating `<fieldName>`.element.
+
+## INTERVAL_TYPE
+
+Update an interval by updating its fields.
+
+## MAP_TYPE
+
+Update a map by updating `<fieldName>`.key or `<fieldName>`.value.
+
+## STRUCT_TYPE
+
+Update a struct by updating its fields.
+
+## USER_DEFINED_TYPE
+
+Update a UserDefinedType[`<udtSql>`] by updating its fields.
+
+

docs/sql-error-conditions.md

@@ -254,6 +254,14 @@ SQLSTATE: none assigned
 
 Failed to set permissions on created path `<path>` back to `<permission>`.
 
+### [CANNOT_UPDATE_FIELD](sql-error-conditions-cannot-update-field-error-class.html)
+
+SQLSTATE: none assigned
+
+Cannot update `<table>` field `<fieldName>` type:
+
+For more details see [CANNOT_UPDATE_FIELD](sql-error-conditions-cannot-update-field-error-class.html)
+
 ### CANNOT_UP_CAST_DATATYPE
 
 SQLSTATE: none assigned
@@ -1922,12 +1930,6 @@ You're using untyped Scala UDF, which does not have the input type information.
 2. use Java UDF APIs, e.g. `udf(new UDF1[String, Integer] { override def call(s: String): Integer = s.length() }, IntegerType)`, if input types are all non primitive.
 3. set "spark.sql.legacy.allowUntypedScalaUDF" to "true" and use this API with caution.
 
-### UPDATE_FIELD_WITH_STRUCT_UNSUPPORTED
-
-SQLSTATE: none assigned
-
-Cannot update `<table>` field `<fieldName>` type: update a struct by updating its fields.
-
 ### VIEW_ALREADY_EXISTS
 
 [SQLSTATE: 42P07](sql-error-conditions-sqlstates.html#class-42-syntax-error-or-access-rule-violation)

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/analysis/CheckAnalysis.scala

@@ -1436,17 +1436,23 @@ trait CheckAnalysis extends PredicateHelper with LookupCatalog with QueryErrorsB
           val newDataType = a.dataType.get
           newDataType match {
             case _: StructType => alter.failAnalysis(
-              "UPDATE_FIELD_WITH_STRUCT_UNSUPPORTED",
+              "CANNOT_UPDATE_FIELD.STRUCT_TYPE",
               Map("table" -> toSQLId(table.name), "fieldName" -> toSQLId(fieldName)))
             case _: MapType => alter.failAnalysis(
-              "_LEGACY_ERROR_TEMP_2325", Map("table" -> table.name, "fieldName" -> fieldName))
+              "CANNOT_UPDATE_FIELD.MAP_TYPE",
+              Map("table" -> toSQLId(table.name), "fieldName" -> toSQLId(fieldName)))
             case _: ArrayType => alter.failAnalysis(
-              "_LEGACY_ERROR_TEMP_2326", Map("table" -> table.name, "fieldName" -> fieldName))
+              "CANNOT_UPDATE_FIELD.ARRAY_TYPE",
+              Map("table" -> toSQLId(table.name), "fieldName" -> toSQLId(fieldName)))
             case u: UserDefinedType[_] => alter.failAnalysis(
-              "_LEGACY_ERROR_TEMP_2327",
-              Map("table" -> table.name, "fieldName" -> fieldName, "udtSql" -> u.sql))
+              "CANNOT_UPDATE_FIELD.USER_DEFINED_TYPE",
+              Map(
+                "table" -> toSQLId(table.name),
+                "fieldName" -> toSQLId(fieldName),
+                "udtSql" -> toSQLType(u)))
             case _: CalendarIntervalType | _: AnsiIntervalType => alter.failAnalysis(
-              "_LEGACY_ERROR_TEMP_2328", Map("table" -> table.name, "fieldName" -> fieldName))
+              "CANNOT_UPDATE_FIELD.INTERVAL_TYPE",
+              Map("table" -> toSQLId(table.name), "fieldName" -> toSQLId(fieldName)))
             case _ => // update is okay
           }
 

sql/core/src/test/scala/org/apache/spark/sql/connector/AlterTableTests.scala

@@ -47,6 +47,14 @@ trait AlterTableTests extends SharedSparkSession with QueryErrorsBase {
     }
   }
 
+  private def prependCatalogName(tableName: String): String = {
+    if (catalogAndNamespace.isEmpty) {
+      s"spark_catalog.$tableName"
+    } else {
+      tableName
+    }
+  }
+
   test("AlterTable: table does not exist") {
     val t2 = s"${catalogAndNamespace}fake_table"
     val quoted = UnresolvedAttribute.parseAttributeName(s"${catalogAndNamespace}table_name")
@@ -486,9 +494,21 @@ trait AlterTableTests extends SharedSparkSession with QueryErrorsBase {
       (DataTypeTestUtils.dayTimeIntervalTypes ++ DataTypeTestUtils.yearMonthIntervalTypes)
         .foreach {
           case d: DataType => d.typeName
-            val e = intercept[AnalysisException](
-              sql(s"ALTER TABLE $t ALTER COLUMN id TYPE ${d.typeName}"))
-            assert(e.getMessage.contains("id to interval type"))
+            val sqlText = s"ALTER TABLE $t ALTER COLUMN id TYPE ${d.typeName}"
+
+            checkError(
+              exception = intercept[AnalysisException] {
+                sql(sqlText)
+              },
+              errorClass = "CANNOT_UPDATE_FIELD.INTERVAL_TYPE",
+              parameters = Map(
+                "table" -> s"${toSQLId(prependCatalogName(t))}",
+                "fieldName" -> "`id`"),
+              context = ExpectedContext(
+                fragment = sqlText,
+                start = 0,
+                stop = 33 + d.typeName.length + t.length)
+            )
         }
     }
   }
@@ -538,19 +558,13 @@ trait AlterTableTests extends SharedSparkSession with QueryErrorsBase {
       val sqlText =
         s"ALTER TABLE $t ALTER COLUMN point TYPE struct<x: double, y: double, z: double>"
 
-      val fullName = if (catalogAndNamespace.isEmpty) {
-        s"spark_catalog.default.table_name"
-      } else {
-        t
-      }
-
       checkError(
         exception = intercept[AnalysisException] {
           sql(sqlText)
         },
-        errorClass = "UPDATE_FIELD_WITH_STRUCT_UNSUPPORTED",
+        errorClass = "CANNOT_UPDATE_FIELD.STRUCT_TYPE",
         parameters = Map(
-          "table" -> s"${toSQLId(fullName)}",
+          "table" -> s"${toSQLId(prependCatalogName(t))}",
           "fieldName" -> "`point`"),
         context = ExpectedContext(
           fragment = sqlText,
@@ -573,12 +587,21 @@ trait AlterTableTests extends SharedSparkSession with QueryErrorsBase {
     val t = fullTableName("table_name")
     withTable(t) {
       sql(s"CREATE TABLE $t (id int, points array<int>) USING $v2Format")
+      val sqlText = s"ALTER TABLE $t ALTER COLUMN points TYPE array<long>"
 
-      val exc = intercept[AnalysisException] {
-        sql(s"ALTER TABLE $t ALTER COLUMN points TYPE array<long>")
-      }
-
-      assert(exc.getMessage.contains("update the element by updating points.element"))
+      checkError(
+        exception = intercept[AnalysisException] {
+          sql(sqlText)
+        },
+        errorClass = "CANNOT_UPDATE_FIELD.ARRAY_TYPE",
+        parameters = Map(
+          "table" -> s"${toSQLId(prependCatalogName(t))}",
+          "fieldName" -> "`points`"),
+        context = ExpectedContext(
+          fragment = sqlText,
+          start = 0,
+          stop = 48 + t.length)
+      )
 
       val table = getTableMetadata(t)
 
@@ -608,12 +631,21 @@ trait AlterTableTests extends SharedSparkSession with QueryErrorsBase {
     val t = fullTableName("table_name")
     withTable(t) {
       sql(s"CREATE TABLE $t (id int, m map<string, int>) USING $v2Format")
+      val sqlText = s"ALTER TABLE $t ALTER COLUMN m TYPE map<string, long>"
 
-      val exc = intercept[AnalysisException] {
-        sql(s"ALTER TABLE $t ALTER COLUMN m TYPE map<string, long>")
-      }
-
-      assert(exc.getMessage.contains("update a map by updating m.key or m.value"))
+      checkError(
+        exception = intercept[AnalysisException] {
+          sql(sqlText)
+        },
+        errorClass = "CANNOT_UPDATE_FIELD.MAP_TYPE",
+        parameters = Map(
+          "table" -> s"${toSQLId(prependCatalogName(t))}",
+          "fieldName" -> "`m`"),
+        context = ExpectedContext(
+          fragment = sqlText,
+          start = 0,
+          stop = 49 + t.length)
+      )
 
       val table = getTableMetadata(t)