Pandas API on Spark 配置选项系统、默认索引与性能调优

1. 什么是 Pandas API on Spark 的选项系统

Pandas API on Spark 提供了一个选项系统，用来定制运行时行为。最常见的是显示类选项，比如控制最大展示行数，但它也支持影响计算行为、索引生成方式、绘图后端等。选项名采用"点式命名"，并且大小写不敏感，例如 display.max_rows。

最直接的访问方式是通过 ps.options：

import pyspark.pandas as ps

print(ps.options.display.max_rows)
ps.options.display.max_rows = 10
print(ps.options.display.max_rows)

2. 三个核心 API

Pandas API on Spark 提供了三个最核心的选项函数：

• get_option()：获取单个选项
• set_option()：设置单个选项
• reset_option()：恢复默认值

2.1 获取和设置选项

import pyspark.pandas as ps

print(ps.get_option("display.max_rows"))
ps.set_option("display.max_rows", 101)
print(ps.get_option("display.max_rows"))

2.2 恢复默认值

import pyspark.pandas as ps

print(ps.get_option("display.max_rows"))
ps.set_option("display.max_rows", 999)
print(ps.get_option("display.max_rows"))

ps.reset_option("display.max_rows")
print(ps.get_option("display.max_rows"))

这套 API 的好处是非常接近 pandas 本身，迁移成本很低。

3. 临时生效：option_context

如果你只想在一小段代码里临时修改配置，而不影响全局，可以使用 option_context。退出 with 代码块后，原配置会自动恢复。

import pyspark.pandas as ps

with ps.option_context("display.max_rows", 10, "compute.max_rows", 5):
    print(ps.get_option("display.max_rows"))
    print(ps.get_option("compute.max_rows"))

print(ps.get_option("display.max_rows"))
print(ps.get_option("compute.max_rows"))

这个特性很适合：

• Notebook 临时调试
• 某段代码特殊配置
• 避免全局选项污染

4. 不同 DataFrame 之间的运算

Pandas API on Spark 默认会限制不同 DataFrame 或 Series 之间的某些运算，因为底层通常需要做 join，而这类操作在分布式环境中可能非常昂贵。这个行为由 compute.ops_on_diff_frames 控制。

4.1 启用跨 DataFrame 运算

import pyspark.pandas as ps

ps.set_option("compute.ops_on_diff_frames", True)

psdf1 = ps.range(5)
psdf2 = ps.DataFrame({"id": [5, 4, 3]})

print((psdf1 - psdf2).sort_index())

ps.reset_option("compute.ops_on_diff_frames")

4.2 给 DataFrame 赋一个不属于它的 Series

import pyspark.pandas as ps

ps.set_option("compute.ops_on_diff_frames", True)

psdf = ps.range(5)
psser_a = ps.Series([1, 2, 3, 4])

psdf["new_col"] = psser_a
print(psdf)

ps.reset_option("compute.ops_on_diff_frames")

这个配置虽然方便，但一定要知道它背后往往意味着分布式 join，因此不能无脑打开。

5. 默认索引类型：最容易忽略也最影响性能的配置

在 pandas API on Spark 中，很多场景都需要生成默认索引，例如把 Spark DataFrame 转成 pandas-on-Spark DataFrame 时，系统会自动补一个默认索引。这个行为由 compute.default_index_type 控制。官方提供了三种模式：

• sequence
• distributed-sequence
• distributed

5.1 sequence

sequence 会生成全局递增索引，底层通过 Window 实现。问题在于它可能导致数据集中到单个节点，因此大数据集应尽量避免使用。

import pyspark.pandas as ps

ps.set_option("compute.default_index_type", "sequence")
psdf = ps.range(3)
ps.reset_option("compute.default_index_type")

print(psdf.index)

5.2 distributed-sequence

这是默认值。它也是全局递增索引，但采用分布式方式实现，比 sequence 更适合大数据场景。官方同时提醒：虽然索引值全局连续，但"哪一行对应哪个索引"在分布式环境下并不总是稳定的，特别是在 apply()、groupby()、transform() 等操作之后，索引可能重新生成，导致行和索引错位。

import pyspark.pandas as ps

ps.set_option("compute.default_index_type", "distributed-sequence")
psdf = ps.range(3)
ps.reset_option("compute.default_index_type")

print(psdf.index)

5.3 distributed

distributed 直接使用 monotonically_increasing_id() 生成索引，性能最好，几乎没有额外代价，但值本身不是严格连续的，而且具有不确定性。官方明确指出：如果你打开了 compute.ops_on_diff_frames，再用这种默认索引对两个不同 DataFrame 做运算，结果很可能不是你想要的。

import pyspark.pandas as ps

ps.set_option("compute.default_index_type", "distributed")
psdf = ps.range(3)
ps.reset_option("compute.default_index_type")

print(psdf.index)

6. 最常用的几个配置项

下面这些选项在日常开发中最值得关注。

6.1 display.max_rows

控制输出展示时最多显示多少行，默认是 1000。如果设成 None，就不限制。这个配置主要影响打印、repr() 等显示行为。

import pyspark.pandas as ps

print(ps.get_option("display.max_rows"))
ps.set_option("display.max_rows", 20)
print(ps.get_option("display.max_rows"))

6.2 compute.max_rows

控制当前 pandas-on-Spark DataFrame 的快捷计算上限，默认是 1000。当设置了这个限制后，小数据会被直接收集到 Driver，然后交给 pandas API 处理；如果超过限制，则继续走 PySpark 分布式路径。

6.3 compute.shortcut_limit

控制 shortcut 机制的阈值。系统会先取指定数量的行来推断 schema 或执行快速路径；超过这个限制后，就改用 PySpark。

6.4 compute.ordered_head

默认是 False。因为 pandas-on-Spark 不保证天然行顺序，所以 head() 返回的并不一定是你以为的"前几行"。如果把它设为 True，系统会先做自然排序再返回结果，但会带来额外性能开销。

6.5 compute.eager_check

默认是 True。如果打开，系统会为了校验提前触发一些 Spark job，这样行为会更接近 pandas，但性能会有损耗；如果关闭，速度会快一点，但某些行为可能与 pandas 有差异。

6.6 compute.isin_limit

控制 Column.isin(list) 在列表长度多大时改用 broadcast join。默认是 80。这个选项会影响 isin 的性能策略。

6.7 plotting.backend

控制绘图后端，默认是 plotly，也支持 matplotlib 等顶层具备 .plot 方法的库。

7. 还有几个不太显眼但很关键的配置

7.1 compute.default_index_cache

它控制 distributed-sequence 索引生成过程中临时 RDD 的缓存级别，默认是 MEMORY_AND_DISK_SER。如果你在大规模数据集上反复生成默认索引，这个配置会影响中间缓存策略。

7.2 compute.pandas_fallback

控制是否自动回退到 pandas 实现。默认是 False。开启后某些操作遇到不支持场景时会自动走 pandas，但这往往意味着数据要被拉回本地，因此要谨慎。

7.3 compute.fail_on_ansi_mode 与 compute.ansi_mode_support

这两个配置与 Spark ANSI 模式兼容性有关。默认情况下，pandas API on Spark 会尽量支持 ANSI 模式，但如果底层 Spark 在 ANSI 模式下工作，而某些能力不兼容，系统可能抛异常。

7.4 plotting.max_rows 与 plotting.sample_ratio

它们用于控制绘图采样规模。像 plot.bar、plot.pie 这类 top-n 图会受 plotting.max_rows 影响；而折线图、面积图等采样型图表则受 plotting.sample_ratio 影响。

8. 开发中怎么选这些配置

如果你主要是做交互式分析或 Notebook 调试，建议重点关注：

• display.max_rows
• compute.max_rows
• compute.ordered_head

如果你主要关心分布式计算性能，建议重点关注：

• compute.default_index_type
• compute.ops_on_diff_frames
• compute.shortcut_limit
• compute.isin_limit

更直白一点：

• 想看得舒服：调显示类配置
• 想跑得稳：调索引和计算类配置
• 想少踩坑：谨慎使用跨 DataFrame 运算和分布式默认索引

9. 总结

Pandas API on Spark 的配置系统不是"可有可无的小功能"，而是直接影响行为和性能的重要部分。最值得优先记住的有三件事：

1. get_option / set_option / reset_option 是最基础的控制入口
2. compute.ops_on_diff_frames 会影响不同 DataFrame 之间能不能直接运算
3. compute.default_index_type 不只是索引风格问题，还会直接影响性能和结果稳定性。

如果你只是把 pandas API on Spark 当成"分布式版 pandas"来用，而忽略这些配置，那后面很容易在性能、索引对齐和结果一致性上踩坑。把这些选项理解透，很多看起来"奇怪"的行为其实都能解释清楚。