geoparquet_find_nearest
Find the nearest features to a point, sorted by distance with great-circle kilometers. Specify a center coordinate and radius to get the closest matches within that area.
Instructions
Return the features closest to a point, nearest first, each with its great-circle distance in kilometres.
WHEN TO USE IT. For "what is near here" and "which is the closest" — the questions where the ranking and the distance are the answer. Use geoparquet_filter_spatial instead when you want everything in an area rather than the closest few.
HOW IT STAYS CHEAP. A radius is not something Parquet statistics can prune on, so the search circle is first widened to its bounding rectangle, which is prunable; the exact distance is then computed only over the rows that survive, and used both to filter and to order. A large radius therefore costs a large read: prefer the smallest radius that can contain the answer, and widen it only if you come back empty.
PARAMETERS.
source: dataset name.
lon, lat: the centre point, in WGS 84 degrees. Longitude first.
radius_km: how far to look, up to 500. Results outside it are excluded, so this is a filter, not just a hint.
category, name_contains: the same narrowing as geoparquet_filter_spatial.
columns: column expressions to return.
limit: how many neighbours, capped at 1000.
WHAT COMES BACK. rows, ordered nearest first, each carrying distance_km; the search_bbox actually used for pruning; and the scan block.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | ||
| lon | Yes | ||
| limit | No | ||
| source | No | overture_places | |
| columns | No | ||
| category | No | ||
| radius_km | No | ||
| name_contains | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||