[GH-2830] Adds Geography dual-dispatch to ST_NumGeometries (#2851)

Author: zhangfengcdt

common/src/main/java/org/apache/sedona/common/geography/Functions.java

@@ -85,6 +85,12 @@ public static int nPoints(Geography g) {
     return toJTS(g).getNumPoints();
   }
 
+  /** Return the number of sub-geometries in a geography (1 for singles). */
+  public static int numGeometries(Geography g) {
+    if (g == null) return 0;
+    return toJTS(g).getNumGeometries();
+  }
+
   /** Return the geometry type string of a geography, prefixed with "ST_". */
   public static String geometryType(Geography g) {
     if (g == null) return null;

common/src/test/java/org/apache/sedona/common/Geography/FunctionTest.java

@@ -148,6 +148,37 @@ public void nPoints_polygon() throws ParseException {
     assertEquals(5, Functions.nPoints(g));
   }
 
+  @Test
+  public void numGeometries_point() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POINT (1 2)", 4326);
+    assertEquals(1, Functions.numGeometries(g));
+  }
+
+  @Test
+  public void numGeometries_polygon() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))", 4326);
+    assertEquals(1, Functions.numGeometries(g));
+  }
+
+  @Test
+  public void numGeometries_multipoint() throws ParseException {
+    Geography g = Constructors.geogFromWKT("MULTIPOINT ((0 0), (1 1), (2 2))", 4326);
+    assertEquals(3, Functions.numGeometries(g));
+  }
+
+  @Test
+  public void numGeometries_multipolygon() throws ParseException {
+    Geography g =
+        Constructors.geogFromWKT(
+            "MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((2 2, 3 2, 3 3, 2 3, 2 2)))", 4326);
+    assertEquals(2, Functions.numGeometries(g));
+  }
+
+  @Test
+  public void numGeometries_nullHandling() {
+    assertEquals(0, Functions.numGeometries(null));
+  }
+
   @Test
   public void geometryType_point() throws ParseException {
     Geography g = Constructors.geogFromWKT("POINT (1 2)", 4326);

docs/api/sql/geography/Geography-Functions.md

@@ -46,5 +46,6 @@ These functions operate on geography type objects.
 | [ST_Envelope](Geography-Functions/ST_Envelope.md) | Geography | Return the bounding box (envelope) of a geography. Supports anti-meridian splitting. | v1.8.0 |
 | [ST_GeometryType](Geography-Functions/ST_GeometryType.md) | String | Return the type of a geography as a string (e.g., "ST_Point", "ST_Polygon"). | v1.9.1 |
 | [ST_NPoints](Geography-Functions/ST_NPoints.md) | Integer | Return the number of points (vertices) in a geography. | v1.9.0 |
+| [ST_NumGeometries](Geography-Functions/ST_NumGeometries.md) | Integer | Return the number of sub-geometries in a geography (1 for single geometries). | v1.9.1 |
 | [ST_Distance](Geography-Functions/ST_Distance.md) | Double | Return the minimum geodesic distance between two geographies in meters. | v1.9.0 |
 | [ST_Contains](Geography-Functions/ST_Contains.md) | Boolean | Test whether geography A fully contains geography B. | v1.9.0 |

docs/api/sql/geography/Geography-Functions/ST_NumGeometries.md

@@ -0,0 +1,42 @@
+<!--
+ 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.
+ -->
+
+# ST_NumGeometries
+
+Introduction: Returns the number of sub-geometries in a geography object. Returns 1 for single geometries (Point, LineString, Polygon).
+
+Format:
+
+`ST_NumGeometries (A: Geography)`
+
+Return type: `Integer`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_NumGeometries(ST_GeogFromWKT('MULTIPOINT ((0 0), (1 1), (2 2))'));
+```
+
+Output:
+
+```
+3
+```

spark/common/src/main/scala/org/apache/spark/sql/sedona_sql/expressions/Functions.scala

@@ -1055,16 +1055,19 @@ private[apache] object ST_IsRing {
 }
 
 /**
- * Returns the number of Geometries. If geometry is a GEOMETRYCOLLECTION (or MULTI*) return the
- * number of geometries, for single geometries will return 1
+ * Returns the number of sub-geometries. For a GEOMETRYCOLLECTION or MULTI* input, returns the
+ * number of component geometries; for single geometries returns 1. Supports both Geometry (JTS)
+ * and Geography (S2) inputs via InferredExpression dual dispatch.
  *
- * This method implements the SQL/MM specification. SQL-MM 3: 9.1.4
+ * For Geometry inputs this method implements the SQL/MM specification (SQL-MM 3: 9.1.4).
  *
  * @param inputExpressions
- *   Geometry
+ *   Geometry or Geography
  */
 private[apache] case class ST_NumGeometries(inputExpressions: Seq[Expression])
-    extends InferredExpression(Functions.numGeometries _) {
+    extends InferredExpression(
+      inferrableFunction1(Functions.numGeometries),
+      inferrableFunction1(org.apache.sedona.common.geography.Functions.numGeometries)) {
 
   protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
     copy(inputExpressions = newChildren)

spark/common/src/test/scala/org/apache/sedona/sql/geography/GeographyFunctionTest.scala

@@ -78,7 +78,7 @@ class GeographyFunctionTest extends TestBaseScala {
     }
   }
 
-  // ─── Level 1: ST_NPoints, ST_GeometryType, ST_AsText ───────────────────
+  // ─── Level 1: ST_NPoints, ST_NumGeometries, ST_GeometryType, ST_AsText ──
 
   describe("Level 1: Structural") {
 
@@ -89,6 +89,21 @@ class GeographyFunctionTest extends TestBaseScala {
       assertEquals(3, row.getInt(0))
     }
 
+    it("ST_NumGeometries single") {
+      val row = sparkSession
+        .sql("SELECT ST_NumGeometries(ST_GeogFromWKT('POINT (1 2)', 4326)) AS n")
+        .first()
+      assertEquals(1, row.getInt(0))
+    }
+
+    it("ST_NumGeometries multipoint") {
+      val row = sparkSession
+        .sql(
+          "SELECT ST_NumGeometries(ST_GeogFromWKT('MULTIPOINT ((0 0), (1 1), (2 2))', 4326)) AS n")
+        .first()
+      assertEquals(3, row.getInt(0))
+    }
+
     it("ST_GeometryType point") {
       val row = sparkSession
         .sql("SELECT ST_GeometryType(ST_GeogFromWKT('POINT (1 2)', 4326)) AS t")