使用pyspark.pandas.read_table读取Databricks表遇UC兼容性报错及疑问

尝试使用pyspark.pandas.read_table读取Databricks上的表为DataFrame时，触发如下错误：

AnalysisException: [UC_COMMAND_NOT_SUPPORTED] AttachDistributedSequence is not supported in Unity Catalog.;
AttachDistributedSequence[__index_level_0__#767L, _c0#734, carat#735, cut#736, color#737, clarity#738, depth#739, table#740, price#741, x#742, y#743, z#744] Index: __index_level_0__#767L
+- SubqueryAlias spark_catalog.default.diamonds
   +- Relation hive_metastore.default.diamonds[_c0#734,carat#735,cut#736,color#737,clarity#738,depth#739,table#740,price#741,x#742,y#743,z#744] csv

表是通过Databricks快速入门笔记本创建的，代码如下：

DROP TABLE IF EXISTS diamonds;
 
CREATE TABLE diamonds
USING csv
OPTIONS (path "/databricks-datasets/Rdatasets/data-001/csv/ggplot2/diamonds.csv", header "true")

读取表的代码：

import pyspark.pandas as ps
psdf = ps.read_table("hive_metastore.default.diamonds")

但使用spark.read.table读取为spark.sql.DataFrame可正常运行：

df = spark.read.table("hive_metastore.default.diamonds")

集群版本：

• Databricks Runtime Version 11.2
• Apache Spark 3.3.0
• Scala 2.12

本人熟悉pandas，希望使用pyspark.pandas.DataFrame，因其API符合使用习惯，有以下疑问：

1. 该错误的含义是什么？
2. 如何将表读取为pyspark.pandas.DataFrame？
3. 是否应转而学习并使用pyspark.sql.DataFrame？若是，原因是什么？

1. 错误含义 #

这个错误是因为pyspark.pandas（原Koalas）读取表时会自动尝试添加一个分布式序列作为默认索引（即日志中的__index_level_0__），而当前使用的Databricks Runtime 11.2版本中，Unity Catalog不支持AttachDistributedSequence这个操作，因此触发了UC_COMMAND_NOT_SUPPORTED异常。

2. 读取为pyspark.pandas.DataFrame的方法 #

有两种可行方案：

• 方案一：Spark DataFrame转换法
  先通过spark.read.table读取为Spark原生DataFrame，再转换为pyspark.pandas.DataFrame，同时禁用自动索引生成：

  import pyspark.pandas as ps
  # 开启Arrow优化提升转换效率（可选）
  spark.conf.set("spark.sql.execution.arrow.pyspark.enabled", "true")
  # 读取并转换，指定不生成默认索引
  spark_df = spark.read.table("hive_metastore.default.diamonds")
  ps_df = ps.DataFrame(spark_df, index_col=None)
  

• 方案二：SQL查询读取法
  使用read_sql直接执行SQL查询，绕开自动添加索引的逻辑：

  import pyspark.pandas as ps
  ps_df = ps.read_sql("SELECT * FROM hive_metastore.default.diamonds", spark)
  

3. 是否应转而使用pyspark.sql.DataFrame？ #

不一定，需根据使用场景判断：

• 优先选pyspark.pandas的场景：
  • 已熟练掌握pandas API，希望快速迁移代码到Spark环境，降低学习成本
  • 处理小到中等规模数据，核心操作是pandas风格的数据分析（如分组聚合、数据清洗）
• 建议用pyspark.sql.DataFrame的场景：
  • 处理超大规模分布式数据，需要精细控制Spark执行计划（如分区、Shuffle优化）
  • 需要使用Spark高级功能，如窗口函数、复杂SQL查询、流处理、MLlib机器学习库等
  • 团队统一使用Spark原生API，便于协作维护
  • 遇到pyspark.pandas兼容性问题（如本案例的Unity Catalog支持问题），且暂时无法升级Runtime版本

注：pyspark.pandas本质是Spark的上层封装，底层依赖Spark引擎，遇到性能或兼容性问题时，切换到原生Spark API是更稳妥的选择。

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