Add row-level geo distance check and fix documentation examples

[simplegaurav]

Changes

Adds is_geo_within_distance, a row-level geospatial check that flags values farther than a
maximum geodesic distance from a reference geography.

Distance is measured in meters along the WGS 84 ellipsoid via st_distance on GEOGRAPHY
values, so the check is meaningful for global data where planar GEOMETRY distances are not.
A row is reported when the shortest distance to the reference is strictly greater than distance.

- criticality: error
  check:
    function: is_geo_within_distance
    arguments:
      column: location
      reference_geometry: "POINT(4.90 52.37)"
      distance: 1000
      convert_column: true
      convert_reference_geometry: true

Behaviour

• reference_geometry accepts a literal WKT/WKB/EWKT/EWKB string or bytes value, or a Column
  expression. A plain string is always a literal, never a column name.
• distance accepts a non-negative number, a Column, or a string SQL expression, so the radius
  can vary per row.
• Null column values are skipped. Rows where distance evaluates to null are also skipped, since
  the comparison is unknown rather than violated.
• Unparseable column values and an unparseable reference are reported with separate messages,
  so the error names the value that actually has to be fixed.
• Numeric distance literals are validated up front: negative, NaN, infinite and boolean values
  raise InvalidParameterError. (bool is a subclass of int, so it is rejected explicitly
  rather than silently becoming a 0/1 metre radius.)

Consistency with existing geo checks

• convert_column / convert_reference_geometry default to False, matching every existing
  is_geo_* relationship check, so the two are not surprising to switch between.
• The alias is <column>_is_not_within_distance_from_reference_geometry, following the
  _reference_geometry suffix family. Including the reference in the alias also avoids a
  collision when the same column is checked against two different radii.
• How the offending value is rendered follows the input contract: the raw value when the input is
  converted from WKT/WKB (where st_astext would be NULL on exactly the unparseable values the
  message is about), and st_astext when the column is already a native GEOGRAPHY.

Second commit — pre-existing documentation bug

The programmatic examples for seven is_geo_* checks (is_geo_contains, is_geo_covers ×2,
is_geo_intersects ×2, is_geo_touches, is_geo_within) construct rules with DQDatasetRule,
but all of these are registered with @register_rule("row"). Copying the snippets as written
fails:

InvalidCheckError: Function 'is_geo_within' is not a dataset-level rule. Use DQRowRule instead.

Fixed to DQRowRule plus the missing import. are_polygons_mutually_disjoint is a genuine
dataset-level rule and is left unchanged. These examples are not covered by
test_apply_checks_all_geo_checks_using_classes, which is why it went unnoticed.

Tests

• manually tested
• added unit tests
• added integration tests
• added end-to-end tests
• added performance tests

Unit (tests/unit/test_geo_check_funcs.py) — literal and Column references, WKB reference,
Column and SQL-expression distances, zero distance, parametrized rejection of negative / NaN /
±inf / boolean distances, and alias assertions for both the converted and native-GEOGRAPHY paths.
Registered in EXPECTED_PARAMETER_ORDER in tests/unit/test_check_func_signatures.py.

Integration (tests/integration/test_row_checks_geo.py) — inside radius, on the reference at
zero radius, outside radius, per-row radius via a column, null radius skipped, and the invalid
column and invalid reference paths asserted separately. Added to
tests/resources/all_row_geo_checks.yaml and to test_apply_checks_all_geo_checks_using_classes.

Performance (tests/perf/test_apply_checks.py) — test_benchmark_is_geo_within_distance,
alongside the existing is_geo_covers benchmarks.

Documentation and Demos

• added/updated demos
• added/updated docs
• added/updated agent skills

docs/dqx/docs/reference/quality_checks.mdx — added the row-level checks table entry, a YAML
usage example, and a programmatic DQRowRule example, each placed at the end of the geo group.
Also contains the DQDatasetRule → DQRowRule fix described above.

[CLAassistant]

All committers have signed the CLA.

[github-actions]

All commits in PR should be signed ('git commit -S ...'). See https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits

[ghanse]

Very good contribution. Left a few minor comments. Need to add 1 test case.

[ghanse]

We should include GeoJSON in the supported formats as well.

[ghanse]

I think we're missing a test case for convert_column=False

[simplegaurav]

Thanks for the review — all three addressed in 3ce2ddd6.

GeoJSON in supported formats

Good catch. The docstring listed the try_to_geometry formats (WKT, WKB, EWKT, EWKB) that I'd
copied from the sibling relationship checks, but this check parses with try_to_geography, which
also accepts GeoJSON. Updated in three places: the docstring, the reference_geometry argument
description, and the row-level checks table in quality_checks.mdx.

Missing convert_column=False test

Added two integration tests covering the native GEOGRAPHY path — one pass case, one violation:

def test_is_geo_within_distance_native_geography_violation(skip_if_runtime_not_geo_compatible, spark):
    """A native GEOGRAPHY value outside the radius is flagged, with the value rendered via st_astext."""
    point = "POINT(5.05 52.37)"
    test_df = spark.createDataFrame([[point]], _GEO_SCHEMA).select(
        F.call_function("try_to_geography", F.col("geom")).alias("geom")
    )
    condition = is_geo_within_distance("geom", F.call_function("try_to_geography", F.lit(_POINT_INSIDE)), 1000)
    ...

They build the column with try_to_geography in a select and then leave both convert flags at
their defaults, so the check receives a genuinely GEOGRAPHY-typed column. The violation case also
exercises the st_astext rendering branch, which is only reachable on that path — with
convert_column=True the message renders the raw input instead, since st_astext returns NULL for
exactly the unparseable values the invalid-geography message is about.

I assert on the condition column alone rather than also selecting geom, since a GEOGRAPHY-typed
column can't be compared against a string schema.

One thing I noticed while writing those

No test in the repo currently builds a native GEOGRAPHY column. Every is_geo_* check defaults to
convert_column=False, but all existing tests pass True, so the default path is untested across
the geo module rather than just here. Might be worth a companion issue to #1513 — happy to open one
if useful.

Thanks for opening #1513.

[ghanse]

Left a few minor suggestions.

[ghanse]

This may not leave the most useful messages if the user passes WKB/EWKB with convert_column=True. For other checks, we surround the parsed geometry with st_astext:

Suggested change

	text_value_col = col_expr.cast("string") if convert_column else F.call_function("st_astext", col_geog)
	invalid_column_message = F.concat_ws(
	"",
	F.lit("value `"),
	text_value_col,
	F.lit(f"` in column `{col_expr_str}` is not a valid geography"),
	)
	invalid_reference_message = F.lit(f"reference geometry for column `{col_expr_str}` is not a valid geography")
	too_far_message = F.concat_ws(
	"",
	F.lit("value `"),
	text_value_col,
	F.lit(f"` in column `{col_expr_str}` is farther than "),
	distance_expr.cast("string"),
	F.lit(" meters from the reference geometry"),
	)
	text_value_col = col_expr.cast("string") if convert_column else F.call_function("st_astext", col_geog)
	invalid_column_message = F.concat_ws(
	"",
	F.lit("value `"),
	text_value_col,
	F.lit(f"` in column `{col_expr_str}` is not a valid geography"),
	)
	invalid_reference_message = F.lit(f"reference geometry for column `{col_expr_str}` is not a valid geography")
	too_far_value_col = F.call_function("st_astext", col_geog)
	too_far_message = F.concat_ws(
	"",
	F.lit("value `"),
	too_far_value_col,
	F.lit(f"` in column `{col_expr_str}` is farther than "),
	distance_expr.cast("string"),
	F.lit(" meters from the reference geometry"),
	)

[ghanse]

math.isfinite may overflow on very large input distances. We might want to catch this and raise InvalidParameterError?