[GH-2830] Adds Geography dual-dispatch to ST_Area (#2853)

Author: zhangfengcdt

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

@@ -105,6 +105,52 @@ public static String asText(Geography g) {
 
   // ─── Level 2: JTS + S2 geodesic metrics ──────────────────────────────────
 
+  /**
+   * Spherical area in square meters of a geography, calculated on the sphere. The Earth is modeled
+   * as a sphere of radius {@link Haversine#AVG_EARTH_RADIUS}; the polygon's interior is integrated
+   * along great-circle edges and scaled by R squared. Multi-polygons sum the children's areas;
+   * geography collections recurse. Returns {@code 0.0} for point/line geographies and for {@code
+   * null}.
+   */
+  public static double area(Geography g) {
+    if (g == null) return 0.0;
+    Geography typed = (g instanceof WKBGeography) ? ((WKBGeography) g).getS2Geography() : g;
+    double steradians = sphericalArea(typed);
+    // S2 polygons can be wound either CCW (interior is the small side) or CW (interior is the
+    // complement on the sphere). Some WKT inputs land in the latter form after parsing, which
+    // makes S2 report the entire sphere minus the visible polygon. Always return the smaller
+    // of the two regions so the answer is bounded by half the surface of the sphere.
+    if (steradians > 2.0 * Math.PI) {
+      steradians = 4.0 * Math.PI - steradians;
+    }
+    return steradians * Haversine.AVG_EARTH_RADIUS * Haversine.AVG_EARTH_RADIUS;
+  }
+
+  /** Steradian area of {@code g} on the unit sphere; 0 for non-areal kinds. */
+  private static double sphericalArea(Geography g) {
+    if (g instanceof PolygonGeography) {
+      return ((PolygonGeography) g).polygon.getArea();
+    }
+    if (g instanceof MultiPolygonGeography) {
+      double sum = 0.0;
+      for (Geography feature : ((MultiPolygonGeography) g).getFeatures()) {
+        if (feature instanceof PolygonGeography) {
+          sum += ((PolygonGeography) feature).polygon.getArea();
+        }
+      }
+      return sum;
+    }
+    if (g instanceof GeographyCollection) {
+      double sum = 0.0;
+      for (Geography feature : ((GeographyCollection) g).getFeatures()) {
+        sum += sphericalArea(feature);
+      }
+      return sum;
+    }
+    // Points and polylines have zero area
+    return 0.0;
+  }
+
   /**
    * Geometry-to-geometry geodesic distance in meters. Uses S2ClosestEdgeQuery for true minimum
    * distance between any two points on the geometries (not centroid-to-centroid). Consistent with

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

@@ -239,7 +239,57 @@ public void asText_nullHandling() {
     assertNull(Functions.asText(null));
   }
 
-  // ─── Level 2: ST_Distance ────────────────────────────────────────────────
+  // ─── Level 2: ST_Area, ST_Distance ───────────────────────────────────────
+
+  @Test
+  public void area_unitBoxAtEquator() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))", 4326);
+    double area = Functions.area(g);
+    // S2 spherical area of a 1°x1° box near equator on a sphere of radius
+    // Haversine.AVG_EARTH_RADIUS = 6371008.0 m. Slightly larger than the WGS84-ellipsoid
+    // value (~1.231e10 m²) by the spheroid/sphere correction (~0.5%). Tolerance of 1e7 m²
+    // (~0.08%) is well above floating-point drift but tight enough to catch a model swap.
+    assertEquals(1.2364e10, area, 1e7);
+  }
+
+  @Test
+  public void area_rightTriangleAtOrigin() throws ParseException {
+    // Right triangle with vertices (0,0), (0,1), (1,0). The polygon is wound clockwise in
+    // lat/lon space, which would let a naïve sphere area function return the complementary
+    // region (almost the whole Earth, ~5.1e14 m²). Asserting the small-side value (~6.18e9 m²)
+    // proves the orientation-collapse branch is doing its job.
+    Geography g = Constructors.geogFromWKT("POLYGON ((0 0, 0 1, 1 0, 0 0))", 4326);
+    double area = Functions.area(g);
+    assertEquals(6.182489e9, area, 1e6);
+  }
+
+  @Test
+  public void area_multipolygon_sumsChildren() throws ParseException {
+    Geography g =
+        Constructors.geogFromWKT(
+            "MULTIPOLYGON (((0 0, 1 0, 1 1, 0 1, 0 0)), ((10 10, 11 10, 11 11, 10 11, 10 10)))",
+            4326);
+    double area = Functions.area(g);
+    // ~1.236e10 (1°² near equator) + ~1.216e10 (1°² near 10°N). Tolerance 5e7 m² ~ 0.2%.
+    assertEquals(2.452e10, area, 5e7);
+  }
+
+  @Test
+  public void area_point_returnsZero() throws ParseException {
+    Geography g = Constructors.geogFromWKT("POINT (1 2)", 4326);
+    assertEquals(0.0, Functions.area(g), 0.0);
+  }
+
+  @Test
+  public void area_linestring_returnsZero() throws ParseException {
+    Geography g = Constructors.geogFromWKT("LINESTRING (0 0, 1 1)", 4326);
+    assertEquals(0.0, Functions.area(g), 0.0);
+  }
+
+  @Test
+  public void area_nullHandling() {
+    assertEquals(0.0, Functions.area(null), 0.0);
+  }
 
   @Test
   public void distance_twoPoints() throws ParseException {

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

@@ -41,6 +41,7 @@ These functions operate on geography type objects.
 
 | Function | Return type | Description | Since |
 | :--- | :--- | :--- | :--- |
+| [ST_Area](Geography-Functions/ST_Area.md) | Double | Return the geodesic area of a geography in square meters (WGS84 spheroid). | v1.9.1 |
 | [ST_AsEWKT](Geography-Functions/ST_AsEWKT.md) | String | Return the Extended Well-Known Text representation of a geography. | v1.8.0 |
 | [ST_AsText](Geography-Functions/ST_AsText.md) | String | Return the Well-Known Text (WKT) representation of a geography. | v1.9.1 |
 | [ST_Envelope](Geography-Functions/ST_Envelope.md) | Geography | Return the bounding box (envelope) of a geography. Supports anti-meridian splitting. | v1.8.0 |

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

@@ -0,0 +1,56 @@
+<!--
+ 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_Area
+
+Introduction: Returns the spherical area of a geography in square meters, calculated on the sphere. The Earth is modeled as a sphere of radius `R = 6 371 008 m` (the authalic Earth radius); the result is the area of the polygon's interior on that sphere. Returns `0.0` for non-areal geographies (points, linestrings) and for `NULL`.
+
+Multi-polygons sum the children's areas; geography collections recurse into their members.
+
+![ST_Area on a Geography on the sphere](../../../../image/ST_Area_geography/ST_Area_geography.svg "ST_Area on a Geography (sphere-native)")
+
+The result is the area of the polygon's user-intended interior. If the input ring happens to be wound in the orientation that would describe the rest of the planet instead, Sedona returns the smaller of the two regions, so the answer is always bounded by half the surface of the Earth (~2.55 × 10¹⁴ m²).
+
+If you specifically want the WGS84 ellipsoidal value (which is ~0.5 % lower for typical shapes), convert via `ST_GeogToGeometry` first and use the geometry overload:
+
+```sql
+SELECT ST_Area(ST_GeogToGeometry(geog), true) FROM …;
+```
+
+Format:
+
+`ST_Area (A: Geography)`
+
+Return type: `Double`
+
+Since: `v1.9.1`
+
+SQL Example
+
+```sql
+SELECT ST_Area(ST_GeogFromWKT('POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))'));
+```
+
+Output (in m²):
+
+```
+1.2364028804392242E10
+```
+
+That is approximately 12,364 km² — the spherical area of a 1°×1° box near the equator.

docs/image/ST_Area_geography/ST_Area_geography.svg

@@ -268,12 +268,17 @@ private[apache] case class ST_Length2D(inputExpressions: Seq[Expression])
 }
 
 /**
- * Return the area measurement of a Geometry.
+ * Return the area measurement of a Geometry or Geography. Supports both Geometry (JTS, planar
+ * area in the input's coordinate units) and Geography (S2, geodesic area in square meters on the
+ * WGS84 spheroid) via InferredExpression dual dispatch.
  *
  * @param inputExpressions
+ *   Geometry or Geography
  */
 private[apache] case class ST_Area(inputExpressions: Seq[Expression])
-    extends InferredExpression(Functions.area _) {
+    extends InferredExpression(
+      inferrableFunction1(Functions.area),
+      inferrableFunction1(org.apache.sedona.common.geography.Functions.area)) {
 
   protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
     copy(inputExpressions = newChildren)

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

@@ -130,10 +130,28 @@ class GeographyFunctionTest extends TestBaseScala {
     }
   }
 
-  // ─── Level 2: ST_Distance ──────────────────────────────────────────────
+  // ─── Level 2: ST_Area, ST_Distance ─────────────────────────────────────
 
   describe("Level 2: Geodesic metrics") {
 
+    it("ST_Area unit box at equator") {
+      val row = sparkSession
+        .sql("SELECT ST_Area(ST_GeogFromWKT('POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))', 4326)) AS a")
+        .first()
+      val area = row.getDouble(0)
+      // Spherical area of a 1°×1° box near the equator on a sphere of radius 6371008.0 m.
+      // Tolerance 1e7 m² (~0.08%) absorbs floating-point drift while staying tight enough to
+      // catch a model swap.
+      assertEquals(1.2364e10, area, 1e7)
+    }
+
+    it("ST_Area of a point returns 0") {
+      val row = sparkSession
+        .sql("SELECT ST_Area(ST_GeogFromWKT('POINT (1 2)', 4326)) AS a")
+        .first()
+      assertEquals(0.0, row.getDouble(0), 0.0)
+    }
+
     it("ST_Distance between two points") {
       val row = sparkSession
         .sql("""