Apache Sedona 1.9.1 常用工具与 API 详解

Apache Sedona 1.9.1 常用工具与 API 详解：spark-shell/pyspark/spark-submit 三种入口实测用法，构造、量测、空间关系、坐标变换等 ST_ 函数速查（全 256 个），Python GeometryType UDT 与 shapely 互通示例，含 FAQ，全程实测。

Apache SedonaApache Sedona2026/10/12

Apache Sedona 1.9.1 常用工具与 API 详解

目标：详解 Apache Sedona 1.9.1 的使用入口与核心 API。Sedona 无独立命令行程序，一切操作通过 Spark 的 spark-shell/pyspark/spark-submit 三个入口加载 Sedona jar 后以 SQL 函数（ST_*）或 Python API 完成。本文按入口与函数分类速查，给出代码示例与真实回显（含 256 个 ST_ 函数规模实测、GeometryType UDT 与 shapely 互通实测）。

一、环境信息

  • 操作系统：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、shapely 2.1.2）
  • 演示账号：root

二、工具概览

Sedona 以「Spark 插件 jar」形态提供，没有 sedona 命令行可执行程序。全部操作 = Spark 入口 + Sedona jar + SedonaContext.create 注册，之后 SQL 与 Python API 通用：

入口语言典型用途
spark-shellScala/SQL交互式查询、脚本验证（-i 加载脚本）
pyspark / python3Python数据分析脚本、Notebook
spark-submit任意生产作业提交
API 类别代表函数/类作用
几何构造ST_Point、ST_GeomFromText、ST_GeomFromWKT从坐标或 WKT 构造几何类型
几何输出ST_AsText、ST_AsGeoJSON几何转 WKT/GeoJSON 文本
空间量测ST_Area、ST_Distance、ST_Length面积、距离、长度
空间关系ST_Contains、ST_Intersects、ST_Within范围连接/相交判断
坐标变换ST_TransformCRS 投影转换（依赖 geotools-wrapper）
Python 类型GeometryType（UDT）shapely 几何与 Spark 列互转

💡 说明：Sedona 1.9.1 注册后共有 800 个函数，其中 ST_ 前缀的空间函数 256 个（实测统计，见 5.6 节）。

三、前置条件

已按《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)|
+-----------+

四、三个入口工具详解

4.1 spark-shell（Scala 交互式）

方案 A 的 spark-defaults.conf 已全局引入 Sedona jar，直接启动：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
/opt/spark/bin/spark-shell --master "local[*]"

实测启动横幅关键行：

Spark context available as 'sc' (master = local[*], app id = local-1791810790684).
Spark session available as 'spark'.

在提示符中注册 Sedona 并查询：

import org.apache.sedona.spark.SedonaContext
val sedona = SedonaContext.create(spark)
sedona.sql("SELECT ST_AsText(ST_Point(1.0, 2.0)) AS point").show(false)

实测回显：

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

也可用 -i 一次性加载脚本（脚本注释须为 ASCII，见《Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南》FAQ Q2）：

/opt/spark/bin/spark-shell --master "local[*]" -i /opt/sedona-demo/sedona_demo.scala

4.2 pyspark 与 python3（Python）

两种 Python 用法：交互式 REPL 用 pyspark 命令；分析脚本用 python3 直接运行（代码内 SparkSession.builder 创建会话），后者更适合沉淀成作业：

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PYSPARK_PYTHON=python3
cd /opt/sedona-demo
python3 sedona_demo.py

会话创建与注册的标准写法（见《Apache Sedona 1.9.1 构建并运行示例空间分析应用指南》第四节完整源码）：

from sedona.spark import SedonaContext
from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .master("local[*]") \
    .appName("SedonaPythonDemo") \
    .config("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") \
    .config("spark.driver.memory", "512m") \
    .getOrCreate()
sedona = SedonaContext.create(spark)

4.3 spark-submit（作业提交）

export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PYSPARK_PYTHON=python3
cd /opt/sedona-demo
/opt/spark/bin/spark-submit --master "local[*]" --conf spark.log.level=WARN sedona_demo.py

查询结果与 python3 直跑一致；作业正常退出时日志尾部实测：

26/10/12 13:25:26 INFO SparkContext: Successfully stopped SparkContext
26/10/12 13:25:27 INFO ShutdownHookManager: Shutdown hook called

💡 说明：spark-submit 默认日志级别为 INFO（spark-shell 默认 WARN）；--conf spark.log.level=WARN 可静默运行日志。JVM 堆生效值验证用 jps -v | grep -oE "\-Xmx[0-9]+m"，实测输出 -Xmx512m。

五、SQL 函数（ST_*）速查

5.1 几何构造

SELECT ST_AsText(ST_Point(1.0, 2.0)) AS point;
SELECT ST_AsText(ST_GeomFromText('POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))')) AS poly;

实测回显：

+-----------+
|point      |
+-----------+
|POINT (1 2)|
+-----------+
函数说明
ST_Point(x, y)由坐标构造点
ST_GeomFromText(wkt) / ST_GeomFromWKT(wkt)WKT 字符串转几何（两者等价）
ST_GeomFromGeoJSON(json)GeoJSON 转几何
ST_Polygon(linestring, polygon)由外壳与内洞构造多边形

5.2 几何输出

函数实测示例输出
ST_AsText(geom)ST_AsText(ST_Point(1.0, 2.0))POINT (1 2)
ST_AsGeoJSON(geom)输出 GeoJSON 文本—

5.3 空间量测

SELECT round(ST_Area(ST_GeomFromText('POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))')), 1) AS area;

实测回显：

+----+
|area|
+----+
|16.0|
+----+
函数说明
ST_Area(geom)面积（上例 4×4 矩形 = 16.0）
ST_Distance(g1, g2)两几何最短欧氏距离（KNN 依据，见 5.5 节实测）
ST_Length(geom)线长度

5.4 空间关系（连接谓词）

函数语义
ST_Contains(a, b)a 包含 b（b 在边界上时为假）
ST_Intersects(a, b)a 与 b 至少有一点相交（含边界）
ST_Within(a, b)a 包含于 b（Contains 的反视角）
ST_DWithin(a, b, d)两几何距离是否小于等于 d（常用于范围过滤）

实测：ST_Contains 范围连接命中 3 行、ST_Intersects 计数 3（完整回显见《Apache Sedona 1.9.1 构建并运行示例空间分析应用指南》第六节）。

5.5 坐标变换与衍生几何

SELECT ST_AsText(ST_Transform(ST_GeomFromText('POINT (116.397128 39.916527)'), 'EPSG:4326', 'EPSG:3857')) AS pt3857;
SELECT ST_AsText(ST_PointOnSurface(ST_GeomFromText('POLYGON ((0 0, 4 0, 4 4, 0 4, 0 0))'))) AS center;

实测回显：

+--------------------------------------------+
|pt3857                                      |
+--------------------------------------------+
|POINT (12957269.018759485 4853819.614609157)|
+--------------------------------------------+
+-----------+
|center     |
+-----------+
|POINT (2 2)|
+-----------+
函数说明
ST_Transform(geom, srcCRS, dstCRS)CRS 投影转换（依赖 geotools-wrapper jar）
ST_PointOnSurface(geom)面内代表点（上例 4×4 矩形中心 (2,2)）
ST_Centroid(geom)几何质心
ST_Buffer(geom, d)缓冲区

5.6 函数规模统计（实测）

python3 会话中统计全部注册函数：

all_fns = [r[0] for r in sedona.sql("SHOW FUNCTIONS").collect()]
st_fns = sorted(f for f in all_fns if f.lower().startswith("st_"))
print("ALL_FUNCTION_COUNT =", len(all_fns))
print("ST_FUNCTION_COUNT =", len(st_fns))

实测回显：

ALL_FUNCTION_COUNT = 800
ST_FUNCTION_COUNT = 256

函数名样例（实测首尾各一批）：

st_3ddistance, st_3ddwithin, st_3dextent, st_3dmakebox, st_addmeasure, st_addpoint, st_affine, st_angle, st_approximatemedialaxis, st_area, st_areaspheroid, st_asbinary, st_asewkb, st_asewkt, st_asgeojson, st_asgml
st_xmin, st_y, st_ymax, st_ymin, st_z, st_zmax, st_zmflag, st_zmin

⚠️ 注意：SHOW FUNCTIONS LIKE 'ST_%' 在 Spark 3.5.9 实测返回 0 行（LIKE 模式对存储名大小写敏感，Sedona 注册名为混合大小写）；统计请 SHOW FUNCTIONS 全量后客户端过滤。

六、Python API：GeometryType UDT 与 shapely 互通

Python 路线可直接用 shapely 几何对象建 DataFrame，Sedona 通过 GeometryType UDT 自动承载：

import shapely.geometry as sg
from sedona.spark.sql.types import GeometryType
df = sedona.createDataFrame([(1, sg.Point(1.0, 2.0)), (2, sg.Point(3.0, 4.0))], schema=["id", "geom"])
df.select("id", "geom").show(truncate=False)
print("SCHEMA:", df.schema.simpleString())
print("UDT_CLASS:", type(df.schema["geom"].dataType).__name__)

实测回显：

+---+-----------+
|id |geom       |
+---+-----------+
|1  |POINT (1 2)|
|2  |POINT (3 4)|
+---+-----------+

SCHEMA: struct<id:bigint,geom:udt>
UDT_CLASS: GeometryType

要点：

API说明
SedonaContext.create(spark)注册 ST_ 函数、几何 UDT 与优化器规则（1.4+ 统一入口）
GeometryType（sedona.spark.sql.types）几何列的 UDT 类型，承载 shapely 对象
sedona.sql(sqlText)等价 spark.sql，返回 DataFrame
createDataFrame(data, schema)本地数据（含 shapely 几何）转分布式 DataFrame

七、注意事项

⚠️ 注意：

  1. 三个入口的 Sedona jar 必须配套：spark-shell/spark-submit 走 spark-defaults.conf 或 --jars，Python 路线在 SparkSession.builder 的 spark.jars 注入，路径为绝对路径。
  2. Python 路线需 pandas/pyarrow 依赖（缺失时 import sedona.spark 直接失败）。
  3. ST_Transform 需 geotools-wrapper jar；缺失时构造/量测函数可用，仅 CRS 变换报错。
  4. SQL 函数名大小写不敏感（st_contains 与 ST_Contains 均可执行），但 SHOW FUNCTIONS LIKE 模式匹配大小写敏感。

八、常见问题

Q1：from sedona.spark import SedonaContext 报 ModuleNotFoundError？ apache-sedona 未安装或 pandas 缺失。pip3 install pyspark==3.5.9 apache-sedona==1.9.1 pandas pyarrow（实测版本组合见《Ubuntu 22.04 安装 Apache Sedona 1.9.1 指南》方案 B）。

Q2：spark-shell 里 SedonaContext.create 找不到符号？ 未加载 Sedona jar 或 import 错误。确认 spark.jars 已配置且执行了 import org.apache.sedona.spark.SedonaContext。

Q3：SQL 函数执行报 UNRESOLVED_ROUTINE？ 该函数不存在或 jar 未注册。先用 SHOW FUNCTIONS 全量确认函数名（注意 LIKE 大小写陷阱），再核对 SedonaContext.create 是否已执行。

Q4：shapely 对象进 DataFrame 报类型不支持？ 未执行 SedonaContext.create（UDT 未注册）。注册后 shapely 的 Point/Polygon 等 Geometry 子类即可经 GeometryType 承载（实测 schema 显示 geom:udt）。

九、参考链接

  • Sedona SQL 函数总览：https://sedona.apache.org/latest-snapshot/api/sql/Overview/
  • Sedona Python API：https://sedona.apache.org/latest-snapshot/api/sql/DataFrameAPI/
  • Spark 快速上手：https://spark.apache.org/docs/latest/quick-start.html
  • Sedona 官网：https://sedona.apache.org/