Apache DataFusion 配置参数详解

Apache DataFusion 的可调参数集中在 SessionConfig 与运行时环境（RuntimeEnv）中，所有配置项统一采用 datafusion.<类别>.<名称> 的命名，并可通过 information_schema.df_settings 视图枚举、通过 SQL SET 语句或编程接口修改。本文基于 Apache DataFusion 55.2.0 实测环境，逐项说明常用参数的取值与含义。下文括号中的「默认值」均为实测服务器上的实际取值。

一、配置体系概览

1.1 三层配置

• SessionConfig（会话配置）：影响单次会话的 SQL 解析、执行与优化行为，如 datafusion.execution.batch_size、datafusion.optimizer.*。可在创建 SessionContext 时传入，或运行期用 SET 修改。
• RuntimeEnv / RuntimeConfig（运行时环境）：管理内存池、临时目录（磁盘溢写）、对象存储等资源，如 datafusion.runtime.memory_limit、datafusion.runtime.temp_directory。
• 对象存储与 I/O 参数：如 datafusion.execution.parquet.*，控制文件读写细节。

1.2 命名规范

所有配置项以 datafusion. 开头，第二段为类别（execution/optimizer/catalog/sql_parser/format/explain/runtime 等）。可用一条 SQL 列出全部配置：

$ datafusion-cli -q --format csv -c "SELECT name, value FROM information_schema.df_settings ORDER BY name;"
datafusion.catalog.has_header,true
datafusion.execution.batch_size,8192
datafusion.execution.target_partitions,12
datafusion.optimizer.enable_topk_aggregation,true
datafusion.execution.parquet.compression,zstd(3)
...

在实测的 55.2.0 环境中，该视图共约 150 个配置项。

二、执行类核心参数

2.1 批大小 batch_size

• 键：datafusion.execution.batch_size
• 默认值（实测）：8192
• 含义：算子间传递的 Arrow RecordBatch 行数。值越大吞吐越高但内存占用越大，值越小延迟越低但调度开销上升，常按内存与并行度调优。

2.2 分区数 target_partitions

• 键：datafusion.execution.target_partitions
• 默认值（实测）：12（等于机器可用 CPU 核数）
• 含义：查询计划的最大并行分区数，直接决定 CPU 并行度。CPU 密集型大批量分析可调大，小查询可调小以降低调度开销。

2.3 其他执行参数

三、优化器开关

优化器开关位于 datafusion.optimizer.*，常用项如下：

关闭某个优化可用于对比计划差异，例如：

$ datafusion-cli -q -c "SET datafusion.optimizer.enable_topk_aggregation = false;" \
  -c "EXPLAIN SELECT * FROM 'employees.csv' ORDER BY salary DESC LIMIT 2;"

四、内存池与运行时

• 内存上限：datafusion.runtime.memory_limit。默认不限制（空值）；CLI 可用 -m/--memory-limit 设置。实测：

$ datafusion-cli -q -m 1g -c "SHOW datafusion.runtime.memory_limit;"
+---------------------------------+-------+
| name                            | value |
+---------------------------------+-------+
| datafusion.runtime.memory_limit | 1G    |
+---------------------------------+-------+

• 内存池类型：CLI --mem-pool-type greedy|fair
  • greedy（默认）：各消费者按需抢占，实现简单；
  • fair：按消费者公平分配，避免单个算子独占。
• 磁盘溢写：datafusion.runtime.temp_directory 指定溢写临时目录；CLI -d/--disk-limit 限制可用磁盘空间（默认 100g）；datafusion.execution.spill_compression（实测 uncompressed）控制溢写压缩；datafusion.execution.max_spill_file_size_bytes（实测 134217728，即 128 MiB）为单个溢写文件上限。
• 说明：Python 绑定 48.0.0 未导出独立的 RuntimeConfig 类，内存池等运行时配置主要通过 CLI 参数或 SQL SET 设置。

五、Parquet 读写选项

位于 datafusion.execution.parquet.*，常用项：

在 Python 中可开启裁剪：

from datafusion import SessionConfig
cfg = SessionConfig().with_information_schema(True).with_parquet_pruning(True)

六、CSV 读取选项

CSV 读取通过表函数或会话配置控制，常见项：

CLI 建外部表时需用 OPTIONS 指定表头（新语法）：

CREATE EXTERNAL TABLE employees STORED AS CSV
LOCATION '/root/employees.csv'
OPTIONS ('format.has_header' 'true');

七、datafusion-cli 命令行参数

以下为 datafusion-cli --help 实测输出：

-b 会直接改变会话配置，实测：

$ datafusion-cli -q -b 4096 -c "SHOW datafusion.execution.batch_size;"
| datafusion.execution.batch_size | 4096  |

八、配置的设置方式

8.1 SQL SET 语句

$ datafusion-cli -q -c "SET datafusion.execution.target_partitions = 2;" \
  -c "SHOW datafusion.execution.target_partitions;"
| datafusion.execution.target_partitions | 2     |

8.2 Python SessionConfig

from datafusion import SessionConfig, SessionContext
cfg = (SessionConfig()
       .with_information_schema(True)
       .with_batch_size(2048)
       .with_target_partitions(4)
       .set("datafusion.execution.parquet.pushdown_filters", "true"))
ctx = SessionContext(cfg)

SessionConfig 提供 with_batch_size、with_target_partitions、with_information_schema、with_parquet_pruning、with_repartition_* 等便捷方法，其余参数用通用 set("<dotted.key>", "<value>")。

九、常用参数默认值速查