You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sedona.apache.org by ji...@apache.org on 2026/08/19 04:32:26 UTC
(sedona) branch master updated: [GH-3263] Deprecate the ST_Force_2D alias function name (#3264)
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 5b487873248 [GH-3263] Deprecate the ST_Force_2D alias function name (#3264)
5b487873248 is described below
commit 5b487873248032b2e967cb44b76ed6029c8b7312
Author: James Willis <ja...@users.noreply.github.com>
AuthorDate: Tue Aug 18 21:32:20 2026 -0700
[GH-3263] Deprecate the ST_Force_2D alias function name (#3264)
---
docs/api/sql/Geometry-Editors/ST_Force2D.md | 2 +-
docs/api/sql/Geometry-Editors/ST_Force_2D.md | 5 ++-
docs/api/sql/Geometry-Functions.md | 4 +--
python/sedona/spark/geopandas/geoseries.py | 2 +-
python/sedona/spark/sql/st_functions.py | 9 +++++
.../expressions/DeprecationWarning.scala | 40 ++++++++++++++++++++++
.../sql/sedona_sql/expressions/Functions.scala | 1 +
.../sql/sedona_sql/expressions/st_functions.scala | 2 ++
8 files changed, 60 insertions(+), 5 deletions(-)
diff --git a/docs/api/sql/Geometry-Editors/ST_Force2D.md b/docs/api/sql/Geometry-Editors/ST_Force2D.md
index 343a094158a..8586b594104 100644
--- a/docs/api/sql/Geometry-Editors/ST_Force2D.md
+++ b/docs/api/sql/Geometry-Editors/ST_Force2D.md
@@ -19,7 +19,7 @@
# ST_Force2D
-Introduction: Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This function is an alias of [ST_Force_2D](ST_Force_2D.md).
+Introduction: Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. [ST_Force_2D](ST_Force_2D.md) is a deprecated alias of this function.

diff --git a/docs/api/sql/Geometry-Editors/ST_Force_2D.md b/docs/api/sql/Geometry-Editors/ST_Force_2D.md
index afe90542e03..350e17b90ee 100644
--- a/docs/api/sql/Geometry-Editors/ST_Force_2D.md
+++ b/docs/api/sql/Geometry-Editors/ST_Force_2D.md
@@ -19,7 +19,10 @@
# ST_Force_2D
-Introduction: Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This function is an alias of [ST_Force2D](ST_Force2D.md).
+!!!warning
+ `ST_Force_2D` is deprecated since `v2.0.0` and will be removed in a future release. Use [ST_Force2D](ST_Force2D.md) instead.
+
+Introduction: Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This function is a deprecated alias of [ST_Force2D](ST_Force2D.md).

diff --git a/docs/api/sql/Geometry-Functions.md b/docs/api/sql/Geometry-Functions.md
index 5ba08875185..1778b0d8dda 100644
--- a/docs/api/sql/Geometry-Functions.md
+++ b/docs/api/sql/Geometry-Functions.md
@@ -113,12 +113,12 @@ These functions create modified geometries by changing type, structure, or verti
| [ST_Collect](Geometry-Editors/ST_Collect.md) | Geometry | Returns MultiGeometry object based on geometry column/s or array with geometries | v1.2.0 |
| [ST_CollectionExtract](Geometry-Editors/ST_CollectionExtract.md) | Geometry | Returns a homogeneous multi-geometry from a given geometry collection. | v1.2.1 |
| [ST_FlipCoordinates](Geometry-Editors/ST_FlipCoordinates.md) | Geometry | Returns a version of the given geometry with X and Y axis flipped. | v1.0.0 |
-| [ST_Force2D](Geometry-Editors/ST_Force2D.md) | Geometry | Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This function is an alias of [ST_Force_2D](Geometry-Editors/ST_Force_2D.md). | v1.8.0 |
+| [ST_Force2D](Geometry-Editors/ST_Force2D.md) | Geometry | Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. | v1.8.0 |
| [ST_Force3D](Geometry-Editors/ST_Force3D.md) | Geometry | Forces the geometry into a 3-dimensional model so that all output representations will have X, Y and Z coordinates. An optionally given zValue is tacked onto the geometry if the geometry is 2-dimen... | v1.4.1 |
| [ST_Force3DM](Geometry-Editors/ST_Force3DM.md) | Geometry | Forces the geometry into XYM mode. Retains any existing M coordinate, but removes the Z coordinate if present. Assigns a default M value of 0.0 if `mValue` is not specified. | v1.6.1 |
| [ST_Force3DZ](Geometry-Editors/ST_Force3DZ.md) | Geometry | Forces the geometry into a 3-dimensional model so that all output representations will have X, Y and Z coordinates. An optionally given zValue is tacked onto the geometry if the geometry is 2-dimen... | v1.6.1 |
| [ST_Force4D](Geometry-Editors/ST_Force4D.md) | Geometry | Converts the input geometry to 4D XYZM representation. Retains original Z and M values if present. Assigning 0.0 defaults if `mValue` and `zValue` aren't specified. The output contains X, Y, Z, and... | v1.6.1 |
-| [ST_Force_2D](Geometry-Editors/ST_Force_2D.md) | Geometry | Forces the geometries into a "2-dimensional mode" so that all output representations will only have the X and Y coordinates. This function is an alias of [ST_Force2D](Geometry-Editors/ST_Force2D.md). | v1.2.1 |
+| [ST_Force_2D](Geometry-Editors/ST_Force_2D.md) | Geometry | Deprecated alias of [ST_Force2D](Geometry-Editors/ST_Force2D.md); use that function instead. | v1.2.1 |
| [ST_ForceCollection](Geometry-Editors/ST_ForceCollection.md) | Geometry | This function converts the input geometry into a GeometryCollection, regardless of the original geometry type. If the input is a multipart geometry, such as a MultiPolygon or MultiLineString, it wi... | v1.6.1 |
| [ST_ForcePolygonCCW](Geometry-Editors/ST_ForcePolygonCCW.md) | Geometry | Sets polygon exterior rings counter-clockwise and interior rings clockwise, including polygonal members nested in GeometryCollections. Non-polygonal members are preserved unchanged. | v1.6.0 |
| [ST_ForcePolygonCW](Geometry-Editors/ST_ForcePolygonCW.md) | Geometry | Sets polygon exterior rings clockwise and interior rings counter-clockwise, including polygonal members nested in GeometryCollections. Non-polygonal members are preserved unchanged. | v1.6.0 |
diff --git a/python/sedona/spark/geopandas/geoseries.py b/python/sedona/spark/geopandas/geoseries.py
index 9cebfac44b0..59fc5774a96 100644
--- a/python/sedona/spark/geopandas/geoseries.py
+++ b/python/sedona/spark/geopandas/geoseries.py
@@ -2492,7 +2492,7 @@ class GeoSeries(GeoFrame, pspd.Series):
return self._query_geometry_column(spark_expr, returns_geom=True)
def force_2d(self) -> "GeoSeries":
- spark_expr = stf.ST_Force_2D(self.spark.column)
+ spark_expr = stf.ST_Force2D(self.spark.column)
return self._query_geometry_column(spark_expr, returns_geom=True)
def force_3d(self, z=0.0) -> "GeoSeries":
diff --git a/python/sedona/spark/sql/st_functions.py b/python/sedona/spark/sql/st_functions.py
index e93b0caf7ce..8690e46461a 100644
--- a/python/sedona/spark/sql/st_functions.py
+++ b/python/sedona/spark/sql/st_functions.py
@@ -16,6 +16,7 @@
# under the License.
import inspect
import sys
+import warnings
from functools import partial
from typing import Optional, Union
@@ -750,11 +751,19 @@ def ST_FlipCoordinates(geometry: ColumnOrName) -> Column:
def ST_Force_2D(geometry: ColumnOrName) -> Column:
"""Force the geometry column to only output two dimensional representations.
+ .. deprecated:: 2.0.0
+ Use :py:func:`ST_Force2D` instead.
+
:param geometry: Geometry column to force to be 2D.
:type geometry: ColumnOrName
:return: Geometry column identical to geometry except with only X and Y coordinates.
:rtype: Column
"""
+ warnings.warn(
+ "ST_Force_2D is deprecated. Use ST_Force2D instead.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
return _call_st_function("ST_Force_2D", geometry)
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/DeprecationWarning.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/DeprecationWarning.scala
new file mode 100644
index 00000000000..b6745c839aa
--- /dev/null
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/DeprecationWarning.scala
@@ -0,0 +1,40 @@
+/*
+ * 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.
+ */
+package org.apache.spark.sql.sedona_sql.expressions
+
+import java.util.concurrent.ConcurrentHashMap
+import org.slf4j.LoggerFactory
+
+/**
+ * Emits a single warning per JVM when a deprecated SQL function name is used, pointing the user
+ * at the canonical name. A runtime warning is the only channel that reaches SQL users, who never
+ * see Scala `@deprecated` annotations.
+ */
+private[expressions] object DeprecationWarning {
+ private val LOGGER = LoggerFactory.getLogger(getClass)
+ private val warned = ConcurrentHashMap.newKeySet[String]()
+
+ def warnOnce(deprecatedName: String, canonicalName: String): Unit = {
+ if (warned.add(deprecatedName)) {
+ LOGGER.warn(
+ s"The function $deprecatedName is deprecated and will be removed in a future release. " +
+ s"Use $canonicalName instead.")
+ }
+ }
+}
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
index d0e4904ef9a..557f7212298 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala
@@ -1511,6 +1511,7 @@ private[apache] case class ST_PointN(inputExpressions: Seq[Expression])
*/
private[apache] case class ST_Force_2D(inputExpressions: Seq[Expression])
extends InferredExpression(Functions.force2D _) {
+ DeprecationWarning.warnOnce("ST_Force_2D", "ST_Force2D")
protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
copy(inputExpressions = newChildren)
diff --git a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
index f0d1edf8900..89c17ef93e0 100644
--- a/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
+++ b/spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/st_functions.scala
@@ -244,7 +244,9 @@ object st_functions {
def ST_FlipCoordinates(geometry: Column): Column = wrapExpression[ST_FlipCoordinates](geometry)
def ST_FlipCoordinates(geometry: String): Column = wrapExpression[ST_FlipCoordinates](geometry)
+ @deprecated("Use ST_Force2D instead", "2.0.0")
def ST_Force_2D(geometry: Column): Column = wrapExpression[ST_Force_2D](geometry)
+ @deprecated("Use ST_Force2D instead", "2.0.0")
def ST_Force_2D(geometry: String): Column = wrapExpression[ST_Force_2D](geometry)
def ST_Force2D(geometry: Column): Column = wrapExpression[ST_Force2D](geometry)