Databricks作业加载表时所有列自动转小写 仅作业环境触发异常

这类环境差异导致的列名大小写不一致问题，本质是Spark大小写处理配置在不同运行环境的默认值差异导致，Databricks平台上90%以上的同类问题都来自以下几个明确原因：

• 交互式Notebook环境默认注入了列名大小写保留配置spark.sql.legacy.preserveCaseSensitiveColumnNames=true，而作业集群默认不携带该配置。当作业读取Parquet/ORC格式的表时，会自动将列名归一化为小写返回；如果作业集群额外配置了spark.sql.hive.convertMetastoreParquet=false，会强制走原生Hive SerDe读取链路，Hive默认会将所有非引号包裹的标识符自动转为小写处理。
• 非Notebook格式的作业（Python脚本/JAR包提交类型）如果在代码中手动初始化SparkSession，未继承Databricks集群的默认SQL配置补丁，会回退到Spark原生的列名解析逻辑，触发列名转小写的行为。
• 若物化视图时生成的是外部Parquet/ORC表，可能出现元存储登记的列名大小写与物理文件footer存储的列名大小写不一致的情况，不同读取链路（内置Delta/Parquet读取器 vs Hive SerDe）会返回不同大小写的列名。

按以下顺序排查可以快速定位根因：

• 分别在作业运行环境和Notebook环境执行以下配置查询代码，对比三个关键配置的返回值差异：

  print(spark.conf.get("spark.sql.caseSensitive"))
  print(spark.conf.get("spark.sql.legacy.preserveCaseSensitiveColumnNames", "UNSET"))
  print(spark.conf.get("spark.sql.hive.convertMetastoreParquet", "UNSET"))
  

  只要三个配置存在任意一项值不一致，基本就能定位为配置差异问题。
• 在两个环境分别执行DESCRIBE EXTENDED <你的表名>，对比返回的列名定义，确认元数据层存储的列名确实为大写，排除跨catalog/跨工作区访问了不同同名表的情况。
• 执行DESCRIBE DETAIL <你的表名>查看表格式，如果是Parquet/ORC类型的外部表，直接读取物理文件的footer信息，确认文件中存储的实际列名大小写，排除元数据与物理数据结构不一致的问题。
• 如果是脚本/JAR类型作业，检查代码中是否存在手动构建SparkSession的逻辑，是否手动覆盖了SQL相关的配置项。

按优先级从高到低选择方案即可：

• 无环境依赖的通用方案（推荐）：读取表后统一做列名归一化，不依赖任何环境配置，彻底规避环境差异带来的问题：

  df = spark.table("your_target_table")
  # 统一将列名转为和原表一致的大写格式
  df = df.toDF(*[col.upper() for col in df.columns])
  

  后续代码可以稳定按大写列名处理，不管集群配置如何变化都不会触发列名不存在的报错。
• 配置对齐方案：在作业集群的「高级配置-Spark配置」中添加和Notebook一致的参数，对齐两边的处理逻辑：

  spark.sql.legacy.preserveCaseSensitiveColumnNames true
  spark.sql.hive.convertMetastoreParquet true
  

  如果是代码中手动初始化SparkSession的场景，在构建Session时显式传入上述配置即可。
• 表结构修复方案：如果排查发现是元存储登记的列名和物理文件列名不一致，可以通过ALTER TABLE语句逐列修正元存储中的列名大小写，或者直接在作业运行的配置环境下重新执行CTAS物化视图，保证写入和读取链路的配置一致，从根源上对齐元数据。
• 长期编码规范调整：后续编写Spark逻辑时，不要硬编码依赖列名的大小写匹配，引用列前统一做大小写归一化，从编码层面避免这类环境差异问题。

内容的提问来源于stack exchange，提问作者stosxri