Copilot commented on code in PR #2924: URL: https://github.com/apache/sedona/pull/2924#discussion_r3206604863
########## docs/setup/install-scala.zh.md: ########## @@ -0,0 +1,94 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +在开始 Sedona 之旅之前，请确保您的 Apache Spark 集群已就绪。 + +在 Apache Spark 中使用 Scala/Java 库有两种方式，您可以任选其一来运行 Sedona： + +* Spark 交互式 Scala 或 SQL shell：上手简单，适合新手尝试简单的函数调用。 +* 独立的 Scala / Java 项目：包管理学习成本较高，但适合大型项目。 + +## Spark Scala shell + +### 自动下载 Sedona jar + +1. 准备好 Spark 集群。 + +2. 使用 `--packages` 选项启动 Spark shell。该命令会自动从 Maven Central 下载 Sedona jar。 + +``` +./bin/spark-shell --packages MavenCoordinates +``` + +请参考 [Sedona Maven Central 坐标](maven-coordinates.md)，根据您的 Spark 版本选择对应的 Sedona 包。 + + * 本地模式：无需搭建集群即可测试 Sedona + ``` + ./bin/spark-shell --packages org.apache.sedona:sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }},org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }} + ``` + + * 集群模式：需要指定 Spark Master IP + ``` + ./bin/spark-shell --master spark://localhost:7077 --packages org.apache.sedona:sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }},org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }} + ``` + +### 手动下载 Sedona jar + +1. 准备好 Spark 集群。 + +2. 下载 Sedona jar： + * 从 [Sedona Releases](../download.md) 下载预编译 jar + * 下载 / git clone Sedona 源码并自行编译（参见 [编译 Sedona](compile.md)） +3. 使用 `--jars` 选项启动 Spark shell。 + +``` +./bin/spark-shell --jars /Path/To/SedonaJars.jar +``` + +请使用文件名中包含 Spark major.minor 版本号的 jar，例如 `sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}`。 + + * 本地模式：无需搭建集群即可测试 Sedona + ``` + ./bin/spark-shell --jars /path/to/sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}.jar,/path/to/geotools-wrapper-{{ sedona.current_geotools }}.jar + ``` + + * 集群模式：需要指定 Spark Master IP + ``` + ./bin/spark-shell --master spark://localhost:7077 --jars /path/to/sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}.jar,/path/to/geotools-wrapper-{{ sedona.current_geotools }}.jar Review Comment: 这里用 `sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}` 作为示例文件名；在 `sedona.current_version=1.9.0` 且 Spark 3.3 已不支持的前提下，这个示例会误导读者下载/引用不存在的 JAR。建议把示例中的 `3.3` 更新为当前支持的 Spark major.minor（如 3.4），或明确提示替换为自己的 Spark 版本。 ########## docs/setup/flink/install-python.zh.md: ########## @@ -0,0 +1,34 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +安装 Apache Sedona Python，请按以下步骤操作： + +1. 安装所需的 Python 包。 + +``` +pip install apache-sedona[flink] shapely attr Review Comment: 安装命令里使用了 `attr`，但 Sedona Python 依赖是 `attrs`（见 `python/pyproject.toml`）。`attr` 和 `attrs` 是不同的包名，这里可能导致安装失败或装错依赖。建议将命令中的 `attr` 更正为 `attrs`。 ########## docs/setup/docker.zh.md: ########## @@ -0,0 +1,179 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +# Sedona JupyterLab Docker 镜像 + +Sedona 的 Docker 镜像可在 [Sedona 官方 DockerHub 仓库](https://hub.docker.com/r/apache/sedona) 获取。 + +我们提供了一个集成 Python JupyterLab、Apache Zeppelin，以及 1 个 master 节点和 1 个 worker 节点的 Apache Sedona Docker 镜像。 + +## 使用方法 + +### 从 DockerHub 拉取镜像 + +格式： + +```bash +docker pull apache/sedona:<sedona_version> +``` + +示例 1：拉取 Sedona master 分支的最新镜像 + +```bash +docker pull apache/sedona:latest +``` + +示例 2：拉取某个特定 Sedona 发布版本的镜像 + +```bash +docker pull apache/sedona:{{ sedona.current_version }} +``` + +### 启动容器 + +格式： + +```bash +docker run -d -e DRIVER_MEM=<driver_mem> -e EXECUTOR_MEM=<executor_mem> -p 8888:8888 -p 8080:8080 -p 8081:8081 -p 4040:4040 -p 8085:8085 apache/sedona:<sedona_version> +``` + +`driver_mem` 与 `executor_mem` 是可选项；如果未提供，容器将分别为 driver 和 executor 各分配 4GB 内存。`-d`（或 `--detach`）参数让容器以分离模式后台运行。 + +示例 1： + +```bash +docker run -d -e DRIVER_MEM=6g -e EXECUTOR_MEM=8g -p 8888:8888 -p 8080:8080 -p 8081:8081 -p 4040:4040 -p 8085:8085 apache/sedona:latest +``` + +该命令会启动一个使用 6GB driver 内存与 8GB executor 内存的容器，并使用最新的 Sedona 镜像；容器以分离模式运行。 + +该命令会将容器的 8888、8080、8081、4040、8085 端口分别映射到宿主机的同名端口。 + +示例 2： + +```bash +docker run -d -e -p 8888:8888 -p 8080:8080 -p 8081:8081 -p 4040:4040 -p 8085:8085 apache/sedona:{{ sedona.current_version }} Review Comment: 示例 2 的 `docker run` 命令里包含单独的 `-e`（后面没有环境变量名/值），该命令会直接报错。请移除该 `-e`，或补全需要设置的环境变量。 ########## docs/setup/install-scala.zh.md: ########## @@ -0,0 +1,94 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +在开始 Sedona 之旅之前，请确保您的 Apache Spark 集群已就绪。 + +在 Apache Spark 中使用 Scala/Java 库有两种方式，您可以任选其一来运行 Sedona： + +* Spark 交互式 Scala 或 SQL shell：上手简单，适合新手尝试简单的函数调用。 +* 独立的 Scala / Java 项目：包管理学习成本较高，但适合大型项目。 + +## Spark Scala shell + +### 自动下载 Sedona jar + +1. 准备好 Spark 集群。 + +2. 使用 `--packages` 选项启动 Spark shell。该命令会自动从 Maven Central 下载 Sedona jar。 + +``` +./bin/spark-shell --packages MavenCoordinates +``` + +请参考 [Sedona Maven Central 坐标](maven-coordinates.md)，根据您的 Spark 版本选择对应的 Sedona 包。 + + * 本地模式：无需搭建集群即可测试 Sedona + ``` + ./bin/spark-shell --packages org.apache.sedona:sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }},org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }} + ``` + + * 集群模式：需要指定 Spark Master IP + ``` + ./bin/spark-shell --master spark://localhost:7077 --packages org.apache.sedona:sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }},org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }} Review Comment: 此处示例使用 `sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }}`。但当前文档 `mkdocs.yml` 中 `sedona.current_version` 为 1.9.0，且平台页已声明 Spark 3.3 自 1.8.0 起不再受支持，因此该坐标很可能不存在/不可用。建议将示例更新为受支持的 Spark 版本（例如 3.4/3.5/4.x），并与 `setup/maven-coordinates.md` 保持一致。 ########## docs/setup/install-python.zh.md: ########## @@ -0,0 +1,122 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +Apache Sedona 扩展了 PySpark 函数，依赖以下库： + +* pyspark +* shapely +* attrs + +如果您的系统尚未安装这些包，请先安装。Sedona 现使用 [uv](https://docs.astral.sh/uv/) 管理 Python 依赖，详细依赖定义见 [pyproject.toml](https://github.com/apache/sedona/blob/master/python/pyproject.toml)。 + +### 安装 sedona + +* 从 PyPI 仓库安装。最新版的 Sedona Python 可在 [PyPI](https://pypi.org/project/apache-sedona/) 找到。[Sedona v1.0.1 及更早版本存在已知问题](release-notes.md#known-issue)。 + +```bash +pip install apache-sedona +``` + +* 自 Sedona v1.1.0 起，pyspark 已成为 Sedona Python 的可选依赖，因为许多 Spark 平台都已预装 Spark。如需在安装 Sedona Python 时一并安装 pyspark，请使用 `spark` 附加项： + +```bash +pip install apache-sedona[spark] +``` + +* 从 Sedona Python 源码安装 + +克隆 Sedona GitHub 源码后运行以下命令： + +```bash +cd python +python3 -m pip install . +``` + +### 准备 sedona-spark jar + +Sedona Python 需要额外配套一个名为 `sedona-spark-shaded` 或 `sedona-spark` 的 jar 文件。请确保所选版本与您的 Spark 和 Scala 版本匹配。 + +请在 artifact 名称中使用 Spark 的 major.minor 版本号。 + +可通过以下方式之一获取该 jar： + +1. 如果您在 Databricks、AWS EMR 或其他云平台的 notebook 中运行 Sedona，请使用 `shaded jar`：从 Maven Central 下载 [sedona-spark-shaded jar](https://repo.maven.apache.org/maven2/org/apache/sedona/) 与 [geotools-wrapper jar](https://repo.maven.apache.org/maven2/org/datasyslab/geotools-wrapper/)，并将其放入 `SPARK_HOME/jars/` 目录。 +2. 如果您在 IDE 或本地 Jupyter Notebook 中运行 Sedona，请使用 `unshaded jar`，并在 Python 程序中通过 [Maven Central 坐标](maven-coordinates.md) 引用，例如： + +==Sedona >= 1.4.1== + +```python +from sedona.spark import * + +config = ( + SedonaContext.builder() + .config( + "spark.jars.packages", + "org.apache.sedona:sedona-spark-3.3_2.12:{{ sedona.current_version }}," + "org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }}", + ) Review Comment: `spark.jars.packages` 示例使用了 `sedona-spark-3.3_2.12:{{ sedona.current_version }}`。但 `sedona.current_version` 当前为 1.9.0 且 Spark 3.3 已不再支持，这会导致坐标解析失败。建议改为与实际 Spark 版本匹配的坐标（例如 `sedona-spark-3.4_2.12:{{ sedona.current_version }}`），并与 `setup/maven-coordinates.md` 一致。 ########## docs/setup/emr.zh.md: ########## @@ -0,0 +1,80 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +在 EMR 上推荐使用 Sedona-1.3.1-incubating 及以上版本。本教程使用 AWS Elastic MapReduce (EMR) 6.9.0，已预装以下应用：Hadoop 3.3.3、JupyterEnterpriseGateway 2.6.0、Livy 0.7.1、Spark 3.3.0。 + +本教程在带 EMR Studio（notebook）的 EMR on EC2 上完成测试。EMR on EC2 使用 YARN 进行资源管理。 + +!!!note + 如果您使用 Spark 3.4+ 与 Scala 2.12，请使用 `sedona-spark-shaded-3.4_2.12`。请注意 Spark 与 Scala 的版本后缀。 + Review Comment: 本页使用 EMR 6.9.0（Spark 3.3.0），但文档全局 `sedona.current_version` 为 1.9.0，且 `setup/platform.md` 已说明 Spark 3.3 自 Sedona 1.8.0 起不再支持。按当前模板渲染后会引导用户在 Spark 3.3 上使用 Sedona 1.9.0，实际无法兼容/下载对应 JAR。建议更新为 Spark 3.4+ 的 EMR 版本，或在文中明确需要将 Sedona 版本 pin 到仍支持 Spark 3.3 的版本。 ########## docs/setup/cluster.zh.md: ########## @@ -0,0 +1,51 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +# 搭建您的 Apache Spark 集群 + +请从 [Spark 下载页面](http://spark.apache.org/downloads.html) 下载 Spark 发行版。 + +## 前置准备 + +1. 在集群上配置免密 SSH。每对 master-worker 之间需要双向免密 SSH。 +2. 确保已安装 JRE 1.8 或更高版本。 Review Comment: 这里写的是 `JRE 1.8 或更高版本`，但 `setup/platform.md` 已明确 Sedona 在 Spark 3.4/3.5 需要 Java 11、Spark 4.x 需要 Java 17，且 Java 8 自 1.8.0 起已弃用。建议将最低 Java 版本要求更新为与当前支持矩阵一致（至少 Java 11）。 ########## docs/setup/fabric.zh.md: ########## @@ -0,0 +1,134 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +本教程将指引您在 Microsoft Fabric Synapse Data Engineering 的 Spark 环境中安装 Sedona。 + +## 步骤 1：打开 Microsoft Fabric Synapse Data Engineering + +进入 [Microsoft Fabric 门户](https://app.fabric.microsoft.com/)，选择 `Data Engineering` 选项。 + + + +## 步骤 2：创建 Microsoft Fabric Data Engineering 环境 + +在左侧点击 `My Workspace`，再点击 `+ New` 新建一个 `Environment`，命名为 `ApacheSedona`。 + + + +## 步骤 3：选择 Apache Spark 版本 + +在 `Environment` 页面，点击 `Home` 选项卡并选择合适的 Apache Spark 版本。后续需要根据这个版本安装匹配的 Apache Sedona 版本。 + + + +## 步骤 4：安装 Sedona Python 包 + +在 `Environment` 页面，点击 `Public libraries` 选项卡，输入 `apache-sedona`，并选择合适的 Apache Sedona 版本，来源（source）选择 `PyPI`。 + + + +## 步骤 5：设置 Spark 配置项 + +在 `Environment` 页面，点击 `Spark properties` 选项卡，新建以下 3 个配置项： + +- `spark.sql.extensions`：`org.apache.sedona.viz.sql.SedonaVizExtensions,org.apache.sedona.sql.SedonaSqlExtensions` +- `spark.serializer`：`org.apache.spark.serializer.KryoSerializer` +- `spark.kryo.registrator`：`org.apache.sedona.core.serde.SedonaKryoRegistrator` + + + +## 步骤 6：保存并发布环境 + +依次点击 `Save` 与 `Publish` 按钮以保存并发布环境，环境随之创建并安装好 Apache Sedona Python 包。发布过程大约需要 10 分钟。 + + + +## 步骤 7：找到 Sedona jar 的下载链接 + +1. 阅读 [Sedona maven 坐标](maven-coordinates.md) 了解所需的 Sedona jar。 +2. 在 [Maven Central](https://search.maven.org/search?q=g:org.apache.sedona) 查找 `sedona-spark-shaded` jar。请注意 jar 的 Spark 与 Scala 版本：如果 Fabric 环境选择了 Spark 3.4，则应下载与 Spark 3.4 + Scala 2.12 对应的 jar，文件名形如 `sedona-spark-shaded-3.4_2.12-1.5.1.jar`。 +3. 在 [Maven Central](https://search.maven.org/search?q=g:org.datasyslab) 查找 `geotools-wrapper` jar。请注意 jar 与 Sedona 的版本对应关系：若使用 Sedona 1.5.1，则应下载 `geotools-wrapper` 1.5.1 版本，文件名形如 `geotools-wrapper-1.5.1-28.2.jar`。 + +下载链接示例： + +``` +https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.4_2.12/1.5.1/sedona-spark-shaded-3.4_2.12-1.5.1.jar +https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/1.5.1-28.2/geotools-wrapper-1.5.1-28.2.jar +``` + +## 步骤 8：在带有 Sedona 环境的 notebook 中安装 jar + +在 notebook 页面，选择此前创建的 `ApacheSedona` 环境。 + + + +可在 notebook 中运行以下代码安装 jar，请将 `jars` 替换为上一步的两个下载链接： + +```text +%%configure -f +{ + "jars": ["https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/1.5.1-28.2/geotools-wrapper-1.5.1-28.2.jar";, "https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.4_2.12/1.5.1/sedona-spark-shaded-3.4_2.12-1.5.1.jar";] +} +``` + +## 步骤 9：验证安装 + +可在 notebook 中运行以下代码验证安装： + +```python +from sedona.spark import * + +sedona = SedonaContext.create(spark) + + +sedona.sql("SELECT ST_GeomFromEWKT('SRID=4269;POINT(40.7128 -74.0060)')").show() +``` + +如果看到点的输出，则说明安装成功。 + + + +## 可选：手动将 Sedona jar 上传到 Fabric 环境的 LakeHouse 存储 + +如果集群无法访问公网，或您希望避免缓慢的实时下载，可以手动将 Sedona jar 上传到 Fabric 环境的 LakeHouse 存储。 + +在 notebook 页面打开 `Explorer`，点击 `LakeHouses` 选项。如果还没有 LakeHouse，可先创建一个。然后选择 `Files`，将上一步下载的 2 个 jar 上传上去。 + +上传完成后，您应能在 LakeHouse 存储中看到这 2 个 jar。复制它们的 `ABFS` 路径。本例中路径为： + +```angular2html +abfss://9e9d4196-870a-4901-8fa5-e24841492...@onelake.dfs.fabric.microsoft.com/e15f3695-af7e-47de-979e-473c3caa9f5b/Files/sedona-spark-shaded-3.4_2.12-1.5.1.jar + +abfss://9e9d4196-870a-4901-8fa5-e24841492...@onelake.dfs.fabric.microsoft.com/e15f3695-af7e-47de-979e-473c3caa9f5b/Files/geotools-wrapper-1.5.1-28.2.jar +``` + + + + + +如使用此选项，notebook 中的配置代码应改为： + +```text +%%configure -f +{ + "conf": { + "spark.jars": "abfss://XXX/Files/sedona-spark-shaded-3.4_2.12-1.5.1.jar,abfss://XXX/Files/geotools-wrapper-1.5.1-28.2.jar", Review Comment: 这里的 `%configure` JSON 示例在 `"spark.jars": ...` 行末包含多余的尾随逗号，这会导致 JSON 解析失败从而无法配置 Spark。请移除该尾随逗号，确保示例是合法 JSON。 ########## docs/setup/install-python.zh.md: ########## @@ -0,0 +1,122 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +Apache Sedona 扩展了 PySpark 函数，依赖以下库： + +* pyspark +* shapely +* attrs + +如果您的系统尚未安装这些包，请先安装。Sedona 现使用 [uv](https://docs.astral.sh/uv/) 管理 Python 依赖，详细依赖定义见 [pyproject.toml](https://github.com/apache/sedona/blob/master/python/pyproject.toml)。 + +### 安装 sedona + +* 从 PyPI 仓库安装。最新版的 Sedona Python 可在 [PyPI](https://pypi.org/project/apache-sedona/) 找到。[Sedona v1.0.1 及更早版本存在已知问题](release-notes.md#known-issue)。 + +```bash +pip install apache-sedona +``` + +* 自 Sedona v1.1.0 起，pyspark 已成为 Sedona Python 的可选依赖，因为许多 Spark 平台都已预装 Spark。如需在安装 Sedona Python 时一并安装 pyspark，请使用 `spark` 附加项： + +```bash +pip install apache-sedona[spark] +``` + +* 从 Sedona Python 源码安装 + +克隆 Sedona GitHub 源码后运行以下命令： + +```bash +cd python +python3 -m pip install . +``` + +### 准备 sedona-spark jar + +Sedona Python 需要额外配套一个名为 `sedona-spark-shaded` 或 `sedona-spark` 的 jar 文件。请确保所选版本与您的 Spark 和 Scala 版本匹配。 + +请在 artifact 名称中使用 Spark 的 major.minor 版本号。 + +可通过以下方式之一获取该 jar： + +1. 如果您在 Databricks、AWS EMR 或其他云平台的 notebook 中运行 Sedona，请使用 `shaded jar`：从 Maven Central 下载 [sedona-spark-shaded jar](https://repo.maven.apache.org/maven2/org/apache/sedona/) 与 [geotools-wrapper jar](https://repo.maven.apache.org/maven2/org/datasyslab/geotools-wrapper/)，并将其放入 `SPARK_HOME/jars/` 目录。 +2. 如果您在 IDE 或本地 Jupyter Notebook 中运行 Sedona，请使用 `unshaded jar`，并在 Python 程序中通过 [Maven Central 坐标](maven-coordinates.md) 引用，例如： + +==Sedona >= 1.4.1== + +```python +from sedona.spark import * + +config = ( + SedonaContext.builder() + .config( + "spark.jars.packages", + "org.apache.sedona:sedona-spark-3.3_2.12:{{ sedona.current_version }}," + "org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }}", + ) + .config( + "spark.jars.repositories", + "https://artifacts.unidata.ucar.edu/repository/unidata-all";, + ) + .getOrCreate() +) +sedona = SedonaContext.create(config) +``` + +==Sedona < 1.4.1== + +`SedonaRegistrator` 自 Sedona 1.4.1 起已被弃用，请改用上面的方式。 + +```python +from pyspark.sql import SparkSession +from sedona.spark import SedonaRegistrator +from sedona.spark import SedonaKryoRegistrator, KryoSerializer + +spark = ( + SparkSession.builder.appName("appName") + .config("spark.serializer", KryoSerializer.getName) + .config("spark.kryo.registrator", SedonaKryoRegistrator.getName) + .config( + "spark.jars.packages", + "org.apache.sedona:sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }}," Review Comment: 此处 `spark.jars.packages` 仍引用 `sedona-spark-shaded-3.3_2.12:{{ sedona.current_version }}`。在 `sedona.current_version=1.9.0` 且 Spark 3.3 不受支持时，这个示例会无法下载依赖。建议更新为受支持的 Spark major.minor（如 3.4/3.5/4.x）对应的 artifact。 ########## docs/setup/azure-synapse-analytics.zh.md: ########## @@ -0,0 +1,248 @@ +<!-- + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + --> + +本教程指引您在启用了数据外泄保护（Data Exfiltration Protection，DEP）或由于其他网络限制导致 Spark 池无法访问公网的情况下，在 Azure Synapse Analytics 中安装 Sedona。 + +## 开始之前 + +本教程主要演示如何在 Spark 3.4、Python 3.10 上跑通 Sedona 1.6.1。 + +如果您希望运行更新的版本，请参考本文后半部分介绍的详细构建与诊断流程。 + +## 强烈建议 + +1. 从一个未安装其他包的干净 Spark 池开始，以避免依赖冲突。 +2. Apache Spark 池 -> Apache Spark 配置：使用默认配置。 + +## Sedona 1.6.1 在 Spark 3.4、Python 3.10 上的安装 + +### 步骤 1：下载 9 个包 + +注意：版本必须严格匹配，最新并不总是最优。 + +来自 Maven： + +- [sedona-spark-shaded-3.4_2.12-1.6.1.jar](https://mvnrepository.com/artifact/org.apache.sedona/sedona-spark-shaded-3.4_2.12/1.6.1) + +- [geotools-wrapper-1.6.1-28.2.jar](https://mvnrepository.com/artifact/org.datasyslab/geotools-wrapper/1.6.1-28.2) + +来自 PyPI： + +- [rasterio-1.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl](https://files.pythonhosted.org/packages/cd/ad/2d3a14e5a97ca827a38d4963b86071267a6cd09d45065cd753d7325699b6/rasterio-1.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl) + +- [shapely-2.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl](https://files.pythonhosted.org/packages/2b/a6/302e0d9c210ccf4d1ffadf7ab941797d3255dcd5f93daa73aaf116a4db39/shapely-2.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl) + +- [apache_sedona-1.6.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl](https://files.pythonhosted.org/packages/b6/71/09f7ca2b6697b2699c04d1649bb379182076d263a9849de81295d253220d/apache_sedona-1.6.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl) + +- [click_plugins-1.1.1-py2.py3-none-any.whl](https://files.pythonhosted.org/packages/e9/da/824b92d9942f4e472702488857914bdd50f73021efea15b4cad9aca8ecef/click_plugins-1.1.1-py2.py3-none-any.whl) + +- [cligj-0.7.2-py3-none-any.whl](https://files.pythonhosted.org/packages/73/86/43fa9f15c5b9fb6e82620428827cd3c284aa933431405d1bcf5231ae3d3e/cligj-0.7.2-py3-none-any.whl) + +- [affine-2.4.0-py3-none-any.whl](https://files.pythonhosted.org/packages/0b/f7/85273299ab57117850cc0a936c64151171fac4da49bc6fba0dad984a7c5f/affine-2.4.0-py3-none-any.whl) + +- [numpy-2.1.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl](https://files.pythonhosted.org/packages/fb/25/ba023652a39a2c127200e85aed975fc6119b421e2c348e5d0171e2046edb/numpy-2.1.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl) + +### 步骤 2：将包上传到 Synapse 工作区 + +https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-manage-workspace-packages + +### 步骤 3：将包添加到 Spark 池 + +本教程采用该页面中的第二种方式：**If you are updating from the Synapse Studio** + +https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-manage-pool-packages#manage-packages-from-synapse-studio-or-azure-portal + +### 步骤 4：notebook + +在 notebook 起始处加入以下代码： + +```python +from sedona.spark import SedonaContext + +config = ( + SedonaContext.builder() + .config( + "spark.jars.packages", + "org.apache.sedona:sedona-spark-shaded-3.4_2.12-1.6.1," + "org.datasyslab:geotools-wrapper-1.6.1-28.2", Review Comment: `spark.jars.packages` 的 Maven 坐标写法不正确：这里把版本用 `-1.6.1` 拼到 artifact 后面，并且 geotools-wrapper 也缺少 `:version` 段。`spark.jars.packages` 需要 `groupId:artifactId:version` 形式、多个坐标用英文逗号分隔。请更正为合法的 Maven 坐标字符串，否则 Spark 无法下载依赖。 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
