[GH-2830] Adds Geography implementations for ST_Within and ST_DWithin

[zhangfengcdt]

Did you read the Contributor Guide?

• Yes, I have read the Contributor Rules and Contributor Development Guide

Is this PR related to a ticket?

• Yes, and the PR name follows the format [GH-XXX] my subject. Closes #<issue_number>

What changes were proposed in this PR?

• ST_DWithin(A, B, d) — returns true iff the minimum geodesic distance between Geographies A
  and B (in meters) is <= d. Delegates to the existing Functions.distance(Geography, Geography),
  which uses S2ClosestEdgeQuery on the two ShapeIndexGeographys and already has point-point /
  point-complex fast paths; the new dWithin simply compares the returned meters against the threshold.
  Match is inclusive (<=) and has no short-circuit, identical to sedona-db's
  s2_distance-then-compare flow. 3-arg only — the Geometry-side useSpheroid 4th argument has no
  Geography analogue because Geography is already spherical.

• ST_Within(A, B) — returns true iff Geography A is fully inside B on the sphere. Implemented
  as contains(B, A), the OGC identity. The underlying contains path runs S2BooleanOperation
  containment over two ShapeIndexGeographys via the existing Predicates helper. The Catalyst
  ST_Within case class is migrated from ST_Predicate + CodegenFallback to InferredExpression
  dual-dispatch (same migration already applied to ST_Contains); JoinQueryDetector is updated to
  match it at the outer level with a Geography guard so spatial-join planning continues to skip
  Geography inputs.

How was this patch tested?

• `mvn -pl common -Dtest=FunctionTest test
• GeographyFunctionTest gains SQL + DataFrame API coverage for both functions

Did this PR include necessary documentation updates?

• Yes, I have updated the documentation.

[zhangfengcdt]

Notes about sedona-db compatability:

Both implementations reduce ST_DWithin(A, B, d) to comparing the minimum geodesic distance between two geography entities using S2ClosestEdgeQuery over each side's S2ShapeIndex. sedona-db calls this via its C++ s2_distance helper; Sedona reuses the existing Functions.distance(Geography, Geography), which wraps Distance.S2_distance(ShapeIndexGeography, ShapeIndexGeography) — the same S2 query, just in Java.

Neither implementation short-circuits via S2ClosestEdgeQuery::Options::set_max_distance; both compute the full minimum and compare. Boundary semantics (<=), point fast paths (S1Angle for point-point, PointTarget for point-complex), and null propagation therefore line up exactly — the Java version is a thin shim over the same S2 primitive.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 12 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.