空间数据平台的迁移常被简化成“把依赖换成新库”，但 Databricks Labs Mosaic 的官方 README 给出的信息说明，真正变化的是运行时边界。Mosaic 在 Databricks Runtime 13.3 于 2026 年 8 月结束支持，官方建议用户转向 GeoBrix。原有项目的空间函数、索引、几何提供者、语言绑定、Photon 要求与 Unity Catalog 限制，都可能影响同一条 Spark 作业的可运行性与结果。迁移应先把旧行为固化成可比较样本，再选择新组件，而不是先替换依赖再解释差异。

数据口径与可核验事实

Mosaic 官方 README 的重要公告称，Databricks Labs Mosaic 在 Databricks Runtime 13.3 于 2026 年 8 月结束支持，并建议现有及新用户采用后继项目 Databricks Labs GeoBrix。公告将 GeoBrix 描述为面向 Databricks Runtime、继续并现代化 Mosaic raster、grid 和 vector 能力的高性能空间处理库，支持 DBR 17.1 及以上以及产品空间功能。

README 同时保留了理解遗留作业所需的事实：Mosaic 是 Apache Spark 的扩展，用于大规模地理数据处理；支持 WKT、WKB、GeoJSON ingestion，提供基于 JTS 的 ST_ geometry/geography 操作、默认 H3 或 BNG 索引，以及 polygon/line 的 grid chipping。其实现主体为 Scala/JVM，Python、R 与 SQL 是围绕 Scala JVM 代码的 thin wrappers。

对 0.4.x，README 建议 DBR 13.3 LTS 且启用 Photon，并明确该系列只支持 DBR 13；非 Photon 标准集群会报出限制执行的错误。它还说明 Shared Access Cluster 中 Python bindings 会受 Py4J Security 阻止，SQL expressions 因 DBR 13 及以上 API 变化尚不能向 Unity Catalog 注册。0.3.x 则推荐 DBR 12.2 LTS with Photon，且不支持 DBR 13。

这些是项目 README 的产品与兼容性说明，不等于任何组织现有 notebook 已自动迁移成功。它们足以说明迁移清单必须同时覆盖运行时、集群访问模式、语言调用面、函数语义、索引以及结果输出。

研究的八项固定口径

  1. Mosaic 官方公告称其在 DBR 13.3 于 2026 年 8 月结束支持。
  2. 官方建议现有和新用户采用后继项目 Databricks Labs GeoBrix。
  3. 公告称 GeoBrix 继续并现代化 raster、grid 和 vector 能力。
  4. GeoBrix 被描述为仅面向 Databricks Runtime，支持 DBR 17.1 及以上。
  5. Mosaic 是 Apache Spark 的地理数据处理扩展，支持 WKT、WKB 和 GeoJSON ingestion。
  6. Mosaic 提供基于 JTS 的 ST_ 操作，默认索引为 H3 或 BNG。
  7. Mosaic 的核心实现为 Scala/JVM，Python、R 和 SQL 是 thin wrappers。
  8. Mosaic 0.4.x 只支持 DBR 13，并建议 DBR 13.3 LTS with Photon。

核心机制：先迁移契约，再迁移代码

空间 notebook 的契约至少包括输入 schema、几何编码、CRS 假设、索引分辨率、空间谓词、空值处理、输出类型和性能边界。Mosaic 的 Python 或 SQL 调用最终跨到 JVM，因此“同样的函数名”并不能保证在新运行时、不同访问模式或新库中得到相同的执行路径。把每个业务作业先写成小型基准数据集与预期断言，才能把平台升级造成的差异从数据变化中分离出来。

建议先给每一条遗留管道建一张清单：使用的 DBR、Photon、access mode、Mosaic 版本、Python/Scala/R/SQL 调用面、JTS/H3/BNG 依赖、UDF 注册方式、Unity Catalog 或 Volume 访问方式，以及涉及的 raster、grid、vector 功能。然后为每条 ST_、索引和空间 join 记录输入样本、结果要素数、面积或距离统计、空值数、输出 schema 与耗时。

GIS 场景

例如，一个湖泊监测作业把 GeoJSON 读入 Spark，转换成 geometry，再按 H3 网格汇总遥感指标。迁移前先固定一小批具有孔洞、多部件、多 CRS 和无效几何的样本，同时保存原始输入、H3 resolution、join 条件、输出网格数和逐网格聚合值。新环境运行后，先比较几何有效性、网格覆盖、边界对象和汇总差异，再扩大到全量历史分区。

对于面向 Shared Access Cluster 的 SQL 或 Python 作业，先验证是否仍依赖自定义 JVM 库和允许列表。README 已指出旧版共享集群的 Python bindings 会被 Py4J Security 阻止，SQL 注册也有 Unity Catalog 限制；这意味着迁移方案可能是改写调用面或采用平台功能，而不是在新运行时强行复制旧安装方式。

技术路径

第一，冻结旧环境证据：导出依赖、DBR、集群配置、access mode、函数列表和代表性输入输出。第二，按 vector、grid、raster 分组建立迁移矩阵；不要把三类处理混成一次不可解释的切换。第三，在隔离作业中验证 GeoBrix 或平台空间能力的安装、权限、函数可见性和最小查询。第四，用固定样本逐项做值、schema、空间覆盖和性能比较。第五，双跑一个完整发布周期，记录差异分类：数据更新、坐标处理、函数语义、运行时限制或性能回退。

一开始不必重写整个湖仓：先让一个只读、可复跑的 vector 或 grid 管道通过验收。只有当同一输入在新环境下能给出已解释的差异和可接受的资源用量，再迁移会写入 Delta 表、下游报表或业务决策的作业。

风险与局限

EoS 公告不等于 Mosaic 代码当日失效，但继续依赖停止支持的运行时会扩大修复、兼容和安全风险。反过来，GeoBrix 是后继项目也不代表所有 API、性能特征或 cluster policy 与 Mosaic 相同。尤其是自定义 JVM 库、Py4J、安全访问模式和 Unity Catalog 约束，可能使简单依赖替换失败。

空间结果的差异也不总是错误。几何库版本、索引实现、CRS、边界规则、浮点精度与数据 release 都可能改变边缘对象。团队应把阈值、允许偏差和人工核查样本写进验收记录，不能只比较总行数或一张地图截图。

检查清单

  1. 是否记录每个遗留作业的 Mosaic 版本、DBR、Photon 与 access mode？
  2. 是否区分 vector、grid、raster 管道并列出各自输入输出契约？
  3. 是否固定几何编码、CRS、索引分辨率、空间谓词和空值规则？
  4. 是否针对边界、多部件、孔洞、无效几何与空数据建立回归样本？
  5. 是否验证 Python、SQL、Scala 或 R 调用在目标 access mode 下可用？
  6. 是否单独核对 Py4J、allowlist、Unity Catalog 与 Volume 访问限制？
  7. 是否双跑并将结果差异归因后，再切换生产写入？

结论

Mosaic 的 EoS 提醒 GIS 数据团队：运行时与调用边界也是空间分析的一部分。可靠迁移不是把 databricks-mosaic 换成新包，而是把 DBR、集群模式、JVM 绑定、几何语义和结果契约逐项验收。先以小型只读管道验证 GeoBrix 或平台功能，再推进全量业务作业，才能把平台升级变成可解释的工程变更。

资料来源