Apache Gluten 配置参数详解
逐项讲解 Apache Gluten 1.7.0 配置参数：插件装载与 Velox 后端、off-heap 与原生内存、列式 Shuffle、columnar 算子开关、回退策略、批大小与并行度以及可观测性日志。
Apache GlutenApache Gluten2026/10/12
Apache Gluten 配置参数详解
Apache Gluten 的参数分两层：一层是 Spark 侧的基础参数（如 spark.plugins、spark.memory.offHeap.size），用于把 Gluten 装载进来并为其预留内存；另一层是 Gluten 自己的 spark.gluten.* 参数，用于控制后端、列式算子开关、回退策略与原生内存/并行度。本文以 Apache Gluten 1.7.0 + Spark 3.5.5 + JDK 17 为基准，逐类说明取值与含义。
一、配置方式与作用域
1.1 三种配置途径
| 途径 | 用法 | 生效范围 |
|---|---|---|
| 命令行 | --conf key=value | 单次提交 |
| 配置文件 | $SPARK_HOME/conf/spark-defaults.conf | 该 Spark 安装的所有作业 |
| 代码内 | SparkConf().set("key","value") | 单个应用 |
注意：多数 Gluten 参数是动态参数，可在运行时通过 spark.conf.set(...) 修改（同一会话内后续查询生效）；少数是静态参数，必须在启动前设定。
1.2 静态与动态参数
- 静态（必须启动前设定）：
spark.plugins、spark.memory.offHeap.enabled、spark.memory.offHeap.size、spark.shuffle.manager、spark.gluten.sql.columnar.enableVanillaVectorizedReaders、spark.gluten.sql.columnar.tableCache。 - 动态：绝大多数
spark.gluten.sql.columnar.*与内存/回退相关项。
1.3 查看生效中的配置
scala> spark.conf.get("spark.plugins")
res0: String = org.apache.gluten.GlutenPlugin
scala> spark.conf.get("spark.memory.offHeap.size")
res1: String = 1g
二、插件装载与后端
2.1 spark.plugins
- 默认值：无
- 取值：
org.apache.gluten.GlutenPlugin - 作用：通过 Spark 插件加载器装载 Gluten 的 Driver/Executor 组件。这是启用 Gluten 的唯一入口，不设置则 Gluten 完全不生效。
2.2 spark.gluten.enabled
- 默认值：
true - 作用：实验性总开关。Gluten 官方建议通过设置/取消
spark.plugins来启停，而不是改动这个值。
2.3 spark.gluten.sql.columnar.backend.velox
- 默认值：无（该前缀本身不单独取值）
- 作用：这是 Velox 后端专属参数的命名空间前缀，形如
spark.gluten.sql.columnar.backend.velox.<name>，用于传递只属于 Velox 的选项。 - 示例：
spark.gluten.sql.columnar.backend.velox.udfLibraryPaths指定 Velox UDF 动态库所在归档路径；同类还有面向内存偏好、分区数、Join 策略等的子项。 - 说明：在 1.x 早期版本中该前缀下曾存在布尔型的“是否启用 Velox 后端”开关，后续版本后端由 classpath 中的 bundle JAR 自动发现（
org.apache.gluten.backendsapi.velox.VeloxBackend），该布尔开关不再必需。具体子项的默认值以官方对应版本文档为准。
2.4 spark.gluten.loadLibFromJar
- 默认值：
false - 作用：是否直接从 JAR 内解出并加载共享库（
libgluten.so、libvelox.so）。置true时 Gluten 把原生库解压到 JNI 工作目录再加载，适合 bundle 与二进制打包在一起分发的场景；置false时从文件系统路径查找。 - 实测：本文环境使用 bundle 内置库，日志中可见
JniLibLoader: Successfully loaded library linux/amd64/libgluten.so。
2.5 原生库定位
| 参数 | 默认值 | 说明 |
|---|---|---|
spark.gluten.sql.columnar.libname | gluten | 原生主库名 |
spark.gluten.sql.columnar.libpath | 空 | Driver 侧库路径 |
spark.gluten.sql.columnar.executor.libpath | 空 | Executor 侧库路径 |
spark.gluten.loadLibOS | 空 | 指定加载器识别的 OS 名（如 linux） |
spark.gluten.loadLibOSVersion | 空 | 指定加载器识别的 OS 版本 |
三、内存配置
3.1 spark.memory.offHeap.enabled
- 默认值：
false（Gluten 推荐设为true） - 作用：启用堆外内存。Gluten 的原生执行大量使用 off-heap。
3.2 spark.memory.offHeap.size
- 默认值：0
- 作用：可用堆外内存的绝对量。即使
spark.memory.offHeap.enabled=false，Gluten 也会利用该值为原生执行预留空间，因此启用 Gluten 时务必显式设置（单机示例可用1g~2g，生产按可用内存放大）。 - 实测：堆外 OOM 时优先调大该项。
3.3 spark.gluten.memory.isolation
- 默认值：
false - 作用：开启隔离内存模式后，Gluten 把每个 task 可用的最大堆外内存限制为
executor memory / max task slots。单会话并发多查询时建议置true，避免因原生内存不可全额溢写导致 OOM。
3.4 spark.gluten.memory.overAcquiredMemoryRatio
- 默认值：
0.3 - 作用：大于 0 时，Velox 会按该比例额外多申请一部分内存作为缓冲以规避 OOM。
3.5 spark.gluten.memory.reservationBlockSize
- 默认值：
8MB - 作用：原生内存向 Spark 的内存管理器申请时的块大小。
3.6 spark.executor.memoryOverhead
- 作用：Spark 堆外内存总量 =
memoryOverhead+spark.memory.offHeap.size。Gluten 未显式设置时会自动计算，实测日志中可见VeloxListenerApi: Memory overhead is not set. Setting it to 402653184 automatically（约 384 MB）。
四、Shuffle 与列式传输
4.1 spark.shuffle.manager
- 推荐值：
org.apache.spark.shuffle.sort.ColumnarShuffleManager - 作用：把 Shuffle 切换为 Gluten 的列式实现，避免行/列转换。静态参数，须启动前设定。
4.2 spark.gluten.sql.columnar.shuffle.codec
- 默认值：空（默认支持
lz4、zstd） - 作用：列式 Shuffle 压缩算法。当
spark.gluten.sql.columnar.shuffle.codecBackend=qat时支持gzip、zstd。
4.3 常用 Shuffle 调优项
| 参数 | 默认值 | 说明 |
|---|---|---|
spark.gluten.sql.columnar.shuffle.readerBufferSize | 1MB | Shuffle reader 读取本地/远端流的缓冲大小 |
spark.gluten.sql.columnar.shuffle.merge.threshold | 0.25 | 合并阈值 |
spark.gluten.sql.columnar.shuffle.realloc.threshold | 0.25 | 重分配阈值 |
spark.gluten.sql.columnar.shuffle.dictionary.enabled | false | 哈希 Shuffle 是否启用字典编码 |
spark.gluten.sql.columnar.shuffle.compression.threshold | 100 | 行数低于该值时合并缓冲后再压缩 |
spark.gluten.sql.columnar.shuffle.sort.partitions.threshold | 4000 | 分区数超过该值时改用 sort-based 列式 Shuffle |
spark.gluten.sql.columnar.shuffle.sort.columns.threshold | 100000 | 列数超过该值时改用 sort-based 列式 Shuffle |
五、算子级开关（spark.gluten.sql.columnar.*）
这些布尔开关逐个控制某类算子是否交给原生引擎，默认基本为 true。
5.1 扫描、过滤与投影
| 参数 | 默认值 | 说明 |
|---|---|---|
...columnar.batchscan | true | 列式 BatchScan（DataSource V2） |
...columnar.filescan | true | 列式 FileScan |
...columnar.hivetablescan | true | 列式 HiveTableScan |
...columnar.filter | true | 列式 Filter |
...columnar.project | true | 列式 Project |
...columnar.batchscan.maxInputPartitions | 2147483647 | BatchScan 最大 task 分区数 |
5.2 聚合、排序与连接
| 参数 | 默认值 | 说明 |
|---|---|---|
...columnar.hashagg | true | 列式 HashAggregate |
...columnar.preferStreamingAggregate | true | 满足分组有序时优先用低内存的 StreamingAggregate |
...columnar.force.hashagg | true | 用 Gluten 哈希聚合替换 Spark 的 sort agg |
...columnar.sort | true | 列式 Sort |
...columnar.shuffledHashJoin | true | 列式 ShuffledHashJoin |
...columnar.broadcastJoin | true | 列式 BroadcastHashJoin |
...columnar.sortMergeJoin | true | 列式 SortMergeJoin（需配合 preferSortMergeJoin=false） |
...columnar.union | true | 列式 Union |
5.3 批量与写入
| 参数 | 默认值 | 说明 |
|---|---|---|
...columnar.maxBatchSize | 4096 | 单个列式 Batch 的行数 |
...columnar.parquet.write.blockSize | 128MB | 列式 Parquet 写块大小 |
...columnar.smallFileThreshold | 0.5 | 小文件总量阈值，用于把小文件分散到不同分区 |
六、回退（Fallback）策略
当某算子原生不支持或代价更高时，Gluten 会把该部分回退给原生 Spark 执行，保证结果正确。
6.1 spark.gluten.sql.ansiFallback.enabled
- 默认值：
true - 作用：ANSI 模式下默认回退到 Spark；置
false则尝试在 ANSI 模式下用 Gluten 执行。
6.2 spark.gluten.sql.columnar.query.fallback.threshold
- 默认值：
-1 - 作用：按
ColumnarToRow与朴素叶子节点数量统计，超过阈值则整条查询回退。
6.3 spark.gluten.sql.columnar.fallback.expressions.threshold
- 默认值：
50 - 作用：Filter/Project 的嵌套表达式数量达到该阈值时回退（Spark codegen 在此类场景更快）。
6.4 其它回退控制
| 参数 | 默认值 | 说明 |
|---|---|---|
...columnar.fallback.ignoreRowToColumnar | true | 统计回退次数时忽略 RowToColumnar |
...columnar.fallback.preferColumnar | true | 双方都含 ColumnarToRow 时优先选 Gluten 计划 |
...columnar.scanOnly | false | 仅把 Scan 及其后 Filter 下推原生 |
spark.gluten.expression.blacklist | 空 | 逗号分隔的表达式黑名单，跳过这些表达式的转换 |
七、原生批处理与并行度
| 参数 | 默认值 | 说明 |
|---|---|---|
spark.gluten.numTaskSlotsPerExecutor | -1 | 每 executor 的 task 槽位数；因非执行类操作不传播配置，需显式给定 |
spark.gluten.sql.columnar.maxBatchSize | 4096 | 原生处理的行批大小，过大增加内存、过小降低效率 |
spark.gluten.sql.columnar.shuffleWriter.bufferSize | 空 | Shuffle writer 缓冲字节数 |
spark.gluten.sql.columnar.shuffle.partitionBufferEvictThreshold | -1 | 拆分输入批后驱逐超过该阈值的分区缓冲；非正值关闭 |
八、可观测性
8.1 spark.sql.planChangeLog.level
- 取值：
TRACE/DEBUG/INFO/WARN/ERROR（默认未启用） - 作用：Spark 计划变更日志级别，设为
WARN或以上可打印计划变化；配合spark.sql.planChangeLog.rules可只看规则子集，便于确认 Gluten 的列式转换是否发生。
8.2 spark.gluten.sql.cacheWholeStageTransformerContext
- 默认值：
false - 作用：置
true后WholeStageTransformer会缓存执行上下文，便于拿到 Substrait 计划与原生计划字符串用于排障（有额外内存开销）。
8.3 日志与 Spark UI
将 org.apache.gluten 日志级别设为 INFO，可看到组件发现、原生库加载、内存开销等关键信息：
INFO Discovery: Discovered component files: org.apache.gluten.backendsapi.velox.VeloxBackend, ...
INFO JniLibLoader: Successfully loaded library linux/amd64/libvelox.so
INFO VeloxListenerApi: Memory overhead is not set. Setting it to 402653184 automatically.
INFO VeloxBackend: Gluten SQL Tab has been attached.
启动后 Spark UI 会多出 “Gluten SQL” 页签，展示原生执行相关的统计信息。
九、一份可直接使用的参考配置
/opt/spark/bin/spark-shell --master 'local[4]' --driver-memory 512m \
--conf spark.plugins=org.apache.gluten.GlutenPlugin \
--conf spark.memory.offHeap.enabled=true \
--conf spark.memory.offHeap.size=2g \
--conf spark.shuffle.manager=org.apache.spark.shuffle.sort.ColumnarShuffleManager \
--conf spark.gluten.sql.columnar.shuffle.codec=zstd \
--conf spark.gluten.memory.isolation=true \
--conf spark.gluten.sql.columnar.query.fallback.threshold=200 \
--conf spark.gluten.sql.columnar.fallback.expressions.threshold=50 \
--conf spark.sql.planChangeLog.level=WARN \
--jars /opt/gluten/gluten-velox-bundle-spark3.5_2.12-linux_amd64-1.7.0.jar
章节目录