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.
 
 ![ST_Force2D](../../../image/ST_Force2D/ST_Force2D.svg "ST_Force2D")
 
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).
 
 ![ST_Force_2D](../../../image/ST_Force_2D/ST_Force_2D.svg "ST_Force_2D")
 
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)