geo_within_radius

Generic Description

Computes point, distance, or containment helpers for location-aware values. It is documented separately because coordinate shape, distance units, and containment assumptions need to be visible in the query text.

Simple example:

RETURN geo_within_radius(48.8566, 2.3522, 48.8570, 2.3530, 120.0) AS nearby

Consumer-Level Explanation

Use it when location math should stay visible next to graph filters and document payloads. Prefer this function when the location calculation is part of filtering, ranking, or audit evidence rather than display-only formatting.

More Detailed Explanation

geo_within_radius should be understood by the value shape it expects and the row shape it returns. It composes with MATCH, WHERE, WITH, RETURN, and procedure output, so planner-facing documentation should describe both the immediate value transformation and why it belongs in the database query.

Advanced Example

This example uses geo_within_radius inside a named row pipeline so the value shape is clear to both the planner and reviewers.

MATCH (d:Device {id: 'runner-1-watch'})
WITH id(d) AS device_id
CALL nexyron.temporal_history(device_id, 'position', 1713430800000, 1713434400000)
YIELD ts, value
WHERE geo_within_radius(value.lat, value.lon, 48.8568, 2.3526, 120.0)
RETURN ts, value.lat AS lat, value.lon AS lon
ORDER BY ts

Real Use Cases

• keeping value shaping visible to the planner and reviewers
• combining graph structure with document-style payload handling
• returning named, typed fields that downstream tooling can reason about

Real Limitations And Tradeoffs

• the function does not repair incorrectly modeled input values
• nearby aliases may be clearer if they express the business intent more directly
• broad use inside hot filters should be reviewed for cost and index interaction