[GH-2830] Adds ST_Buffer for the Geography type via dual-dispatch (#2865)

Author: zhangfengcdt

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

@@ -199,6 +199,53 @@ public static String asEWKT(Geography geography) {
     return geography.toEWKT();
   }
 
+  // ─── Level 4: spherical buffer ───────────────────────────────────────────
+
+  /**
+   * Returns a Geography that represents the metric ε-buffer of {@code g} on the sphere, where
+   * {@code radiusMeters} is interpreted as meters along the spheroid. Implementation reuses the
+   * existing geometry-side spheroidal buffer (UTM project → JTS planar buffer → unproject), which
+   * gives accurate sub-UTM-zone results; for very large geographies the UTM round-trip's accuracy
+   * caveats apply (see ST_Buffer's docs).
+   */
+  public static Geography buffer(Geography g, double radiusMeters) {
+    return buffer(g, radiusMeters, "");
+  }
+
+  /**
+   * Geography is inherently spheroidal, so the {@code useSpheroid} flag (only meaningful for the
+   * planar Geometry version of ST_Buffer) is rejected for Geography inputs. This overload exists to
+   * give a clear, actionable error when callers try to pass it; without it the resolver would
+   * coerce the boolean to a string and fail later inside the buffer-parameters parser with a
+   * confusing message.
+   */
+  public static Geography buffer(Geography g, double radiusMeters, boolean useSpheroid) {
+    throw new IllegalArgumentException(
+        "ST_Buffer does not accept a useSpheroid argument for Geography inputs (Geography is "
+            + "always spheroidal). Use ST_Buffer(geog, distance) or "
+            + "ST_Buffer(geog, distance, parameters) instead.");
+  }
+
+  /**
+   * Same as {@link #buffer(Geography, double)} but allows a JTS-style buffer parameters string
+   * ({@code "quad_segs=8 endcap=round join=round mitre_limit=5.0 side=both"}). The string is parsed
+   * by the existing geometry-side parser.
+   */
+  public static Geography buffer(Geography g, double radiusMeters, String parameters) {
+    if (g == null) return null;
+    Geometry jts = toJTS(g);
+    if (jts == null) return null;
+    int srid = g.getSRID();
+    // Geography is always lon/lat; default to WGS84 when the source has no SRID set.
+    jts.setSRID(srid != 0 ? srid : 4326);
+    Geometry buffered =
+        org.apache.sedona.common.Functions.buffer(jts, radiusMeters, true, parameters);
+    if (buffered == null) return null;
+    Geography result = Constructors.geomToGeography(buffered);
+    result.setSRID(srid);
+    return result;
+  }
+
   // ─── Helpers ───────────────────────────────────────────────────────────────
 
   private static Geometry toJTS(Geography g) {

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

@@ -332,4 +332,66 @@ public void contains_nullHandling() throws ParseException {
     assertFalse(Functions.contains(g1, null));
     assertFalse(Functions.contains(null, g1));
   }
+
+  // ─── Level 4: ST_Buffer ──────────────────────────────────────────────────
+
+  @Test
+  public void buffer_nullInputReturnsNull() throws ParseException {
+    assertNull(Functions.buffer(null, 100.0));
+    assertNull(Functions.buffer(null, 100.0, "quad_segs=4"));
+  }
+
+  @Test
+  public void buffer_pointProducesEnclosingPolygon() throws ParseException {
+    Geography origin = Constructors.geogFromWKT("POINT (0 0)", 4326);
+    Geography buffered = Functions.buffer(origin, 1000.0); // 1 km on the sphere
+    assertNotNull(buffered);
+    assertEquals("ST_Polygon", Functions.geometryType(buffered));
+    // A point ~785 m NE of origin should fall inside the 1 km buffer.
+    Geography near = Constructors.geogFromWKT("POINT (0.005 0.005)", 4326);
+    assertTrue(Functions.contains(buffered, near));
+    // A point ~1.57 km NE should fall outside.
+    Geography far = Constructors.geogFromWKT("POINT (0.01 0.01)", 4326);
+    assertFalse(Functions.contains(buffered, far));
+  }
+
+  @Test
+  public void buffer_polygonContainsOriginalInterior() throws ParseException {
+    Geography poly =
+        Constructors.geogFromWKT("POLYGON ((0 0, 0.01 0, 0.01 0.01, 0 0.01, 0 0))", 4326);
+    Geography buffered = Functions.buffer(poly, 200.0);
+    assertNotNull(buffered);
+    Geography inside = Constructors.geogFromWKT("POINT (0.005 0.005)", 4326);
+    assertTrue("buffered polygon must contain its centroid", Functions.contains(buffered, inside));
+    // A point 500 m beyond the original polygon's edge but inside the 200 m band would still
+    // be outside; pick a point far enough that the buffer cannot reach it.
+    Geography farOutside = Constructors.geogFromWKT("POINT (1 1)", 4326);
+    assertFalse(Functions.contains(buffered, farOutside));
+  }
+
+  @Test
+  public void buffer_parametersStringHonored() throws ParseException {
+    // quad_segs=2 produces a low-fidelity buffer (octagon for a point); quad_segs=64
+    // produces a much smoother boundary. Vertex counts should differ accordingly.
+    Geography origin = Constructors.geogFromWKT("POINT (0 0)", 4326);
+    Geography coarse = Functions.buffer(origin, 1000.0, "quad_segs=2");
+    Geography fine = Functions.buffer(origin, 1000.0, "quad_segs=64");
+    assertNotNull(coarse);
+    assertNotNull(fine);
+    assertTrue(
+        "fine buffer should have more vertices than coarse",
+        Functions.nPoints(fine) > Functions.nPoints(coarse));
+  }
+
+  @Test
+  public void buffer_negativeRadiusShrinksPolygon() throws ParseException {
+    Geography poly =
+        Constructors.geogFromWKT("POLYGON ((0 0, 0.01 0, 0.01 0.01, 0 0.01, 0 0))", 4326);
+    Geography shrunk = Functions.buffer(poly, -100.0);
+    assertNotNull(shrunk);
+    // Shrunk polygon is either smaller or empty; the original boundary point should now
+    // be outside (or contains() returns false on an empty geometry, which is also acceptable).
+    Geography boundary = Constructors.geogFromWKT("POINT (0 0)", 4326);
+    assertFalse(Functions.contains(shrunk, boundary));
+  }
 }

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

@@ -44,6 +44,7 @@ These functions operate on geography type objects.
 | [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_Buffer](Geography-Functions/ST_Buffer.md) | Geography | Return the metric ε-buffer of a geography. Distance is always interpreted as meters along the spheroid. | 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 |
 | [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 |

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

@@ -0,0 +1,93 @@
+<!--
+ 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_Buffer
+
+Introduction: Returns a `Geography` whose interior is the metric ε-buffer of the input on the sphere. The `distance` argument is always interpreted as **meters** along the spheroid — there is no `useSpheroid` flag because `Geography` is inherently spheroidal.
+
+![ST_Buffer of a Geography point on the sphere](../../../../image/ST_Buffer_geography/ST_Buffer_geography_point.svg "ST_Buffer of a Geography point on the sphere")
+![ST_Buffer of a Geography polygon on the sphere](../../../../image/ST_Buffer_geography/ST_Buffer_geography_polygon.svg "ST_Buffer of a Geography polygon on the sphere")
+
+Internally, Sedona projects the input to the most appropriate UTM zone (selected via `ST_BestSRID`), applies a planar buffer in that zone, and projects the result back to lon/lat. This produces accurate results for inputs that fit inside a single UTM zone (~6° wide). For larger inputs the same accuracy caveats apply as for `ST_Buffer` on `Geometry` with `useSpheroid = true`.
+
+Format:
+
+`ST_Buffer (geog: Geography, distanceMeters: Double)`
+
+`ST_Buffer (geog: Geography, distanceMeters: Double, parameters: String)`
+
+Return type: `Geography`
+
+Since: `v1.9.1`
+
+!!! note "`useSpheroid` is not accepted for Geography inputs"
+    The 3-argument form `ST_Buffer(geom, distance, useSpheroid: Boolean)` from the `Geometry`
+    overload is **rejected** when the first argument is a `Geography`. Geography is inherently
+    spheroidal, so the flag would be either redundant (`useSpheroid = true`) or contradictory
+    (`useSpheroid = false`). A call like
+
+    ```sql
+    SELECT ST_Buffer(ST_GeogFromWKT('POINT(0 0)', 4326), 1000.0, true);  -- ❌ throws
+    ```
+
+    raises:
+
+    ```
+    IllegalArgumentException: ST_Buffer does not accept a useSpheroid argument for
+    Geography inputs (Geography is always spheroidal). Use ST_Buffer(geog, distance) or
+    ST_Buffer(geog, distance, parameters) instead.
+    ```
+
+    Drop the `useSpheroid` argument, or — if you really want a planar buffer — convert to
+    Geometry first via `ST_GeogToGeometry` and use the `Geometry` overload of `ST_Buffer`.
+
+The optional `parameters` string accepts the same JTS-style key/value pairs used by `ST_Buffer` for `Geometry`:
+
+| Key | Default | Allowed values |
+| :--- | :--- | :--- |
+| `quad_segs` | `8` | positive integer — segments per quadrant in curved corners |
+| `endcap` | `round` | `round`, `flat`, `butt`, `square` |
+| `join` | `round` | `round`, `mitre` (or `miter`), `bevel` |
+| `mitre_limit` (or `miter_limit`) | `5.0` | positive decimal |
+| `side` | `both` | `both`, `left`, `right` (single-sided buffer for linestrings) |
+
+Notes:
+
+- A negative `distanceMeters` shrinks polygons (returning a smaller polygon, possibly `EMPTY` when the radius exceeds the polygon's narrowest dimension); for points and lines a negative buffer always produces an empty result.
+- The output `Geography` preserves the input's SRID. If the input has no SRID set, the result is normalised to WGS84 (EPSG:4326).
+
+SQL Example
+
+```sql
+-- 1 km buffer around a point
+SELECT ST_AsText(ST_Buffer(ST_GeogFromWKT('POINT(0 0)', 4326), 1000));
+
+-- 200 m buffer around a polygon, with low-fidelity corners
+SELECT ST_AsText(ST_Buffer(
+  ST_GeogFromWKT('POLYGON((0 0, 0.01 0, 0.01 0.01, 0 0.01, 0 0))', 4326),
+  200,
+  'quad_segs=4 endcap=square'
+));
+
+-- Use the buffer as a containment test
+SELECT ST_Contains(
+  ST_Buffer(ST_GeogFromWKT('POINT(0 0)', 4326), 1000),
+  ST_GeogFromWKT('POINT(0.005 0.005)', 4326)
+);
+```

docs/image/ST_Buffer_geography/ST_Buffer_geography_point.svg

@@ -86,6 +86,12 @@ object FunctionResolver {
           // All arguments are NullType literals; every overload returns null, so the choice
           // between equally-good matches is semantically irrelevant. Prefer the first candidate.
           ambiguousMatches.head._1
+        } else if (expressions.headOption.exists(_.dataType == NullType)) {
+          // The first argument (the geometry/geography input) is a NullType literal. All
+          // ST_* overloads return null on null input, so the dispatch choice is again
+          // semantically irrelevant — prefer the first registered candidate. This keeps
+          // calls like `ST_Buffer(null, 0)` working after Geography overloads were added.
+          ambiguousMatches.head._1
         } else {
           val ambiguousTypesMsg = ambiguousMatches
             .map { case (function, _) =>

docs/image/ST_Buffer_geography/ST_Buffer_geography_polygon.svg

@@ -192,7 +192,17 @@ private[apache] case class ST_Buffer(inputExpressions: Seq[Expression])
     extends InferredExpression(
       inferrableFunction2(Functions.buffer),
       inferrableFunction3(Functions.buffer),
-      inferrableFunction4(Functions.buffer)) {
+      inferrableFunction4(Functions.buffer),
+      inferrableFunction2(org.apache.sedona.common.geography.Functions.buffer),
+      // Explicit type ascription disambiguates the two 3-arg Geography buffer overloads
+      // (`(Geography, double, String)` for the JTS-style parameters string, and
+      // `(Geography, double, boolean)` which throws a clear error if `useSpheroid` is passed).
+      inferrableFunction3(
+        org.apache.sedona.common.geography.Functions
+          .buffer(_: org.apache.sedona.common.S2Geography.Geography, _: Double, _: String)),
+      inferrableFunction3(
+        org.apache.sedona.common.geography.Functions
+          .buffer(_: org.apache.sedona.common.S2Geography.Geography, _: Double, _: Boolean))) {
 
   protected def withNewChildrenInternal(newChildren: IndexedSeq[Expression]) = {
     copy(inputExpressions = newChildren)