geoparquet_filter_spatial
Find features inside a rectangle or WKT area and return them as GeoJSON. Filter by category, name, or confidence to get exactly the matching places, using pushdown to read only relevant data.
Instructions
Return the features of a dataset that fall inside an area, as a GeoJSON FeatureCollection. The area is either a lon/lat rectangle or an arbitrary WKT geometry.
WHEN TO USE IT. When the answer is the features themselves — "which cafes are in this neighbourhood", "give me the buildings along this street" — and you intend to look at them individually. When you only need a count, a ranking or a distribution, use geoparquet_aggregate_attribute or geoparquet_summarize_h3 instead: they answer from the remote file and transfer kilobytes instead of features.
COST. The rectangle is what makes the read cheap. It is pushed into the remote Parquet file and prunes whole row groups from their footer statistics before any byte of data is fetched, so a tight box costs far less than a wide one — this is the difference between megabytes and gigabytes, not a micro-optimisation. Always pass the tightest area the question allows.
PARAMETERS.
source: dataset name.
min_lon, min_lat, max_lon, max_lat: the rectangle, in WGS 84 degrees. Pass all four, or none if you are using wkt.
wkt: an arbitrary geometry instead of a rectangle, for example 'POLYGON ((2.33 48.85, 2.36 48.85, 2.36 48.87, 2.33 48.87, 2.33 48.85))'. Its envelope prunes the read and the exact shape then filters the survivors, so the answer is exact. Give either a rectangle or a wkt, never both.
category: exact match on the dataset's category column, for example 'restaurant'. Preview the column first — the vocabulary is not obvious.
name_contains: case-insensitive substring of the feature name.
min_confidence: 0 to 1, Overture's own confidence in the record. 0.8 drops most questionable entries.
columns: column expressions to return. A narrow projection is worth as much as a tight box, because Parquet is columnar and unread columns are unfetched.
include_geometry: false skips the geometry column — the widest in the file — and approximates each feature by its bounding-box corner, which is exact for points. Ignored when wkt is used, since the exact test needs the geometry.
limit: maximum features, capped at 1000.
WHAT COMES BACK. geojson as a FeatureCollection; feature_count and truncated, which tells you the limit was reached and there is more; geometry_is_exact; the sql that ran; and scan with bytes_scanned — read it, and tighten the area if it looks large.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wkt | No | ||
| limit | No | ||
| source | No | overture_places | |
| columns | No | ||
| max_lat | No | ||
| max_lon | No | ||
| min_lat | No | ||
| min_lon | No | ||
| category | No | ||
| name_contains | No | ||
| min_confidence | No | ||
| include_geometry | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||