(sedona) branch master updated: [GH-1781] Document parameterized spatial SQL queries (#3387)

[ji...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jiayuasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sedona.git


The following commit(s) were added to refs/heads/master by this push:
     new f02a8514d58 [GH-1781] Document parameterized spatial SQL queries (#3387)
f02a8514d58 is described below

commit f02a8514d58e7e60f235b90b2ced5a6456b76dbb
Author: Jia Yu <ji...@apache.org>
AuthorDate: Mon Sep 21 23:50:07 2026 -0700

    [GH-1781] Document parameterized spatial SQL queries (#3387)
---
 docs/tutorial/sql.md    | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/tutorial/sql.zh.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)

diff --git a/docs/tutorial/sql.md b/docs/tutorial/sql.md
index b7213741b99..169c22a85f6 100644
--- a/docs/tutorial/sql.md
+++ b/docs/tutorial/sql.md
@@ -139,6 +139,54 @@ Add the following line after creating Sedona config. If you already have a Spark
 
 You can also register everything by passing `--conf spark.sql.extensions=org.apache.sedona.sql.SedonaSqlExtensions` to `spark-submit` or `spark-shell`.
 
+## Parameterized queries (Python)
+
+`sedona.sql` supports the named parameters provided by [SparkSession.sql](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.SparkSession.sql.html). Bind values through `args` instead of inserting them into SQL strings with f-strings or concatenation. Pass a DataFrame as a keyword argument to reference it through a `{placeholder}`; Spark manages the temporary view for you.
+
+```python
+points = sedona.sql("""
+    SELECT 1 AS id, ST_Point(1D, 1D) AS geometry
+    UNION ALL
+    SELECT 2 AS id, ST_Point(5D, 5D) AS geometry
+""")
+region_wkt = "POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))"
+
+result = sedona.sql(
+    """
+    SELECT id
+    FROM {points}
+    WHERE ST_Intersects(geometry, ST_GeomFromWKT(:region))
+    """,
+    args={"region": region_wkt},
+    points=points,
+)
+result.show()
+```
+
+```text
++---+
+| id|
++---+
+|  1|
++---+
+```
+
+Leave both `:region` and `{points}` unquoted. `:region` binds the WKT string as a SQL value, while `{points}` references the DataFrame.
+
+Shapely geometry objects cannot be bound directly. Pass `geometry.wkt` to `ST_GeomFromWKT`, or bind `geometry.wkb` and use `ST_GeomFromWKB`:
+
+```python
+from shapely.geometry import Point
+
+geometry = Point(1, 1)
+result = sedona.sql(
+    "SELECT ST_AsText(ST_GeomFromWKB(:geometry)) AS wkt",
+    args={"geometry": geometry.wkb},
+)
+print(result.first().wkt)
+# POINT (1 1)
+```
+
 ## Load data from text files
 
 Assume we have a WKT file, namely `usa-county.tsv`, at Path `/Download/usa-county.tsv` as follows:
diff --git a/docs/tutorial/sql.zh.md b/docs/tutorial/sql.zh.md
index 1c2b3122d2e..90c7fc4d1dc 100644
--- a/docs/tutorial/sql.zh.md
+++ b/docs/tutorial/sql.zh.md
@@ -139,6 +139,54 @@ SedonaSQL 详细 API 说明请参阅 [SedonaSQL API](../api/sql/Overview.md)。
 
 也可以通过在 `spark-submit` 或 `spark-shell` 中传入 `--conf spark.sql.extensions=org.apache.sedona.sql.SedonaSqlExtensions` 完成注册。
 
+## 参数化查询（Python）
+
+`sedona.sql` 支持 [SparkSession.sql](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.SparkSession.sql.html) 提供的命名参数。请通过 `args` 绑定值，而不要用 f-string 或字符串拼接将值插入 SQL。可以将 DataFrame 作为关键字参数传入，并通过 `{占位符}` 引用；Spark 会自动管理临时视图。
+
+```python
+points = sedona.sql("""
+    SELECT 1 AS id, ST_Point(1D, 1D) AS geometry
+    UNION ALL
+    SELECT 2 AS id, ST_Point(5D, 5D) AS geometry
+""")
+region_wkt = "POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))"
+
+result = sedona.sql(
+    """
+    SELECT id
+    FROM {points}
+    WHERE ST_Intersects(geometry, ST_GeomFromWKT(:region))
+    """,
+    args={"region": region_wkt},
+    points=points,
+)
+result.show()
+```
+
+```text
++---+
+| id|
++---+
+|  1|
++---+
+```
+
+不要给 `:region` 或 `{points}` 加引号。`:region` 将 WKT 字符串绑定为 SQL 值，`{points}` 则引用 DataFrame。
+
+不能直接绑定 Shapely 几何对象。可以将 `geometry.wkt` 传给 `ST_GeomFromWKT`，或绑定 `geometry.wkb` 并使用 `ST_GeomFromWKB`：
+
+```python
+from shapely.geometry import Point
+
+geometry = Point(1, 1)
+result = sedona.sql(
+    "SELECT ST_AsText(ST_GeomFromWKB(:geometry)) AS wkt",
+    args={"geometry": geometry.wkb},
+)
+print(result.first().wkt)
+# POINT (1 1)
+```
+
 ## 从文本文件加载数据
 
 假设有一个 WKT 文件 `usa-county.tsv`，路径为 `/Download/usa-county.tsv`，内容如下：