diff --git a/docs/setup/azure-synapse-analytics.zh.md b/docs/setup/azure-synapse-analytics.zh.md new file mode 100644 index 00000000000..2f2c67782b9 --- /dev/null +++ b/docs/setup/azure-synapse-analytics.zh.md @@ -0,0 +1,248 @@ + + +本教程指引您在启用了数据外泄保护（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", + ) + .config("spark.serializer", "org.apache.spark.serializer.KryoSerializer") + .config( + "spark.kryo.registrator", "org.apache.sedona.core.serde.SedonaKryoRegistrator" + ) + .config( + "spark.sql.extensions", + "org.apache.sedona.viz.sql.SedonaVizExtensions,org.apache.sedona.sql.SedonaSqlExtensions", + ) + .getOrCreate() +) + +sedona = SedonaContext.create(config) +``` + +跑一个测试： + +```python +sedona.sql("SELECT ST_GeomFromEWKT('SRID=4269;POINT(40.7128 -74.0060)')").show() +``` + +如果看到点的输出，则说明安装成功，配置工作至此完成。 + +## Sedona 1.6.0 在 Spark 3.4、Python 3.10 上需要的包 + +``` +spark-xml_2.12-0.17.0.jar +sedona-spark-shaded-3.4_2.12-1.6.0.jar + +click_plugins-1.1.1-py2.py3-none-any.whl +affine-2.4.0-py3-none-any.whl +apache_sedona-1.6.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl +cligj-0.7.2-py3-none-any.whl +rasterio-1.3.10-cp310-cp310-manylinux2014_x86_64.whl +shapely-2.0.4-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl +snuggs-1.4.7-py3-none-any.whl +geotools-wrapper-1.6.0-28.2.jar +``` + +## 背景：如何为其他/未来版本的 Spark 与/或 Sedona 确定所需包 + +警告：该流程需要相当的技术耐心与排错能力。 + +整体步骤：用与已部署 Spark 池相同的镜像构建一台 Linux 虚拟机，按 Synapse 进行配置，安装 Sedona 包，再识别出在 Synapse 基线之上额外需要的包。 + +下面是 Sedona 1.6.1 在 Spark 3.4、Python 3.10 上的实操过程（同一流程也用于 Sedona 1.6.0）。 + +### 步骤 1：根据版本识别 Spark 池所用的 Linux 镜像 + +https://learn.microsoft.com/en-us/azure/synapse-analytics/spark/apache-spark-34-runtime + +### 步骤 2：下载 ISO + +https://github.com/microsoft/azurelinux/tree/2.0 + +### 步骤 3：构建虚拟机 + +https://github.com/microsoft/azurelinux/blob/2.0/toolkit/docs/quick_start/quickstart.md#iso-image + +如使用 Hyper-V，需注意以下设置： + +- 启用 Secure Boot：Microsoft UEFI Certificate authority +- CPU 核心数：2 +- 关闭动态内存（固定为 8GB）。忘记此设置会带来很多麻烦。 + +### 步骤 4：更新虚拟机 + +连接到虚拟机，注意首次启动会比预期更慢。 + +```sh +sudo dnf upgrade +``` + +### 步骤 5：可选但强烈推荐 —— 安装 ssh-server（以便复制粘贴） + +```sh +sudo tdnf install -y openssh-server +``` + +启用 root 与密码认证： + +```sh +sudo vi /etc/ssh/sshd_config +- PasswordAuthentication yes +- PermitRootLogin yes +``` + +启动 ssh-server： + +```bash +sudo systemctl enable --now sshd.service +``` + +识别虚拟机 IP（这里在 Windows 10 桌面上使用 Hyper-V）： + +```ps +Get-VMNetworkAdapter -VMName "Synapse Spark 3.4 Python 3.10 Sedona 1.6.1" | Select-Object -ExpandProperty IPAddresses +``` + +### 步骤 6：安装 Miniconda + +```bash +cd /tmp +wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh +chmod +x Miniconda3-latest-Linux-x86_64.sh +./Miniconda3-latest-Linux-x86_64.sh +``` + +### 步骤 7：安装编译器 + +```sh +sudo tdnf -y install gcc g++ +``` + +### 步骤 8：创建 Synapse 基线虚拟环境 + +下载虚拟环境定义文件： + +```bash +wget -O Synapse-Python310-CPU.yml https://raw.githubusercontent.com/microsoft/synapse-spark-runtime/refs/heads/main/Synapse/spark3.4/Synapse-Python310-CPU.yml source +``` + +```bash +conda env create -f Synapse-Python310-CPU.yml -n synapse +``` + +如果在 `fsspec_wrapper` 处报错，请从 yml 中移除 `fsspec_wrapper==0.1.13=py_3` 后重试。 + +如果在上述修改之后仍出现来自 `pip` 的其他错误，可以忽略，仍可继续。 + +### 步骤 9：安装 Sedona Python 包 + +```bash +conda activate synapse +echo "apache-sedona==1.6.1" > requirements.txt +pip install -r requirements.txt > pip-output.txt +``` + +### 步骤 10：识别需要下载的 Python 包 + +```bash +grep Downloading pip-output.txt +``` + +**该输出即为您需要从 PyPI 定位并下载的包列表。** + +输出示例： + +``` +Downloading apache_sedona-1.6.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (177 kB) +Downloading shapely-2.0.6-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.5 MB) +Downloading rasterio-1.4.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (22.2 MB) +Downloading affine-2.4.0-py3-none-any.whl (15 kB) +Downloading cligj-0.7.2-py3-none-any.whl (7.1 kB) +Downloading click_plugins-1.1.1-py2.py3-none-any.whl (7.5 kB) +``` + +### 步骤 11：在已部署的 Azure Synapse Spark 池（真实环境，不是虚拟机）中识别包冲突 + +- 将包上传到工作区 +- 将包加入您的（干净的！）Spark 池 + +请仔细查看 Synapse 返回的错误信息，并逐一排查冲突。 + +注意：在 Spark 3.4 上安装 Sedona 1.6.0 时未遇到问题，但 Sedona 1.6.1 及其支持包出现了与 `numpy` 相关的冲突，需要下载特定版本并加入包列表。`numpy` 并未出现在前面 grep 的输出中。 diff --git a/docs/setup/cluster.zh.md b/docs/setup/cluster.zh.md new file mode 100644 index 00000000000..1529ee1bb8e --- /dev/null +++ b/docs/setup/cluster.zh.md @@ -0,0 +1,51 @@ + + +# 搭建您的 Apache Spark 集群 + +请从 [Spark 下载页面](http://spark.apache.org/downloads.html) 下载 Spark 发行版。 + +## 前置准备 + +1. 在集群上配置免密 SSH。每对 master-worker 之间需要双向免密 SSH。 +2. 确保已安装 JRE 1.8 或更高版本。 +3. 将所有 worker 的 IP 地址列入 `./conf/slaves`。 +4. 除必要的 Spark 配置外，您可能还需要在 Spark 配置文件中加入以下设置以避免 Sedona 内存相关错误： + +在 `./conf/spark-defaults.conf` 中： + +``` +spark.driver.memory 10g +spark.network.timeout 1000s +spark.driver.maxResultSize 5g +``` + +* `spark.driver.memory` 用于为 driver 程序分配足够的内存。Sedona 需要在 driver 上构建全局网格文件（全局索引）。如果数据量较大（通常超过 100 GB），将该参数设为 2~5 GB 较为合适，否则可能出现 “out of memory” 错误。 +* `spark.network.timeout` 是所有网络交互的默认超时时间。空间连接查询有时需要更长的 shuffle 时间，调大此参数可让 Spark 有足够的耐心等待结果。 +* `spark.driver.maxResultSize` 是每个 Spark action 中所有分区的序列化结果总大小限制。空间查询的结果有时较大，`Collect` 操作可能会抛出错误。 + +更多 Spark 参数细节请参阅 [Spark 官方文档](https://spark.apache.org/docs/latest/configuration.html)。 + +## 启动集群 + +进入解压后的 Apache Spark 目录的根目录，通过终端启动 Spark 集群： + +``` +./sbin/start-all.sh +``` diff --git a/docs/setup/compile.zh.md b/docs/setup/compile.zh.md new file mode 100644 index 00000000000..0c83337eff4 --- /dev/null +++ b/docs/setup/compile.zh.md @@ -0,0 +1,193 @@ + + +# 编译 Sedona 源码 + +## 编译 Scala / Java 源码 + +Sedona Scala/Java 代码是一个多模块项目，每个模块都是 Scala/Java 混合工程，由 Apache Maven 3 管理。 + +* 请确保您的 Linux/Mac 机器上已安装 Java 11/17、Apache Maven 3.3.1+ 与 Python 3.8+。Sedona 的编译尚未在 Windows 机器上测试。 + +要编译所有模块，请确保位于所有模块的根目录，然后在终端运行以下命令： + +=== "不运行单元测试" + ```bash + mvn clean install -DskipTests + ``` + 该命令会先删除旧的二进制文件，并编译所有模块；编译过程会跳过单元测试。如果只编译单个模块，请进入对应模块的目录后运行同一命令。 + +=== "运行单元测试" + ```bash + mvn clean install + ``` + 所有模块的 Maven 单元测试可能耗时长达 30 分钟。 + +=== "打包 Geotools jar" + ```bash + mvn clean install -DskipTests -Dgeotools + ``` + Geotools 相关 jar 会被打入生成的 fat jar 中。 + +!!!note + 默认情况下，该命令会针对 Spark 3.4 和 Scala 2.12 编译 Sedona。 + +### 针对不同目标编译 + +可使用 `-Dspark` 与 `-Dscala` 命令行参数指定不同的目标： + +* `-Dspark`：`{major}.{minor}`，例如 `-Dspark=3.4` 表示针对 Spark 3.4 编译。 +* `-Dscala`：`2.12` 或 `2.13` + +=== "Spark 3.4+ Scala 2.12" + ``` + mvn clean install -DskipTests -Dspark=3.4 -Dscala=2.12 + ``` + 若要针对更高 Spark 版本编译，请将 `3.4` 替换为对应的 Spark major.minor 版本。 +=== "Spark 3.4+ Scala 2.13" + ``` + mvn clean install -DskipTests -Dspark=3.4 -Dscala=2.13 + ``` + 若要针对更高 Spark 版本编译，请将 `3.4` 替换为对应的 Spark major.minor 版本。 + +!!!tip + 如需获取打包好所有 GeoTools jar 的 Sedona Spark Shaded jar，只需追加 `-Dgeotools` 选项，例如：`mvn clean install -DskipTests -Dscala=2.12 -Dspark=3.4 -Dgeotools` + +### 下载 staged jar + +Sedona 通过 GitHub Actions 在每次提交时自动生成 jar。您可以在 [此处](https://github.com/apache/sedona/actions/workflows/java.yml) 点击对应提交的 ==Artifacts== 标签下载这些 jar。 + +## 运行 Python 测试 + +1) 准备 Spark（如未安装则下载）并设置环境变量 + +```bash +export SPARK_VERSION=3.4.0 # 或其他受支持的版本 +wget https://archive.apache.org/dist/spark/spark-${SPARK_VERSION}/spark-${SPARK_VERSION}-bin-hadoop3.tgz +tar -xvzf spark-${SPARK_VERSION}-bin-hadoop3.tgz +rm spark-${SPARK_VERSION}-bin-hadoop3.tgz +export SPARK_HOME=$PWD/spark-${SPARK_VERSION}-bin-hadoop3 +export PYTHONPATH=$SPARK_HOME/python +``` + +2) 将所需的 JAI jar 放入 $SPARK_HOME/jars + +```bash +export JAI_CORE_VERSION="1.1.3" +export JAI_CODEC_VERSION="1.1.3" +export JAI_IMAGEIO_VERSION="1.1" +wget -P $SPARK_HOME/jars/ https://repo.osgeo.org/repository/release/javax/media/jai_core/${JAI_CORE_VERSION}/jai_core-${JAI_CORE_VERSION}.jar +wget -P $SPARK_HOME/jars/ https://repo.osgeo.org/repository/release/javax/media/jai_codec/${JAI_CODEC_VERSION}/jai_codec-${JAI_CODEC_VERSION}.jar +wget -P $SPARK_HOME/jars/ https://repo.osgeo.org/repository/release/javax/media/jai_imageio/${JAI_IMAGEIO_VERSION}/jai_imageio-${JAI_IMAGEIO_VERSION}.jar +``` + +3) 构建包含 GeoTools shaded 的 Sedona Scala/Java jar（从仓库根目录执行） + +```bash +mvn clean install -DskipTests -Dgeotools +cp spark-shaded/target/sedona-spark-shaded-*.jar $SPARK_HOME/jars/ +``` + +4) 准备 Python 开发环境 + +Python 包使用 `pyproject.toml`（PEP 517/518）并以 setuptools 作为构建后端。推荐使用 [uv](https://docs.astral.sh/uv/) 管理虚拟环境与依赖。 + +```bash +cd python +python -m pip install --upgrade uv +uv venv --python 3.10 # 或其他受支持的版本（>=3.8） +``` + +5) 安装匹配的 PySpark 版本与其他依赖 + +```bash +cd python +# 使用正确的 PySpark 版本，否则将默认安装最新版 +uv add pyspark==${SPARK_VERSION} --optional spark +uv sync +``` + +6) 以可编辑模式安装 Sedona 并运行 Python 测试 + +```bash +cd python +uv pip install -e . +uv run pytest -v tests +``` + +## 编译文档 + +文档网站会在每次提交后自动构建，构建产物可在以下位置下载： + +### MkDocs 网站 + +文档网站源码以 Markdown 编写，由 MkDocs 编译，主题基于 [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)。 + +在 Sedona 仓库中，MkDocs 配置文件 ==mkdocs.yml== 位于根目录，所有文档源码位于 `docs` 目录。 + +如需在本地编译源码并测试网站，请阅读 [MkDocs 教程](http://www.mkdocs.org/#installation) 与 [Materials for MkDocs 教程](https://squidfunk.github.io/mkdocs-material/getting-started/)。 + +简而言之，需要运行： + +``` +python3 -m pip install uv +uv sync --group docs +``` + +安装好 MkDocs 与 MkDocs-Material 后，在 Sedona 根目录运行： + +``` +uv run mkdocs build +uv run mike deploy --update-aliases latest-snapshot -b website -p +uv run mike serve +``` + +## pre-commit + +我们通过 GitHub Actions 运行 [pre-commit](https://pre-commit.com/)，因此本地安装目前是可选的。 + +pre-commit 的[配置文件](https://github.com/apache/sedona/blob/master/.pre-commit-config.yaml)位于仓库根目录。在运行钩子之前，需要先安装 pre-commit。 + +钩子会在执行 `git commit` 时运行，也可以通过命令行 `pre-commit` 触发。部分钩子会在失败时自动修复代码，但大多数会输出 linter 错误信息。如果某个钩子失败，整个 commit 会失败，您需要修复问题后重新 `git add` 并提交。`git commit` 时钩子大多只针对修改过的文件运行；如果想对所有文件运行所有钩子，或者您正在新增钩子，应运行： + +`pre-commit run --all-files` + +有时您可能需要跳过某个钩子，例如该钩子阻碍了提交，或您本地缺少该钩子所需的依赖。`SKIP` 变量以英文逗号分隔多个钩子： + +`SKIP=codespell git commit -m "foo"` + +在直接运行 pre-commit 时同样适用： + +`SKIP=codespell pre-commit run --all-files` + +偶尔您在执行 `git commit` 时遇到更严重的问题，可以使用 `--no-verify` 跳过 pre-commit 检查直接提交，例如： + +`git commit --no-verify -m "foo"` + +如果只想运行某个钩子（例如 `markdownlint`），可使用： + +`pre-commit run markdownlint --all-files` + +仓库根目录下的 [Makefile](https://github.com/apache/sedona/blob/master/Makefile) 提供了三个与 pre-commit 相关的便捷命令。 + +例如，可以运行以下命令将 pre-commit 安装为每次提交前自动运行的钩子： + +``` +make checkinstall +``` diff --git a/docs/setup/databricks.zh.md b/docs/setup/databricks.zh.md new file mode 100644 index 00000000000..afda58ff95f --- /dev/null +++ b/docs/setup/databricks.zh.md @@ -0,0 +1,194 @@ + + +您可以在 Databricks 中运行 Sedona，以充分利用 Sedona 提供的功能。下面是一个运行 Sedona 代码的 Databricks notebook 示例： + +![示例 notebook](../image/databricks/image1.png) + +由于平台限制，Sedona 并非在所有 Databricks 环境中都可用。本文将说明如何以及在哪些 Databricks 环境中运行 Sedona。 + +## Databricks 与 Sedona 的版本要求 + +Databricks 与 Sedona 都依赖 Spark、Scala 等多个库。 + +例如，某个 Databricks Runtime 16.4 依赖 Scala 2.12 与 Spark 3.5。下表给出几个 Databricks 运行时的版本要求： + +![Databricks 运行时](../image/databricks/image2.png) + +如果使用基于 Spark 3.5 与 Scala 2.12 编译的 Databricks Runtime，那么也应使用基于 Spark 3.5 与 Scala 2.12 编译的 Sedona 版本。即使您只使用 Python 或 SQL API，Scala 版本也必须保持一致。 + +## 在 Databricks 中安装 Sedona 库 + +执行以下命令下载所需的 Sedona 包： + +```sh +%sh +# 为 Sedona 创建 JAR 目录 +mkdir -p /Workspace/Shared/sedona/{{ sedona.current_version }} + +# 从 Maven 下载依赖到 DBFS +curl -o /Workspace/Shared/sedona/{{ sedona.current_version }}/geotools-wrapper-{{ sedona.current_geotools }}.jar "https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/{{ sedona.current_geotools }}/geotools-wrapper-{{ sedona.current_geotools }}.jar" + +curl -o /Workspace/Shared/sedona/{{ sedona.current_version }}/sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar "https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/{{ sedona.current_version }}/sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar" +``` + +`sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar` 的编译环境如下： + +* Spark 3.5 +* Scala 2.12 +* Sedona {{ sedona.current_version }} + +请确保使用与该 jar 兼容的 Databricks Runtime。 + +下载完成后，您应在 Databricks 环境中看到这些文件： + +![已下载的 JAR](../image/databricks/image3.png) + +按以下方式创建一个初始化脚本： + +``` +%sh + +# 为 Sedona 创建初始化脚本目录 +mkdir -p /Workspace/Shared/sedona/ + +# 创建初始化脚本 +cat > /Workspace/Shared/sedona/sedona-init.sh <<'EOF' +#!/bin/bash +# +# File: sedona-init.sh +# +# 集群启动时，将 Sedona 的 jar 复制到集群默认的 jar 目录。 + +# 可选：移除 Databricks 自带的 H3 JAR，以避免与 Sedona 的 H3 函数发生版本冲突。 +# Databricks 自带的是 H3 v3.x，与 Sedona 使用的 H3 v4.x API 不兼容。 +# 如果您需要使用 Sedona 的 H3 函数（如 ST_H3CellIDs），请取消下一行的注释。 +# rm -f /databricks/jars/*h3*.jar + +cp /Workspace/Shared/sedona/{{ sedona.current_version }}/*.jar /databricks/jars + +EOF +``` + +## 创建 Databricks 集群 + +需要创建与 Sedona JAR 文件兼容的 Databricks 集群。如果使用基于 Scala 2.12 编译的 Sedona JAR，集群也必须运行 Scala 2.12。 + +进入 compute 选项卡并配置集群： + +![集群配置](../image/databricks/image4.png) + +设置正确的集群配置： + +![Spark 配置](../image/databricks/image5.png) + +下面是方便复制粘贴的集群配置项列表： + +``` +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 +spark.sedona.enableParserExtension false +``` + +指定初始化脚本的路径： + +![初始化脚本](../image/databricks/image6.png) + +如果您创建的是 Shared 集群，则无法使用存放在 Workspace 中的 init 脚本与 jar，请改为存放到 volume 中。整体流程保持一致。 + +在 Library 选项卡中加入所需依赖： + +![Python 库](../image/databricks/image7.png) + +完整库列表如下： + +``` +apache-sedona=={{ sedona.current_version }} +geopandas==1.0.1 +keplergl==0.3.7 +pydeck==0.9.1 +``` + +然后点击 “Create compute” 启动集群。 + +## 创建 Databricks notebook + +新建一个 Databricks notebook 并连接到刚才创建的集群。验证可以运行包含 Sedona 函数的 Python 计算： + +![Python 计算](../image/databricks/image1.png) + +如果您希望使用 Sedona 的 Python 函数，例如 [DataFrame API](../api/sql/DataFrameAPI.md) 或 [StructuredAdapter](../tutorial/sql.md#spatialrdd-to-dataframe-with-spatial-partitioning)，则需要按以下方式初始化 Sedona： + +```python +from sedona.spark import * + +sedona = SedonaContext.create(spark) +``` + +也可以使用 SQL API： + +![SQL 计算](../image/databricks/image8.png) + +## 在 Databricks Delta Lake 表中保存几何对象 + +下面演示如何创建带几何列的 Sedona DataFrame： + +```python +df = sedona.createDataFrame( + [ + ("a", "POLYGON((1.0 1.0,1.0 3.0,2.0 3.0,2.0 1.0,1.0 1.0))"), + ("b", "LINESTRING(4.0 1.0,4.0 2.0,6.0 4.0)"), + ("c", "POINT(9.0 2.0)"), + ], + ["id", "geometry"], +) +df = df.withColumn("geometry", expr("ST_GeomFromWKT(geometry)")) +``` + +将 Sedona DataFrame 写入 Delta Lake 表： + +```python +df.write.saveAsTable("your_org.default.geotable") +``` + +读取该表的方式：`sedona.table("your_org.default.geotable").display()` + +在 Databricks 中的结果大致如下： + +![写表](../image/databricks/image9.png) + +## 已知问题 + +为保证稳定性，建议使用当前在维护的长期支持（LTS）版本，例如 Databricks Runtime 16.4 LTS 或 15.4 LTS。部分 Databricks Runtime（如非 LTS 的 16.2）与 Apache Sedona 不兼容，原因是该运行时变更了 json4s 的依赖版本。 + +### Databricks 上的 H3 函数报错 + +Databricks Runtime 自带较旧的 H3 库（v3.x），与 Sedona 的 H3 函数（需要 H3 v4.x）不兼容。在调用 `ST_H3CellIDs`、`ST_H3CellDistance`、`ST_H3KRing`、`ST_H3ToGeom` 或其他 Sedona H3 函数时，如果出现类似报错： + +``` +java.lang.NoSuchMethodError: com.uber.h3core.H3Core.polygonToCells(...) +``` + +说明 Databricks 自带的 H3 库覆盖了 Sedona 携带的版本。 + +上文提供的初始化脚本中包含一个可选修复：取消 `rm -f /databricks/jars/*h3*.jar` 这一行的注释，先移除 Databricks 自带的 H3 JAR，再复制 Sedona 的 JAR。这样就可以使用 Sedona 的 H3 v4.x。 + +!!!note + 移除 Databricks 自带的 H3 JAR 会导致 Databricks 内置的 H3 SQL 表达式（如 `h3_coverash3`、`h3_boundaryaswkt`）失效。Sedona 提供了等价的 H3 函数可作为替代。 diff --git a/docs/setup/docker.zh.md b/docs/setup/docker.zh.md new file mode 100644 index 00000000000..cd5ce8847a7 --- /dev/null +++ b/docs/setup/docker.zh.md @@ -0,0 +1,179 @@ + + +# 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: +``` + +示例 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= -e EXECUTOR_MEM= -p 8888:8888 -p 8080:8080 -p 8081:8081 -p 4040:4040 -p 8085:8085 apache/sedona: +``` + +`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 }} +``` + +该命令会启动一个 driver 与 executor 各使用 4GB 内存的容器，并使用 Sedona {{ sedona.current_version }} 镜像。 + +容器的端口映射与示例 1 相同。 + +示例 3：使用 Docker volume 持久化 `/opt`（Jupyter & Zeppelin 数据） + +为确保 **Jupyter 工作区、Zeppelin notebook 与配置不会丢失**，可以将 `/opt` 挂载为 **Docker volume**： + +```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 \ + -v sedona_opt:/opt \ + apache/sedona:latest +``` + +- `-v sedona_opt:/opt` 会**创建（若不存在）并挂载名为 `sedona_opt` 的 Docker volume** 到容器内的 `/opt` 目录。 +- 即使容器被停止或删除，**Jupyter 与 Zeppelin 的 notebook、配置和工作区也会持久保留**。 + +### 开始编码 + +打开浏览器访问 [http://localhost:8888/](http://localhost:8888/)，即可在 Jupyter Notebook 中使用 Sedona 编码。也可以在浏览器中访问 [http://localhost:8085/classic/](http://localhost:8085/classic/) 来使用 Apache Zeppelin。 + +### 注意事项 + +- 该容器假设您的机器至少有 8GB 内存，并会占用所有 CPU 核心与 8GB 内存。1 个 worker 占用 4GB，Jupyter 程序占用剩余的 4GB。 +- 容器中的 Sedona 以集群模式运行，同一时间只能运行 1 个 notebook。如需运行其他 notebook，请先关闭当前 notebook 的内核（[操作方法](https://jupyterlab.readthedocs.io/en/stable/user/running.html)）。 + +## 构建方法 + +克隆 Sedona GitHub 仓库。 + +### 针对某个 Sedona 发布版构建镜像 + +要求：docker（[安装方法](https://docs.docker.com/engine/install/)） + +格式： + +```bash +./docker/build.sh +``` + +示例： + +```bash +./docker/build.sh 3.4.1 {{ sedona.current_version }} +``` + +`build_mode` 为可选项。如果未提供或值为 `local`，脚本会在本地构建镜像；否则会启动跨平台编译并直接将镜像推送到 DockerHub。 + +### 针对最新的 Sedona master 构建镜像 + +要求：docker（[安装方法](https://docs.docker.com/engine/install/)）、JDK <= 19、maven3 + +格式： + +```bash +./docker/build.sh latest +``` + +示例： + +```bash +./docker/build.sh 3.4.1 latest +``` + +`build_mode` 为可选项，含义与上文相同。 + +### 注意事项 + +该 Docker 镜像仅支持基于 Sedona 1.7.0+ 与 Spark 3.3+ 构建。 + +## 集群配置 + +### 软件 + +- OS：Ubuntu 22.02 +- JDK：openjdk-19 +- Python：3.10 +- Spark 3.5.5 + +### Web UI + +- JupyterLab：http://localhost:8888/ +- Spark master URL：spark://localhost:7077 +- Spark 作业 UI：http://localhost:4040 +- Spark master Web UI：http://localhost:8080/ +- Spark worker Web UI：http://localhost:8081/ +- Apache Zeppelin：http://localhost:8085/ + +容器中已捆绑一份 Zeppelin 教程 notebook，详情请参阅 [Sedona-Zeppelin 教程](../tutorial/zeppelin.md)。 + +## 如何推送到 DockerHub + +格式： + +```bash +docker login +./docker/build.sh release +``` + +示例： + +```bash +docker login +./docker/build.sh 3.4.1 {{ sedona.current_version }} release +``` diff --git a/docs/setup/emr.zh.md b/docs/setup/emr.zh.md new file mode 100644 index 00000000000..a0f251ccacc --- /dev/null +++ b/docs/setup/emr.zh.md @@ -0,0 +1,80 @@ + + +在 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 的版本后缀。 + +## 准备初始化脚本 + +在您的 S3 存储桶中添加一个内容如下的脚本： + +```bash +#!/bin/bash + +# EMR 集群只有临时的本地存储，jar 放在哪个路径其实并不影响。 +sudo mkdir /jars + +# 下载 Sedona jar +sudo curl -o /jars/sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}.jar "https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.3_2.12/{{ sedona.current_version }}/sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}.jar" + +# 下载 GeoTools jar +sudo curl -o /jars/geotools-wrapper-{{ sedona.current_geotools }}.jar "https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/{{ sedona.current_geotools }}/geotools-wrapper-{{ sedona.current_geotools }}.jar" + +# 安装必要的 Python 库 +sudo python3 -m pip install pandas +sudo python3 -m pip install shapely +sudo python3 -m pip install geopandas +sudo python3 -m pip install keplergl==0.3.2 +sudo python3 -m pip install pydeck==0.8.0 +sudo python3 -m pip install attrs matplotlib descartes apache-sedona=={{ sedona.current_version }} +``` + +创建 EMR 集群时，在 `bootstrap action` 中指定该脚本的位置。 + +## 添加软件配置 + +创建 EMR 集群时，在软件配置（software configuration）中加入以下内容： + +```bash +[ + { + "Classification":"spark-defaults", + "Properties":{ + "spark.yarn.dist.jars": "/jars/sedona-spark-shaded-3.3_2.12-{{ sedona.current_version }}.jar,/jars/geotools-wrapper-{{ sedona.current_geotools }}.jar", + "spark.serializer": "org.apache.spark.serializer.KryoSerializer", + "spark.kryo.registrator": "org.apache.sedona.core.serde.SedonaKryoRegistrator", + "spark.sql.extensions": "org.apache.sedona.viz.sql.SedonaVizExtensions,org.apache.sedona.sql.SedonaSqlExtensions" + } + } +] +``` + +## 验证安装 + +集群创建完成后，可在 Jupyter Notebook 中运行以下代码以验证安装： + +```python +spark.sql("SELECT ST_Point(0, 0)").show() +``` + +注意：您不需要再调用 `SedonaRegistrator.registerAll(spark)` 或 `SedonaContext.create(spark)`，因为配置中的 `org.apache.sedona.sql.SedonaSqlExtensions` 已经为您完成了这些工作。 diff --git a/docs/setup/fabric.zh.md b/docs/setup/fabric.zh.md new file mode 100644 index 00000000000..1a7acb9cfc5 --- /dev/null +++ b/docs/setup/fabric.zh.md @@ -0,0 +1,134 @@ + + +本教程将指引您在 Microsoft Fabric Synapse Data Engineering 的 Spark 环境中安装 Sedona。 + +## 步骤 1：打开 Microsoft Fabric Synapse Data Engineering + +进入 [Microsoft Fabric 门户](https://app.fabric.microsoft.com/)，选择 `Data Engineering` 选项。 + +![Microsoft Fabric 门户](../image/fabric/fabric-1.png) + +## 步骤 2：创建 Microsoft Fabric Data Engineering 环境 + +在左侧点击 `My Workspace`，再点击 `+ New` 新建一个 `Environment`，命名为 `ApacheSedona`。 + +![创建新的 Data Engineering 环境](../image/fabric/fabric-2.png) + +## 步骤 3：选择 Apache Spark 版本 + +在 `Environment` 页面，点击 `Home` 选项卡并选择合适的 Apache Spark 版本。后续需要根据这个版本安装匹配的 Apache Sedona 版本。 + +![在 Environment 页面 Home 选项卡中添加合适的 Apache Spark 版本](../image/fabric/fabric-3.png) + +## 步骤 4：安装 Sedona Python 包 + +在 `Environment` 页面，点击 `Public libraries` 选项卡，输入 `apache-sedona`，并选择合适的 Apache Sedona 版本，来源（source）选择 `PyPI`。 + +![在 Environment 页面的 Public libraries 中添加合适的 Apache Sedona 版本](../image/fabric/fabric-4.png) + +## 步骤 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` + +![在 Environment 页面 Spark properties 选项卡中添加 3 个配置项](../image/fabric/fabric-5.png) + +## 步骤 6：保存并发布环境 + +依次点击 `Save` 与 `Publish` 按钮以保存并发布环境，环境随之创建并安装好 Apache Sedona Python 包。发布过程大约需要 10 分钟。 + +![保存并发布环境](../image/fabric/fabric-6.png) + +## 步骤 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` 环境。 + +![在带有 Sedona 环境的 notebook 中安装 jar](../image/fabric/fabric-9.png) + +可在 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() +``` + +如果看到点的输出，则说明安装成功。 + +![验证安装](../image/fabric/fabric-10.png) + +## 可选：手动将 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-e24841492ab8@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-e24841492ab8@onelake.dfs.fabric.microsoft.com/e15f3695-af7e-47de-979e-473c3caa9f5b/Files/geotools-wrapper-1.5.1-28.2.jar +``` + +![Sedona notebook 中的 Lakehouses 数据源选项卡](../image/fabric/fabric-7.png) + +![从 Files 上传 jar 并复制其 ABFS 路径](../image/fabric/fabric-8.png) + +如使用此选项，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", + } +} +``` diff --git a/docs/setup/flink/install-python.zh.md b/docs/setup/flink/install-python.zh.md new file mode 100644 index 00000000000..784b345fc31 --- /dev/null +++ b/docs/setup/flink/install-python.zh.md @@ -0,0 +1,34 @@ + + +安装 Apache Sedona Python，请按以下步骤操作： + +1. 安装所需的 Python 包。 + +``` +pip install apache-sedona[flink] shapely attr +``` + +2. 从 Maven Central 下载所需的 JAR 文件： + +* sedona-flink-shaded_2.12:jar:{{ sedona.current_version }} +* geotools-wrapper-{{ sedona.current_geotools }}.jar + +要将这些 JAR 文件安装到您的 Flink 集群或 PyFlink 应用中，请参阅 Flink 官方文档： +https://nightlies.apache.org/flink/flink-docs-master/docs/dev/python/dependency_management/ diff --git a/docs/setup/flink/install-scala.zh.md b/docs/setup/flink/install-scala.zh.md new file mode 100644 index 00000000000..13e50fbc0b4 --- /dev/null +++ b/docs/setup/flink/install-scala.zh.md @@ -0,0 +1,33 @@ + + +在开始 Sedona 之旅之前，请确保您的 Apache Flink 集群已就绪。 + +随后即可创建一个独立的 Scala / Java 项目。独立项目可以让您创建多个 Scala / Java 文件，并将复杂的逻辑集中实现。 + +要在独立的 Flink 项目中使用 Sedona，只需在 `pom.xml` 或 `build.sbt` 中将 Sedona 添加为依赖。 + +1. 关于如何添加 Sedona 依赖，请参阅 [Sedona Maven Central 坐标](../maven-coordinates.md) +2. 阅读 [Sedona Flink 指南](../../tutorial/flink/sql.md)，并使用 Sedona 模板项目快速上手：[Sedona 模板项目](../../tutorial/demo.md) +3. 使用 Maven 编译您的项目，并确保得到打包了所有依赖的 fat jar。 +4. 将编译生成的 fat jar 提交到 Flink 集群。请确保位于 Flink 发行版的根目录，然后运行以下命令： + +``` +./bin/flink run /Path/To/YourJar.jar +``` diff --git a/docs/setup/flink/modules.zh.md b/docs/setup/flink/modules.zh.md new file mode 100644 index 00000000000..11bbf9aceb9 --- /dev/null +++ b/docs/setup/flink/modules.zh.md @@ -0,0 +1,33 @@ + + +# Apache Flink 上的 Sedona 模块 + +| 名称 | 介绍 | +|---------------|--------------------------------------------| +| flink | 空间 Table 与 DataStream 实现 | +| flink-shaded | shaded 版本 | + +## API 可用性 + +| | **DataStream** | **Table** | +|:----------:|:------------:|:-----------------:| +| Scala/Java |✅|✅| +| Python |否|否| +| R |否|否| diff --git a/docs/setup/flink/platform.zh.md b/docs/setup/flink/platform.zh.md new file mode 100644 index 00000000000..db98fb08595 --- /dev/null +++ b/docs/setup/flink/platform.zh.md @@ -0,0 +1,27 @@ + + +Sedona Flink 二进制版本由 Java 11/17 与 Scala 2.12 编译，已针对 Flink 1.12 - 1.19 进行测试。 + +**Java 要求：** + +- Flink 1.12 - 1.18：Java 11 +- Flink 1.19+：Java 17 + +**注意：** 自 Sedona 1.8.0 起不再支持 Java 8。 diff --git a/docs/setup/glue.zh.md b/docs/setup/glue.zh.md new file mode 100644 index 00000000000..789cc4a9c31 --- /dev/null +++ b/docs/setup/glue.zh.md @@ -0,0 +1,107 @@ + + +本教程介绍如何配置 Glue notebook 与 Glue ETL 作业。本文假设您已具备 AWS Glue 作业的基础使用经验。 + +教程中使用 Sedona {{ sedona.current_version }} 与 [Glue 5.0](https://docs.aws.amazon.com/glue/latest/dg/release-notes.html)，运行环境为 Spark 3.5.4、Java 17、Scala 2.12 和 Python 3.11。Glue 5.0 推荐使用 Sedona 1.8.0 及以上版本。 + +!!!warning + **重要：** 自 Sedona 1.8.0 起不再支持 Java 8 与 Spark 3.3。Sedona 1.8.0+ 需要 Glue 5.0+（支持 Java 17 与 Spark 3.5+）。如果您必须停留在 Glue 4.0（Spark 3.3、Java 8），请使用 Sedona 1.7.1 或更低版本，并将下方的 `sedona-spark-shaded-3.5_2.12` artifact 替换为 `sedona-spark-shaded-3.3_2.12`。 + +## 收集 Maven 链接 + +您需要让 Glue 作业指向 Sedona 与 Geotools 的 jar。推荐直接使用 Maven 上发布的 jar。下面给出的链接是为 Glue 5.0 准备的。 + +Sedona Jar：[Maven Central](https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/{{ sedona.current_version }}/sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar) + +Geotools Jar：[Maven Central](https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/{{ sedona.current_geotools }}/geotools-wrapper-{{ sedona.current_geotools }}.jar) + +!!!note + 请务必选择 Scala 2.12 与 Spark 3.5 的版本。Scala 2.13 的 jar 与 Glue 5.0 不兼容。 + +## 配置 Glue 作业 + +获得 jar 链接后，您可以将它们与 apache-sedona Python 包一起配置到 Glue 作业中。notebook 类型与 script 类型的作业配置方式略有不同。 + +!!!note + 请务必保持 jar 与 Python 包的 Sedona 版本一致。 + +### Notebook 作业 + +在创建 sparkContext 或 glueContext 之前，添加以下 cell magic。第一行指向 jar，第二行直接通过 pip 安装 Sedona Python 包。 + +```text +# Sedona Config +%extra_jars https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/{{ sedona.current_version }}/sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar, https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/{{ sedona.current_geotools }}/geotools-wrapper-{{ sedona.current_geotools }}.jar +%additional_python_modules apache-sedona=={{ sedona.current_version }} +``` + +如果您使用 Glue 提供的示例 notebook，则第一个 cell 现在大致应是： + +```text +%idle_timeout 2880 +%glue_version 5.0 +%worker_type G.1X +%number_of_workers 5 + +# Sedona Config +%extra_jars https://repo1.maven.org/maven2/org/apache/sedona/sedona-spark-shaded-3.5_2.12/{{ sedona.current_version }}/sedona-spark-shaded-3.5_2.12-{{ sedona.current_version }}.jar, https://repo1.maven.org/maven2/org/datasyslab/geotools-wrapper/{{ sedona.current_geotools }}/geotools-wrapper-{{ sedona.current_geotools }}.jar +%additional_python_modules apache-sedona=={{ sedona.current_version }} + + +import sys +from awsglue.transforms import * +from awsglue.utils import getResolvedOptions +from pyspark.context import SparkContext +from awsglue.context import GlueContext +from awsglue.job import Job + +sc = SparkContext.getOrCreate() +glueContext = GlueContext(sc) +spark = glueContext.spark_session +job = Job(glueContext) +``` + +可以通过运行以下 cell 验证安装： + +```python +from sedona.spark import * + +sedona = SedonaContext.create(spark) +sedona.sql("SELECT ST_POINT(1., 2.) as geom").show() +``` + +### ETL 作业 + +Glue 也将这种作业称为 Script 作业。在作业页面上切换到 “Job details” 选项卡，展开页面底部的 “Advanced properties” 部分。在 “Dependent JARs path” 字段中填入两个 jar 的链接，并以英文逗号分隔。 + +要添加 Sedona Python 包，进入 “Job Parameters” 部分新增一个参数，键为 `--additional-python-modules`，值为 `apache-sedona=={{ sedona.current_version }}`。 + +为验证安装，可在脚本中加入以下代码： + +```python +from sedona.spark import * + +config = SedonaContext.builder().getOrCreate() +sedona = SedonaContext.create(config) + +sedona.sql("SELECT ST_POINT(1., 2.) as geom").show() +``` + +将其加入脚本后保存并运行作业。如果作业运行成功，则说明安装成功。 diff --git a/docs/setup/install-python.zh.md b/docs/setup/install-python.zh.md new file mode 100644 index 00000000000..af03ba19dfe --- /dev/null +++ b/docs/setup/install-python.zh.md @@ -0,0 +1,122 @@ + + +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 }}," + "org.datasyslab:geotools-wrapper:{{ sedona.current_geotools }}", + ) + .getOrCreate() +) +SedonaRegistrator.registerAll(spark) +``` + +### 设置环境变量 + +如果您手动将 sedona-spark-shaded jar 复制到 `SPARK_HOME/jars/` 目录，则需要设置两个环境变量： + +* SPARK_HOME。例如，在终端运行： + +```bash +export SPARK_HOME=~/Downloads/spark-3.0.1-bin-hadoop2.7 +``` + +* PYTHONPATH。例如，在终端运行： + +```bash +export PYTHONPATH=$SPARK_HOME/python +``` + +之后即可体验 [Sedona Python Jupyter Notebook](../tutorial/jupyter-notebook.md)。 diff --git a/docs/setup/install-scala.zh.md b/docs/setup/install-scala.zh.md new file mode 100644 index 00000000000..acec355b750 --- /dev/null +++ b/docs/setup/install-scala.zh.md @@ -0,0 +1,94 @@ + + +在开始 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 + ``` + +## Spark SQL shell + +请参阅 [在纯 SQL 环境中使用 Sedona](../tutorial/sql-pure-sql.md)。 + +## 独立的 Spark 项目 + +独立项目可以让您创建多个 Scala / Java 文件，并将复杂的逻辑集中实现。要在独立的 Spark 项目中使用 Sedona，只需在 `pom.xml` 或 `build.sbt` 中将 Sedona 添加为依赖。 + +1. 关于如何添加 Sedona 依赖，请参阅 [Sedona Maven Central 坐标](maven-coordinates.md) +2. 使用 Sedona 模板项目快速上手：[Sedona 模板项目](../tutorial/demo.md) +3. 使用 SBT 编译您的项目，并确保得到打包了所有依赖的 fat jar。 +4. 将编译生成的 fat jar 提交到 Spark 集群。请确保位于 Spark 发行版的根目录，然后运行以下命令： + +``` +./bin/spark-submit --master spark://YOUR-IP:7077 /Path/To/YourJar.jar +``` + +!!!note + 关于 spark-submit 的详细说明请参见 [Spark 官方文档](https://spark.apache.org/docs/latest/submitting-applications.html)。 diff --git a/docs/setup/maven-coordinates.zh.md b/docs/setup/maven-coordinates.zh.md new file mode 100644 index 00000000000..96ae59b6a03 --- /dev/null +++ b/docs/setup/maven-coordinates.zh.md @@ -0,0 +1,382 @@ + + +# Maven 坐标 + +## 使用 Sedona shaded（fat）jar + +!!!warning + 对于 Scala/Java/Python 用户，这是在您的环境中使用 Sedona 最常见的方式。除非确认确实不需要 shaded jar，否则不要使用单独的 Sedona jar。 + +!!!warning + 对于 R 用户，这是在您的环境中使用 Sedona 的唯一方式。 + +Apache Sedona 针对每个受支持的 Spark 版本提供了不同的包。 + +请使用 artifact 名称中包含 Spark major.minor 版本号的 artifact。例如，对于 Spark 3.4，应使用 `sedona-spark-shaded-3.4_2.12`。 + +如果使用基于 Scala 2.13 编译的 Spark，则应使用对应的 Scala 2.13 版本，其后缀为 `_2.13`。 + +可选的 GeoTools 库仅在使用栅格算子时才需要。矢量 CRS 转换（ST_Transform）现在默认使用内置的 proj4sedona，无需 GeoTools。该 wrapper 库是 GeoTools 官方 jar 的再分发，目的仅是把 GeoTools jar 从 OSGEO 仓库带入 Maven Central。该库基于 GNU Lesser General Public License (LGPL) 协议，因此无法打包进 Sedona 官方发行版中。 + +!!! abstract "Sedona 与 Apache Spark + Scala 2.12" + + === "Spark 3.4 与 Scala 2.12" + + ```xml + + org.apache.sedona + sedona-spark-shaded-3.4_2.12 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 3.5 与 Scala 2.12" + + ```xml + + org.apache.sedona + sedona-spark-shaded-3.5_2.12 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + + === "Spark 4.0 与 Scala 2.12" + + ```xml + + org.apache.sedona + sedona-spark-shaded-4.0_2.12 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +!!! abstract "Sedona 与 Apache Spark + Scala 2.13" + + === "Spark 3.4 与 Scala 2.13" + + ```xml + + org.apache.sedona + sedona-spark-shaded-3.4_2.13 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 3.5 与 Scala 2.13" + + ```xml + + org.apache.sedona + sedona-spark-shaded-3.5_2.13 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + + === "Spark 4.0 与 Scala 2.13" + + ```xml + + org.apache.sedona + sedona-spark-shaded-4.0_2.13 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + + === "Spark 4.1 与 Scala 2.13" + + ```xml + + org.apache.sedona + sedona-spark-shaded-4.1_2.13 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +!!! abstract "Sedona 与 Apache Flink" + + === "Flink 1.12+ 与 Scala 2.12" + + ```xml + + org.apache.sedona + sedona-flink-shaded_2.12 + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +!!! abstract "Sedona 与 Snowflake" + + === "Snowflake 7.0+（2023 年及以后）" + + ```xml + + org.apache.sedona + sedona-snowflake + {{ sedona.current_version }} + + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +## 使用 Sedona unshaded jar + +!!!warning + Scala、Java、Python 用户仅在同时满足以下条件时才考虑使用下面的 jar：(1) 您知道如何在复杂应用中排除传递依赖；(2) 您的环境可以访问公网；(3) 您正在使用某种 Maven 包解析器，或 pom.xml/build.sbt，它通常以 `GroupID:ArtifactID:Version` 的形式接收输入。如果您不清楚以上含义，那么下面的 jar 不适合您。 + +Apache Sedona 针对每个受支持的 Spark 版本提供了不同的包。 + +请使用 artifact 名称中包含 Spark major.minor 版本号的 artifact。例如，对于 Spark 3.4，应使用 `sedona-spark-3.4_2.12`。 + +如果使用基于 Scala 2.13 编译的 Spark，则应使用对应的 Scala 2.13 版本（后缀为 `_2.13`）。 + +可选的 GeoTools 库仅在使用栅格算子时才需要。矢量 CRS 转换（ST_Transform）现在默认使用内置的 proj4sedona，无需 GeoTools。该 wrapper 库是 GeoTools 官方 jar 的再分发，目的仅是把 GeoTools jar 从 OSGEO 仓库带入 Maven Central。该库基于 GNU Lesser General Public License (LGPL) 协议，因此无法打包进 Sedona 官方发行版中。 + +!!! abstract "Sedona 与 Apache Spark + Scala 2.12" + + === "Spark 3.4 与 Scala 2.12" + ```xml + + org.apache.sedona + sedona-spark-3.4_2.12 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 3.5 与 Scala 2.12" + ```xml + + org.apache.sedona + sedona-spark-3.5_2.12 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 4.0 与 Scala 2.12" + ```xml + + org.apache.sedona + sedona-spark-4.0_2.12 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +!!! abstract "Sedona 与 Apache Spark + Scala 2.13" + + === "Spark 3.4 与 Scala 2.13" + ```xml + + org.apache.sedona + sedona-spark-3.4_2.13 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 3.5 与 Scala 2.13" + ```xml + + org.apache.sedona + sedona-spark-3.5_2.13 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 4.0 与 Scala 2.13" + ```xml + + org.apache.sedona + sedona-spark-4.0_2.13 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + === "Spark 4.1 与 Scala 2.13" + ```xml + + org.apache.sedona + sedona-spark-4.1_2.13 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +!!! abstract "Sedona 与 Apache Flink" + + === "Flink 1.12+ 与 Scala 2.12" + + ```xml + + org.apache.sedona + sedona-flink_2.12 + {{ sedona.current_version }} + + + org.datasyslab + geotools-wrapper + {{ sedona.current_geotools }} + + ``` + +Sedona Snowflake 没有 unshaded 版本。 + +### netCDF-Java 5.4.2 + +仅当您希望使用 `RS_FromNetCDF` 读取 HDF/NetCDF 文件时才需要此依赖。注意该 JAR 并未发布到 Maven Central，需要在 pom.xml 或 build.sbt 中加入对应仓库，或在 Spark 配置 `spark.jars.repositories` / `spark-submit --repositories` 中指定其 URL。 + +许可协议：BSD 3-clause（与 Apache 2.0 兼容）。 + +!!! abstract "添加 HDF/NetCDF 依赖" + + === "Sedona 1.3.1+" + + 在 pom.xml 中加入 unidata 仓库： + + ``` + + + unidata-all + Unidata All + https://artifacts.unidata.ucar.edu/repository/unidata-all/ + + + ``` + + 然后将 cdm-core 添加到 POM 依赖中： + + ```xml + + edu.ucar + cdm-core + 5.4.2 + + ``` + + === "Sedona 1.3.1 之前" + + ```xml + + + org.datasyslab + sernetcdf + 0.1.0 + + ``` + +## SNAPSHOT 版本 + +有时 Sedona 会为即将发布的版本提供 SNAPSHOT 版本。其命名规则与正式版相同，仅在版本号中以 “SNAPSHOT” 作为后缀，例如 `{{ sedona_create_release.current_snapshot }}`。 + +要下载 SNAPSHOT，需要在 pom.xml 或 build.sbt 中添加以下仓库： + +### build.sbt + +resolvers += + "Apache Software Foundation Snapshots" at "https://repository.apache.org/content/groups/snapshots" + +### pom.xml + +```xml + + + snapshots-repo + https://repository.apache.org/content/groups/snapshots + false + true + + +``` diff --git a/docs/setup/modules.zh.md b/docs/setup/modules.zh.md new file mode 100644 index 00000000000..ed3fa072552 --- /dev/null +++ b/docs/setup/modules.zh.md @@ -0,0 +1,35 @@ + + +# Apache Spark 上的 Sedona 模块 + +| 名称 | API | 介绍 | +|----------------|-----------------------|------------------------------------------------------| +| spark | RDD / SQL / DataFrame | SpatialRDD 与空间 DataFrame | +| spark-shaded | | Shaded 版本 | +| python | | SpatialRDD 与空间 DataFrame 的 Python 接口 | +| Zeppelin | Apache Zeppelin | 适用于 Apache Zeppelin 0.8.1+ 的插件 | + +## API 可用性 + +| | **Core/RDD** | **DataFrame/SQL** | **Viz RDD/SQL** | +|:----------:|:------------:|:-----------------:|:---------------:| +| Scala/Java |✅|✅|✅| +| Python |✅|✅|仅 SQL| +| R |✅|✅|✅| diff --git a/docs/setup/overview.zh.md b/docs/setup/overview.zh.md new file mode 100644 index 00000000000..7dfbea071fe --- /dev/null +++ b/docs/setup/overview.zh.md @@ -0,0 +1,55 @@ + + +# 下载统计 + +| 下载统计 | **Maven** | **PyPI** | Conda-forge | **CRAN** | **DockerHub** | +|----------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| Apache Sedona | 33 万次/月 | [![PyPI - Downloads](https://img.shields.io/pypi/dm/apache-sedona)](https://pepy.tech/project/apache-sedona) [![Downloads](https://static.pepy.tech/personalized-badge/apache-sedona?period=total&units=international_system&left_color=black&right_color=brightgreen&left_text=total%20downloads)](https://pepy.tech/project/apache-sedona) | [![Anaconda-Server Badge](https://anaconda.org/conda-forge/apache-sedona/badges/downloads.svg)](https://anaconda.org/conda-forge/apache-sedona) | [![CRAN downloads per month](https://cranlogs.r-pkg.org/badges/apache.sedona?color=brightgreen)](https://cran.r-project.org/package=apache.sedona) [![Total CRAN downloads](https://cranlogs.r-pkg.org/badges/grand-total/apache.sedona?color=brightgreen)](https://cran.r-project.org/package=apache.sedona) | [![Docker pulls](https://img.shields.io/docker/pulls/apache/sedona?color=brightgreen)](https://hub.docker.com/r/apache/sedona) | +| 已归档的 GeoSpark 版本 | 1 万次/月 | [![PyPI - Downloads](https://img.shields.io/pypi/dm/geospark)](https://pepy.tech/project/geospark)[![Downloads](https://static.pepy.tech/personalized-badge/geospark?period=total&units=international_system&left_color=black&right_color=brightgreen&left_text=total%20downloads)](https://pepy.tech/project/geospark) | | | | + +# Sedona 能做什么？ + +## 分布式空间数据集 + +- [x] Spark 上的空间 RDD +- [x] Spark 上的空间 DataFrame/SQL +- [x] Flink 上的空间 DataStream +- [x] Flink 上的空间 Table/SQL +- [x] Snowflake 上的空间 SQL + +## 复杂空间对象 + +- [x] 矢量几何对象 / 轨迹 +- [x] 支持地图代数（Map Algebra）的栅格图像 +- [x] 多种输入格式：CSV、TSV、WKT、WKB、GeoJSON、Shapefile、GeoTIFF、ArcGrid、NetCDF/HDF + +## 分布式空间查询 + +- [x] 空间查询：范围查询、范围连接查询、距离连接查询、K 最近邻查询 +- [x] 空间索引：R-Tree、Quad-Tree + +## 丰富的空间分析工具 + +- [x] 坐标参考系（CRS）/ 空间参考系（SRS）转换 +- [x] Apache Zeppelin 仪表盘集成 +- [X] 与 Jupyter Notebook、GeoPandas、Shapely 等多种 Python 工具集成 +- [X] 与 KeplerGL、DeckGL 等多种可视化工具集成 +- [x] 高分辨率、可扩展的地图生成：[可视化空间 DataFrame/RDD](../tutorial/viz.md) +- [x] 支持 Scala、Java、Python、R diff --git a/docs/setup/platform.zh.md b/docs/setup/platform.zh.md new file mode 100644 index 00000000000..0c51162b14e --- /dev/null +++ b/docs/setup/platform.zh.md @@ -0,0 +1,49 @@ + + +Sedona 二进制版本由 Java 11/17 与 Scala 2.12/2.13 编译，并在以下环境中经过测试： + +**Java 要求：** + +- Spark 3.4 与 3.5：Java 11 +- Spark 4.0 与 4.1：Java 17 + +**注意：** 自 Sedona 1.8.0 起不再支持 Java 8。自 Sedona 1.8.0 起不再支持 Spark 3.3。 + +=== "Sedona Scala/Java" + + | | Spark 3.4| Spark 3.5 | Spark 4.0 | Spark 4.1 | + |:---------:|:---------:|:---------:|:---------:|:---------:| + | Scala 2.12 |✅ |✅ |✅ | | + | Scala 2.13 |✅ |✅ |✅ |✅ | + +=== "Sedona Python" + + | | Spark 3.4 (Scala 2.12)|Spark 3.5 (Scala 2.12)| Spark 4.0 (Scala 2.13)| Spark 4.1 (Scala 2.13)| + |:---------:|:---------:|:---------:|:---------:|:---------:| + | Python 3.7 | ✅ | ✅ | | | + | Python 3.8 | ✅ | ✅ | | | + | Python 3.9 | ✅ | ✅ | ✅ | ✅ | + | Python 3.10 | ✅ | ✅ | ✅ | ✅ | + +=== "Sedona R" + + | | Spark 3.4 | Spark 3.5 | Spark 4.0 | Spark 4.1 | + |:---------:|:---------:|:---------:|:---------:|:---------:| + | Scala 2.12 | ✅ | ✅ | ✅ | | diff --git a/docs/setup/snowflake/install.zh.md b/docs/setup/snowflake/install.zh.md new file mode 100644 index 00000000000..48d83bd87ae --- /dev/null +++ b/docs/setup/snowflake/install.zh.md @@ -0,0 +1,116 @@ + + +!!! note + 本教程介绍如何在 Snowflake 上手动安装 Sedona。如果您不希望手动安装，可以使用由 [Wherobots](https://wherobots.com/) 发布的免费 [SedonaSnow](https://app.snowflake.com/marketplace/listing/GZTYZF0RTY3/wherobots-sedonasnow) 原生应用。 + +## 前置条件 + +要在 Snowflake 上安装 Sedona，需要准备一个 Snowflake 账号，以及一位至少能访问一个 `DATABASE` 并能运行至少一个 `WAREHOUSE` 的 Snowflake 用户。然后按照以下步骤进行安装。 + +如何创建 DATABASE 可参阅 [Snowflake 官方文档](https://docs.snowflake.com/en/sql-reference/sql/create-database)。 + +本教程使用如下 SQL 语句创建数据库；当然您也可以使用任意其他数据库： + +```sql +CREATE DATABASE SEDONA_TEST; +``` + +## 步骤 1：在数据库中创建 stage + +stage 是 Snowflake 中映射到云存储位置（如 Amazon S3、Azure Blob Storage、Google Cloud Storage）的对象，可用于将数据加载到表中或从表中卸载数据。 + +这里我们在上一步创建的数据库的 `public` schema 下创建一个名为 `ApacheSedona` 的 stage，用于上传 Sedona 的 JAR 文件。我们选择 `Snowflake managed` 类型的 stage。 + +![在数据库中创建 stage](../../image/snowflake/snowflake-1.png) + +创建后，您应能在数据库中看到该 stage： + +![在数据库中查看 stage](../../image/snowflake/snowflake-2.png) + +如何创建 stage 可参阅 [Snowflake 官方文档](https://docs.snowflake.com/en/sql-reference/sql/create-stage.html)。 + +## 步骤 2：将 Sedona 的 JAR 文件上传到 stage + +需要下载以下 2 个 JAR 文件： + +* sedona-snowflake-{{ sedona.current_version }}.jar：[Sedona 在 Maven Central 的仓库](https://central.sonatype.com/artifact/org.apache.sedona/sedona-snowflake/versions) +* geotools-wrapper-{{ sedona.current_geotools }}.jar：[GeoTools-wrapper 在 Maven Central 的仓库](https://central.sonatype.com/artifact/org.datasyslab/geotools-wrapper/versions) + +然后将这 2 个 JAR 文件上传到上一步创建的 stage 中。 + +上传完成后，您应能在 stage 中看到这 2 个文件： + +![stage 中的 2 个 JAR 文件](../../image/snowflake/snowflake-3.png) + +如何向 stage 上传文件可参阅 [Snowflake 官方文档](https://docs.snowflake.com/en/sql-reference/sql/put.html)。 + +## 步骤 3：在数据库中创建 schema + +schema 是 Snowflake 中映射到数据库的对象，可按业务功能或其他类别将表组织在一起。 + +这里我们在上一步的数据库下创建一个名为 `SEDONA` 的 schema，用于承载 Sedona 的函数。 + +![在数据库中创建 schema](../../image/snowflake/snowflake-4.png) + +随后即可在数据库中找到该 schema： + +![在数据库中查看 schema](../../image/snowflake/snowflake-5.png) + +如何创建 schema 可参阅 [Snowflake 官方文档](https://docs.snowflake.com/en/sql-reference/sql/create-schema.html)。 + +## 步骤 4：获取创建 Sedona 函数的 SQL 脚本 + +通过运行以下命令获取该 SQL 脚本： + +```bash +java -jar sedona-snowflake-{{ sedona.current_version }}.jar --geotools-version {{ sedona.current_geotools }} > sedona-snowflake.sql +``` + +其中 sedona-snowflake-{{ sedona.current_version }}.jar 即步骤 2 中下载的 JAR 文件。 + +## 步骤 5：运行 SQL 脚本以创建 Sedona 的函数 + +我们在上一步的数据库下创建一个 worksheet，并运行该 SQL 脚本以创建 Sedona 的函数。 + +这里我们选择 `Create Worksheet from SQL File` 选项。 + +![从 SQL 文件创建 Worksheet](../../image/snowflake/snowflake-6.png) + +在 worksheet 中将数据库选择为 `SEDONA_TEST`，schema 选择为 `PUBLIC`。SQL 脚本应已加载到 worksheet 中。然后右键点击 worksheet 选择 `Run All`。Snowflake 大约会用 3 分钟时间创建 Sedona 的函数。 + +![运行 SQL 脚本以创建 Sedona 函数](../../image/snowflake/snowflake-7.png) + +## 步骤 6：验证安装 + +打开新的 worksheet，将数据库选为 `SEDONA_TEST`，schema 任意。然后运行以下 SQL 语句： + +```sql +SELECT SEDONA.ST_AsEWKT(SEDONA.ST_SETSRID(SEDONA.ST_POINT(1, 2), 4326)); +``` + +应能看到如下结果： + +``` +SRID=4326;POINT (1 2) +``` + +worksheet 应类似下图： + +![验证安装的 worksheet 输出](../../image/snowflake/snowflake-8.png) diff --git a/docs/setup/snowflake/modules.zh.md b/docs/setup/snowflake/modules.zh.md new file mode 100644 index 00000000000..b386a1dd991 --- /dev/null +++ b/docs/setup/snowflake/modules.zh.md @@ -0,0 +1,32 @@ + + +# Snowflake 上的 Sedona 模块 + +| 名称 | 介绍 | +|-------------------|-----------------------------------------------| +| snowflake | 适用于 Snowflake 的空间 SQL 函数 | +| snowflake-tester | Sedona Snowflake 函数的自动化测试器 | + +## API 可用性 + +| | **Table** | +|:----------:|:-----------------:| +| SnowSQL |✅| +| Snowpark |✅| diff --git a/docs/setup/wherobots.zh.md b/docs/setup/wherobots.zh.md new file mode 100644 index 00000000000..a45f1197179 --- /dev/null +++ b/docs/setup/wherobots.zh.md @@ -0,0 +1,26 @@ + + +## WherobotsDB + +Wherobots Cloud 提供了对 WherobotsDB 的完全托管、完全预配置的云服务。WherobotsDB 是一套全面的空间分析数据库系统，您可以在云端托管的 Jupyter Notebook 中使用 Python、Java 或 Scala 内核进行体验，无需任何安装。 + +WherobotsDB 在公共 API 层面与 Apache Sedona 100% 兼容，并提供更丰富的功能与更优的性能。 + +将现有的 Sedona 工作流迁移到 [Wherobots Cloud](https://www.wherobots.com) 非常简单。请前往 [此处](https://cloud.wherobots.com/) 注册以创建账号。 diff --git a/docs/setup/zeppelin.zh.md b/docs/setup/zeppelin.zh.md new file mode 100644 index 00000000000..9101edb4715 --- /dev/null +++ b/docs/setup/zeppelin.zh.md @@ -0,0 +1,75 @@ + + +# 安装 Sedona-Zeppelin + +!!!warning + **已知问题**：由于 Leaflet JS 的限制，Sedona 在 Zeppelin 地图上只能将每个几何对象（点、线串和多边形）以点的形式绘制。如需可扩展且功能完整的可视化，请使用 SedonaViz 在 Zeppelin 地图上绘制散点图与热力图。 + +## 兼容性 + +Apache Spark 2.3+ + +Apache Zeppelin 0.8.1+ + +Sedona 1.0.0+：Sedona-core、Sedona-SQL、Sedona-Viz + +## 安装 + +!!!note + 仅当您在 Zeppelin Helium 包列表中找不到 [Apache-sedona](https://www.npmjs.com/package/apache-sedona) 或 [GeoSpark Zeppelin](https://www.npmjs.com/package/geospark-zeppelin) 时，才需要执行步骤 1 和 2。 + +### 创建 Helium 文件夹（可选） + +在 Zeppelin 根目录下创建一个名为 `helium` 的文件夹。 + +### 添加 Sedona-Zeppelin 描述（可选） + +在该文件夹中创建一个名为 `sedona-zeppelin.json` 的文件，并写入以下内容。请注意修改 artifact 路径！ + +``` +{ + "type": "VISUALIZATION", + "name": "sedona-zeppelin", + "description": "Zeppelin visualization support for Sedona", + "artifact": "/Absolute/Path/sedona/zeppelin", + "license": "BSD-2-Clause", + "icon": "" +} +``` + +### 启用 Sedona-Zeppelin + +重启 Zeppelin，然后打开 Zeppelin Helium 界面并启用 Sedona-Zeppelin。 + +![Enable Package](../image/enable-helium.gif) + +### 在 Zeppelin Spark 解释器中添加 Sedona 依赖 + +![add-geospark](../image/add-geospark-interpreter.gif) + +### 可视化 SedonaSQL 结果 + +![sql-zeppelin](../image/sql-zeppelin.gif) + +### 展示 SedonaViz 结果 + +![viz-zeppelin](../image/viz-zeppelin.gif) + +至此安装完成！请阅读 [Sedona-Zeppelin 教程](../tutorial/zeppelin.md) 查看完整的实操示例。