Apache Sedona 1.9.1 配置参数详解

Apache Sedona 1.9.1 配置参数详解：Spark 基础参数（jars/堆内存/Kryo 序列化）与 sedona.global/join 空间索引及空间连接参数分类详解，SedonaConf 默认值实测（RTREE/KDBTREE/LEFT），含生产配置模板与 FAQ，全程实测。

Apache SedonaApache Sedona2026/10/12

Apache Sedona 1.9.1 配置参数详解

目标：系统讲解 Apache Sedona 1.9.1 的配置参数。Sedona 无独立配置文件，参数分两层：Spark 运行时参数（spark.*，决定 jar 加载、堆内存、序列化）与 Sedona 空间引擎参数（sedona.*/spark.sedona.*，决定空间索引、空间连接行为）。本文对每个参数给出含义、默认值、设置方式与生产建议模板。所有默认值均在 Ubuntu 22.04.5 + Spark 3.5.9 + Sedona 1.9.1 环境以 SedonaConf 实测提取。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS
  • Java：OpenJDK 17.0.20.1
  • Spark：3.5.9（/opt/spark，local 模式）
  • Sedona 版本：1.9.1（/opt/sedona-jars/sedona-spark-shaded-3.5_2.12-1.9.1.jar）
  • GeoTools wrapper：/opt/sedona-jars/geotools-wrapper-1.9.1-33.5.jar
  • Python：3.10.12（pyspark 3.5.9、apache-sedona 1.9.1）
  • 配置文件：/opt/spark/conf/spark-defaults.conf

二、前置条件

已完成 Sedona 安装（见《Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南》），并能运行最小空间查询：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PYSPARK_PYTHON=python3
python3 /opt/sedona_verify.py

实测回显：

+-----------+
|point      |
+-----------+
|POINT (1 2)|
+-----------+

三、参数查看与修改方式

配置层设置入口查看方式
全局默认（作业级）/opt/spark/conf/spark-defaults.conf直接查看文件
会话级（代码内）SparkSession.builder().config(k, v)spark.conf.get(k)（Python）/ spark.conf.get(k)（Scala）
提交时覆盖spark-submit --conf k=v--conf 优先级最高
运行期动态修改spark.conf.set(k, v)（仅 SQL 类参数）同上
Sedona 引擎内部SedonaConf 对象读取上述键new SedonaConf(spark.conf) 后调 getter

💡 说明：Sedona 键支持 sedona. 与 spark.sedona. 两种前缀（如 sedona.join.gridtype 等价 spark.sedona.join.gridtype），本文统一用 sedona. 前缀。spark.conf.get 的默认值参数类型必须与键类型一致，传错类型会报 IllegalArgumentException（实测 spark.sql.shuffle.partitions 传字符串默认值报 should be int）。

四、参数总览

参数默认值（实测）作用
spark.jars空提交到集群的 jar 列表（Sedona jar 在此引入）
spark.driver.memory1g驱动 JVM 堆大小
spark.serializerJavaSerializerRDD 序列化器（建议 Kryo）
spark.kryo.registrator空Kryo 注册器（Sedona 用 SedonaKryoRegistrator）
sedona.global.indextrue空间查询是否使用空间索引
sedona.global.indextypeRTREE空间索引类型
sedona.join.gridtypeKDBTREE空间连接的网格划分方式
sedona.join.numpartition-1空间连接分区数（-1 表示自动）
sedona.join.indexbuildsideLEFT连接时在哪一侧构建空间索引
sedona.join.autoBroadcastJoinThreshold10485760空间广播连接阈值（字节）
sedona.join.spatitionsideauto空间分区的主导侧
spark.sedona.crs.geotoolsfalseCRS 变换是否走 GeoTools 引擎
spark.sql.shuffle.partitions200Shuffle 分区数（影响空间连接并行度）

默认值实测方式与回显见 5.2/5.3 节。

五、核心参数分类详解

5.1 Spark 运行时基础参数

  • spark.jars：逗号分隔的 jar 路径列表，Spark 启动时自动分发加载。Sedona 部署的核心入口：

    spark.jars                /opt/sedona-jars/sedona-spark-shaded-3.5_2.12-1.9.1.jar,/opt/sedona-jars/geotools-wrapper-1.9.1-33.5.jar

  • spark.driver.memory：驱动 JVM 堆。演示环境建议 512m，运行期验证生效值：

    /usr/lib/jvm/java-17-openjdk-amd64/bin/jps -v | grep -oE "\-Xmx[0-9]+m"

    实测回显：

    -Xmx512m

  • spark.serializer + spark.kryo.registrator：几何对象序列化必须走 Sedona 的 Kryo 注册器。实测在 SparkSession.builder 中显式设置后读取：

    .config("spark.serializer", "org.apache.spark.serializer.KryoSerializer")
.config("spark.kryo.registrator", "org.apache.sedona.core.serde.SedonaKryoRegistrator")

    GET spark.serializer = org.apache.spark.serializer.KryoSerializer
GET spark.kryo.registrator = org.apache.sedona.core.serde.SedonaKryoRegistrator

    ⚠️ 注意：实测仅调用 SedonaContext.create(spark) 而不显式配置时，spark.serializer 可能为 unset（SQL 专用 DataFrame 路径不受影响）；凡涉及 RDD 层序列化几何对象（SpatialRDD），务必显式配置上述两项。

  • spark.sql.shuffle.partitions：Shuffle 分区数，默认 200，直接决定空间连接后的并行度，小集群建议显式调低（如 12）。

5.2 Sedona 空间索引参数（sedona.global.*）

通过 SedonaConf 读取引擎实际生效值（spark-shell）：

import org.apache.sedona.core.utils.SedonaConf
val conf = new SedonaConf(spark.conf)
println("useIndex=" + conf.getUseIndex)
println("indexType=" + conf.getIndexType)

实测回显（默认值）：

useIndex=true
indexType=RTREE
参数可选值说明
sedona.global.indextrue / false是否为空间查询构建本地空间索引；false 时查询退化为线性扫描
sedona.global.indextypeRTREE / QUADTREE索引结构；RTREE 为通用默认，QUADTREE 在均匀点数据上更快

运行时设置方式：

spark.conf.set("sedona.global.index", "true")
spark.conf.set("sedona.global.indextype", "rtree")

5.3 Sedona 空间连接参数（sedona.join.*）

SedonaConf 实测默认值（同上方式）：

joinGridType=KDBTREE
buildSide=LEFT
fallbackPartitionNum=-1
autoBroadcastJoinThreshold=10485760
参数实测默认说明
sedona.join.gridtypeKDBTREE连接前对空间划分网格：KDBTREE（自适应 KD 树）/ QUADTREE / EQUALGRID
sedona.join.numpartition-1空间连接分区数；-1 自动。实测设 4 后 spark.conf.get 返回 4
sedona.join.indexbuildsideLEFT构建索引的一侧：LEFT / RIGHT / BOTH；默认左表建索引
sedona.join.autoBroadcastJoinThreshold10485760一侧数据小于阈值（字节）时走广播空间连接
sedona.join.spatitionsideauto空间分区主导侧（按哪一侧数据做空间划分）

运行时设置与读回实测（python3）：

spark.conf.set("sedona.join.numpartition", "4")
spark.conf.set("sedona.join.indexbuildside", "left")

GET sedona.join.numpartition = 4
GET sedona.join.indexbuildside = left

⚠️ 注意：网格类型与分区数决定空间连接的倾斜表现。多边形大、点小的场景（点在多边形内连接）建议 sedona.join.indexbuildside=left（左表多边形建索引）保持默认即可；两侧都是海量数据时优先调 sedona.join.numpartition。

5.4 CRS 变换与地理类型参数（spark.sedona.*）

以下键名来自 Sedona 1.9.1 的 SedonaConf（jar 内实测提取）：

参数说明
spark.sedona.crs.geotoolsCRS 变换引擎开关；启用后 ST_Transform 使用 GeoTools（需 geotools-wrapper jar）
spark.sedona.crs.url.base自定义 CRS 定义库的基础 URL
spark.sedona.crs.url.pathTemplateCRS 定义路径模板
spark.sedona.crs.url.formatCRS 定义格式
spark.sedona.geography.eagerShapeIndexGeography 类型是否急切构建 shape 索引
spark.sedona.dbscan.includeOutliersDBSCAN 聚类是否输出离群点
spark.sedona.libpostal.dataDirlibpostal 地址解析数据目录
spark.sedona.libpostal.useSenzinglibpostal 是否使用 Senzing 模式

ST_Transform 在默认配置下即可工作（实测 EPSG:4326 → EPSG:3857，见《Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南》验证节）；spark.sedona.crs.* 仅在自定义坐标系或离线 CRS 库时需要调整。

六、生产配置模板

💡 适用场景：16GB 内存节点、NVMe SSD、千万级点/面空间连接作业，Spark 3.5.9 + Sedona 1.9.1，YARN/Standalone 集群模式。

spark-defaults.conf 生产模板：

# Sedona jar（两个 jar 配套 1.9.1）
spark.jars                /opt/sedona-jars/sedona-spark-shaded-3.5_2.12-1.9.1.jar,/opt/sedona-jars/geotools-wrapper-1.9.1-33.5.jar
# 序列化：几何对象必须走 Sedona Kryo 注册器
spark.serializer          org.apache.spark.serializer.KryoSerializer
spark.kryo.registrator    org.apache.sedona.core.serde.SedonaKryoRegistrator
# 内存：驱动 512m-2g，按集群规模规划
spark.driver.memory       512m
# 并行度：按核数与数据量调整
spark.sql.shuffle.partitions  12
# 空间连接：海量面-面连接时调大分区数
sedona.join.gridtype      kdbtree
sedona.join.numpartition  -1
sedona.join.indexbuildside left
场景推荐配置
演示/测试（小内存）driver 512m、shuffle.partitions 12、sedona.join 默认值
生产点-面连接（8GB 节点）indexbuildside=left、gridtype=kdbtree、global.index=true
生产海量面-面连接（16GB 节点）numpartition=核数×2、gridtype=kdbtree、评估 broadcast 阈值
只做量测/格式转换（无连接）sedona.global.index=false 可省索引构建开销

七、常见问题

Q1：spark.conf.get("spark.sql.shuffle.partitions", "200") 报类型错误？ get 的默认值参数会被强制转换为目标类型，传 "200" 字符串对 int 型键正常、对带默认值的键传不匹配类型会报 IllegalArgumentException: should be int。建议不传默认值直接 spark.conf.get(k)。

Q2：设置了 sedona.* 参数但空间连接没变化？ 确认键名前缀（sedona. 或 spark.sedona. 均可）、设置时机（须在执行动作前），并用 SedonaConf 读回验证：

println(new SedonaConf(spark.conf).getJoinGridType)

实测回显：

KDBTREE

Q3：Kryo 注册器没配会怎样？ DataFrame/SQL 路线（本文示例）可正常工作；一旦使用 SpatialRDD（RDD 层 API），JavaSerializer 序列化几何对象性能差甚至失败。务必两项成对配置（见 5.1 节）。

Q4：如何确认参数实际生效？ 两级验证：Spark 层用 spark.conf.get(k)；Sedona 引擎层用 new SedonaConf(spark.conf) 的 getter（getUseIndex/getIndexType/getJoinGridType 等），以 getter 返回值为准。

八、参考链接

  • Sedona 官网参数文档：https://sedona.apache.org/latest-snapshot/tutorial/parameters/
  • Sedona Spatial Join 调优：https://sedona.apache.org/latest-snapshot/api/sql/Optimizer/
  • Spark 配置文档：https://spark.apache.org/docs/latest/configuration.html
  • Sedona 官网：https://sedona.apache.org/