Add case sensitivity doc to TableCatalog, rename methods in TableChange.

Author: rdblue

sql/catalyst/src/main/java/org/apache/spark/sql/catalog/v2/TableCatalog.java

@@ -28,6 +28,12 @@
 
 /**
  * Catalog methods for working with Tables.
+ * <p>
+ * TableCatalog implementations may be case sensitive or case insensitive. Spark will pass
+ * {@link Identifier table identifiers} without modification. Field names passed to
+ * {@link #alterTable(Identifier, TableChange...)} will be normalized to match the case used in the
+ * table schema when updating, renaming, or dropping existing columns when catalyst analysis is case
+ * insensitive.
  */
 public interface TableCatalog extends CatalogPlugin {
   /**

sql/catalyst/src/main/java/org/apache/spark/sql/catalog/v2/TableChange.java

@@ -138,7 +138,7 @@ static TableChange renameColumn(String[] fieldNames, String newName) {
    * @param newDataType the new data type
    * @return a TableChange for the update
    */
-  static TableChange updateColumn(String[] fieldNames, DataType newDataType) {
+  static TableChange updateColumnType(String[] fieldNames, DataType newDataType) {
     return new UpdateColumnType(fieldNames, newDataType, true);
   }
 
@@ -153,7 +153,10 @@ static TableChange updateColumn(String[] fieldNames, DataType newDataType) {
    * @param newDataType the new data type
    * @return a TableChange for the update
    */
-  static TableChange updateColumn(String[] fieldNames, DataType newDataType, boolean isNullable) {
+  static TableChange updateColumnType(
+      String[] fieldNames,
+      DataType newDataType,
+      boolean isNullable) {
     return new UpdateColumnType(fieldNames, newDataType, isNullable);
   }
 
@@ -168,7 +171,7 @@ static TableChange updateColumn(String[] fieldNames, DataType newDataType, boole
    * @param newComment the new comment
    * @return a TableChange for the update
    */
-  static TableChange updateComment(String[] fieldNames, String newComment) {
+  static TableChange updateColumnComment(String[] fieldNames, String newComment) {
     return new UpdateColumnComment(fieldNames, newComment);
   }
 

sql/catalyst/src/test/scala/org/apache/spark/sql/catalog/v2/TableCatalogSuite.scala

@@ -359,7 +359,7 @@ class TableCatalogSuite extends SparkFunSuite {
 
     assert(table.schema == schema)
 
-    val updated = catalog.alterTable(testIdent, TableChange.updateColumn(Array("id"), LongType))
+    val updated = catalog.alterTable(testIdent, TableChange.updateColumnType(Array("id"), LongType))
 
     val expectedSchema = new StructType().add("id", LongType).add("data", StringType)
     assert(updated.schema == expectedSchema)
@@ -376,7 +376,7 @@ class TableCatalogSuite extends SparkFunSuite {
     assert(table.schema == originalSchema)
 
     val updated = catalog.alterTable(testIdent,
-      TableChange.updateColumn(Array("id"), LongType, true))
+      TableChange.updateColumnType(Array("id"), LongType, true))
 
     val expectedSchema = new StructType().add("id", LongType).add("data", StringType)
     assert(updated.schema == expectedSchema)
@@ -390,7 +390,7 @@ class TableCatalogSuite extends SparkFunSuite {
     assert(table.schema == schema)
 
     val exc = intercept[IllegalArgumentException] {
-      catalog.alterTable(testIdent, TableChange.updateColumn(Array("id"), LongType, false))
+      catalog.alterTable(testIdent, TableChange.updateColumnType(Array("id"), LongType, false))
     }
 
     assert(exc.getMessage.contains("Cannot change optional column to required"))
@@ -406,7 +406,7 @@ class TableCatalogSuite extends SparkFunSuite {
 
     val exc = intercept[IllegalArgumentException] {
       catalog.alterTable(testIdent,
-        TableChange.updateColumn(Array("missing_col"), LongType))
+        TableChange.updateColumnType(Array("missing_col"), LongType))
     }
 
     assert(exc.getMessage.contains("missing_col"))
@@ -421,7 +421,7 @@ class TableCatalogSuite extends SparkFunSuite {
     assert(table.schema == schema)
 
     val updated = catalog.alterTable(testIdent,
-      TableChange.updateComment(Array("id"), "comment text"))
+      TableChange.updateColumnComment(Array("id"), "comment text"))
 
     val expectedSchema = new StructType()
         .add("id", IntegerType, nullable = true, "comment text")
@@ -436,14 +436,14 @@ class TableCatalogSuite extends SparkFunSuite {
 
     assert(table.schema == schema)
 
-    catalog.alterTable(testIdent, TableChange.updateComment(Array("id"), "comment text"))
+    catalog.alterTable(testIdent, TableChange.updateColumnComment(Array("id"), "comment text"))
 
     val expectedSchema = new StructType()
         .add("id", IntegerType, nullable = true, "replacement comment")
         .add("data", StringType)
 
     val updated = catalog.alterTable(testIdent,
-      TableChange.updateComment(Array("id"), "replacement comment"))
+      TableChange.updateColumnComment(Array("id"), "replacement comment"))
 
     assert(updated.schema == expectedSchema)
   }
@@ -457,7 +457,7 @@ class TableCatalogSuite extends SparkFunSuite {
 
     val exc = intercept[IllegalArgumentException] {
       catalog.alterTable(testIdent,
-        TableChange.updateComment(Array("missing_col"), "comment"))
+        TableChange.updateColumnComment(Array("missing_col"), "comment"))
     }
 
     assert(exc.getMessage.contains("missing_col"))