Skip to content

Commit f77666b

Browse files
committed
Execute spatial distance with RowFn
Signed-off-by: Connor Tsui <[email protected]>
1 parent b6c09be commit f77666b

7 files changed

Lines changed: 215 additions & 77 deletions

File tree

‎vortex-spatial/Cargo.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ geo-types = { workspace = true }
2222
geoarrow = { workspace = true }
2323
geoarrow-cast = { workspace = true }
2424
prost = { workspace = true }
25-
vortex-array = { workspace = true }
25+
vortex-array = { workspace = true, features = ["unstable_row_fns"] }
2626
vortex-arrow = { workspace = true }
2727
vortex-buffer = { workspace = true }
2828
vortex-edition = { workspace = true }

‎vortex-spatial/src/extension/mod.rs‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,63 @@ pub(crate) fn geometries(
178178
}
179179
}
180180

181+
/// The geometry a null row decodes to under [`geometries_null_tolerant`]. Arbitrary: the caller
182+
/// guarantees null rows are never read.
183+
pub(crate) fn placeholder_geometry() -> Geometry<f64> {
184+
Geometry::Point(geo_types::Point::new(0.0, 0.0))
185+
}
186+
187+
/// Whether [`geometries_null_tolerant`] supports this array without filtering null rows first.
188+
pub(crate) fn can_decode_geometries_null_tolerant(array: &ArrayRef) -> VortexResult<bool> {
189+
if array.validity()?.definitely_no_nulls() {
190+
return Ok(true);
191+
}
192+
193+
let Some(ext) = array.dtype().as_extension_opt() else {
194+
vortex_bail!(
195+
"spatial: operand is not a geometry extension type, was {}",
196+
array.dtype()
197+
);
198+
};
199+
200+
Ok(ext.is::<Point>() || ext.is::<Polygon>())
201+
}
202+
203+
/// Decode a native geometry column that may contain null rows, writing [`placeholder_geometry`]
204+
/// into their slots. The caller guarantees null rows are never read.
205+
///
206+
/// `Ok(None)` means this geometry type has no null-tolerant decode yet (`Point` and `Polygon` are
207+
/// covered), and the caller falls back to the filter strategy, which never decodes a null row. A
208+
/// column with definitely no nulls delegates to the ordinary [`geometries`] for any type.
209+
pub(crate) fn geometries_null_tolerant(
210+
array: &ArrayRef,
211+
ctx: &mut ExecutionCtx,
212+
) -> VortexResult<Option<Vec<Geometry<f64>>>> {
213+
if array.validity()?.definitely_no_nulls() {
214+
return geometries(array, ctx).map(Some);
215+
}
216+
217+
let Some(ext) = array.dtype().as_extension_opt() else {
218+
vortex_bail!(
219+
"spatial: operand is not a geometry extension type, was {}",
220+
array.dtype()
221+
);
222+
};
223+
let storage = array
224+
.clone()
225+
.execute::<ExtensionArray>(ctx)?
226+
.storage_array()
227+
.clone();
228+
229+
if ext.is::<Point>() {
230+
point_geometries_null_tolerant(&storage, ctx).map(Some)
231+
} else if ext.is::<Polygon>() {
232+
polygon_geometries_null_tolerant(&storage, ctx).map(Some)
233+
} else {
234+
Ok(None)
235+
}
236+
}
237+
181238
/// Decode a constant operand scalar to one geometry, a constant of any
182239
/// supported geometry type is decoded exactly like a column.
183240
pub(crate) fn single_geometry(

‎vortex-spatial/src/extension/point.rs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ use super::coordinate::coordinate_from_struct;
5050
use super::coordinate::coordinate_storage_dtype;
5151
use super::geoarrow_metadata;
5252
use super::geoarrow_to_wkb;
53+
use super::placeholder_geometry;
5354
use super::spatial_metadata_from_arrow;
5455

5556
/// A single location: `geoarrow.point`, stored as `Struct<x, y[, z][, m]>` of non-nullable `f64`.
@@ -150,6 +151,23 @@ pub(crate) fn point_geometries(
150151
.collect()
151152
}
152153

154+
/// Like [`point_geometries`], but a null row decodes to the placeholder geometry instead of
155+
/// failing. The caller guarantees null rows are never read.
156+
pub(crate) fn point_geometries_null_tolerant(
157+
storage: &ArrayRef,
158+
ctx: &mut ExecutionCtx,
159+
) -> VortexResult<Vec<Geometry<f64>>> {
160+
point_array(storage, ctx)?
161+
.iter()
162+
.map(|geometry| match geometry {
163+
None => Ok(placeholder_geometry()),
164+
Some(geometry) => Ok(geometry
165+
.map_err(|e| vortex_err!("spatial: geometry access failed: {e}"))?
166+
.to_geometry()),
167+
})
168+
.collect()
169+
}
170+
153171
impl ArrowExportVTable for Point {
154172
fn arrow_ext_id(&self) -> Id {
155173
*ARROW_POINT

‎vortex-spatial/src/extension/polygon.rs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ use super::coordinate::coordinate_dimension;
5353
use super::coordinate::coordinate_storage_dtype;
5454
use super::geoarrow_metadata;
5555
use super::geoarrow_to_wkb;
56+
use super::placeholder_geometry;
5657
use super::spatial_metadata_from_arrow;
5758

5859
/// A polygon: `geoarrow.polygon`, stored as `List<List<Struct<x, y[, z][, m]>>>` (rings of vertices).
@@ -153,6 +154,23 @@ pub(crate) fn polygon_geometries(
153154
.collect()
154155
}
155156

157+
/// Like [`polygon_geometries`], but a null row decodes to the placeholder geometry instead of
158+
/// failing. The caller guarantees null rows are never read.
159+
pub(crate) fn polygon_geometries_null_tolerant(
160+
storage: &ArrayRef,
161+
ctx: &mut ExecutionCtx,
162+
) -> VortexResult<Vec<Geometry<f64>>> {
163+
polygon_array(storage, ctx)?
164+
.iter()
165+
.map(|geometry| match geometry {
166+
None => Ok(placeholder_geometry()),
167+
Some(geometry) => Ok(geometry
168+
.map_err(|e| vortex_err!("spatial: geometry access failed: {e}"))?
169+
.to_geometry()),
170+
})
171+
.collect()
172+
}
173+
156174
/// Build a geoarrow `PolygonArray` from a `Polygon`'s `List<List<coordinate>>` storage.
157175
fn polygon_array(storage: &ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<PolygonArray> {
158176
let polygon_type = polygon_type(

‎vortex-spatial/src/scalar_fn/distance.rs‎

Lines changed: 29 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -6,43 +6,20 @@
66
use geo::Distance;
77
use geo::Euclidean;
88
use vortex_array::ArrayRef;
9-
use vortex_array::ExecutionCtx;
109
use vortex_array::arrays::ScalarFnArray;
1110
use vortex_array::dtype::DType;
12-
use vortex_array::dtype::Nullability;
13-
use vortex_array::dtype::PType;
14-
use vortex_array::expr::Expression;
15-
use vortex_array::expr::union_child_validities;
16-
use vortex_array::scalar_fn::Arity;
17-
use vortex_array::scalar_fn::ChildName;
1811
use vortex_array::scalar_fn::EmptyOptions;
19-
use vortex_array::scalar_fn::ExecutionArgs;
2012
use vortex_array::scalar_fn::ScalarFnId;
21-
use vortex_array::scalar_fn::ScalarFnVTable;
2213
use vortex_array::scalar_fn::TypedScalarFnInstance;
14+
use vortex_array::scalar_fn::unstable::row::InitializedElement;
15+
use vortex_array::scalar_fn::unstable::row::RowFn;
16+
use vortex_array::scalar_fn::unstable::row::RowVisitor;
17+
use vortex_array::scalar_fn::unstable::row::UninitElementSink;
2318
use vortex_error::VortexResult;
24-
use vortex_error::vortex_ensure;
2519
use vortex_session::VortexSession;
2620
use vortex_session::registry::CachedId;
2721

28-
use crate::extension::is_native_geometry;
29-
use crate::scalar_fn::execute::execute_binary_geo_types;
30-
31-
/// Validate the two native geometry operands accepted by `ST_Distance`.
32-
fn validate_distance_operands(dtypes: &[DType]) -> VortexResult<()> {
33-
vortex_ensure!(
34-
dtypes.len() == 2,
35-
"spatial: distance requires exactly two geometry operands, got {}",
36-
dtypes.len()
37-
);
38-
for dtype in dtypes {
39-
vortex_ensure!(
40-
is_native_geometry(dtype),
41-
"spatial: distance operand {dtype} is not a native geometry type"
42-
);
43-
}
44-
Ok(())
45-
}
22+
use crate::scalar_fn::row::GeometryRow;
4623

4724
/// Planar (Euclidean) `ST_Distance` (no geodesic correction) between two native geometry
4825
/// operands, each a column or a constant literal.
@@ -60,66 +37,41 @@ impl SpatialDistance {
6037
}
6138
}
6239

63-
impl ScalarFnVTable for SpatialDistance {
40+
impl RowFn for SpatialDistance {
6441
type Options = EmptyOptions;
6542

43+
const ARG_NAMES: &'static [&'static str] = &["a", "b"];
44+
const INFALLIBLE: bool = false;
45+
6646
fn id(&self) -> ScalarFnId {
6747
static ID: CachedId = CachedId::new("vortex.st.distance");
6848
*ID
6949
}
7050

71-
fn serialize(&self, _: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
51+
fn serialize(&self, _options: &Self::Options) -> VortexResult<Option<Vec<u8>>> {
7252
Ok(Some(vec![]))
7353
}
7454

75-
fn deserialize(&self, _: &[u8], _: &VortexSession) -> VortexResult<Self::Options> {
76-
Ok(EmptyOptions)
77-
}
78-
79-
fn arity(&self, _: &Self::Options) -> Arity {
80-
Arity::Exact(2)
81-
}
82-
83-
fn child_name(&self, _: &Self::Options, child_idx: usize) -> ChildName {
84-
match child_idx {
85-
0 => ChildName::from("a"),
86-
1 => ChildName::from("b"),
87-
_ => unreachable!("distance has exactly two children"),
88-
}
89-
}
90-
91-
fn return_dtype(&self, _: &Self::Options, dtypes: &[DType]) -> VortexResult<DType> {
92-
validate_distance_operands(dtypes)?;
93-
let nullability = Nullability::from(dtypes.iter().any(DType::is_nullable));
94-
Ok(DType::Primitive(PType::F64, nullability))
95-
}
96-
97-
fn execute(
55+
fn deserialize(
9856
&self,
99-
_: &Self::Options,
100-
args: &dyn ExecutionArgs,
101-
ctx: &mut ExecutionCtx,
102-
) -> VortexResult<ArrayRef> {
103-
let a = args.get(0)?;
104-
let b = args.get(1)?;
105-
// Distance is a value, not a verdict: no bounding-rect test can decide it.
106-
execute_binary_geo_types(&a, &b, |x, y| Euclidean.distance(x, y), None, ctx)
57+
_metadata: &[u8],
58+
_session: &VortexSession,
59+
) -> VortexResult<Self::Options> {
60+
Ok(EmptyOptions)
10761
}
10862

109-
fn validity(
63+
fn dispatch<V: RowVisitor<Self::Options>>(
11064
&self,
111-
_: &Self::Options,
112-
expression: &Expression,
113-
) -> VortexResult<Option<Expression>> {
114-
union_child_validities(expression)
115-
}
116-
117-
fn is_strict(&self, _: &Self::Options) -> bool {
118-
true
119-
}
120-
121-
fn is_infallible(&self, _: &Self::Options) -> bool {
122-
true
65+
_options: &Self::Options,
66+
_args: &[DType],
67+
visitor: V,
68+
) -> VortexResult<V::VisitResult> {
69+
visitor.visit_into::<(GeometryRow, GeometryRow), UninitElementSink<f64>, _>(
70+
|(a, b), output| {
71+
// SAFETY: `output` is the `UninitElementSink` row supplied for this callback.
72+
unsafe { InitializedElement::write(output, Euclidean.distance(a, b)) }
73+
},
74+
)
12375
}
12476
}
12577

@@ -196,8 +148,9 @@ mod tests {
196148
Ok(())
197149
}
198150

199-
/// Distance passes no bounding-rect rejection: a point far outside a constant polygon's
200-
/// bounding rect still gets its true distance, alongside an inside point at distance zero.
151+
/// Distance is a value rather than a verdict, so no bounding-rect rejection may fire for it: a
152+
/// point far outside a constant polygon's rect still gets its true distance. Carried over from
153+
/// #9076, which added the rejection to the predicates but deliberately not to this function.
201154
#[test]
202155
fn distance_to_constant_polygon_is_exact() -> VortexResult<()> {
203156
let session = vortex_array::array_session();

‎vortex-spatial/src/scalar_fn/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ mod execute;
1313
pub mod intersects;
1414
pub mod length;
1515
pub mod make_line;
16+
pub(crate) mod row;
Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
//! What the geo scalar functions add to the row-function machinery: an element type that decodes a
5+
//! native geometry column into `geo_types` geometries.
6+
7+
use geo_types::Geometry;
8+
use vortex_array::ArrayRef;
9+
use vortex_array::ExecutionCtx;
10+
use vortex_array::dtype::DType;
11+
use vortex_array::scalar_fn::unstable::row::InputElement;
12+
use vortex_error::VortexResult;
13+
use vortex_error::vortex_ensure;
14+
15+
use crate::extension::can_decode_geometries_null_tolerant;
16+
use crate::extension::geometries;
17+
use crate::extension::geometries_null_tolerant;
18+
use crate::extension::is_native_geometry;
19+
20+
/// Marker for native geometry input elements: accepts any native geometry column and presents each
21+
/// row as a decoded `geo_types` geometry.
22+
///
23+
/// The two operands of a binary geo function need not share a geometry type, since distance,
24+
/// containment and intersection across types are all meaningful, so this validates only that the
25+
/// column is _some_ native geometry.
26+
pub(crate) struct GeometryRow;
27+
28+
// SAFETY: The row-loop view is a geometry slice. Its `ViewLen` is the slice length, so every index
29+
// below that length is valid for both checked and unchecked access.
30+
unsafe impl InputElement for GeometryRow {
31+
type Column = Vec<Geometry<f64>>;
32+
type View<'a> = &'a [Geometry<f64>];
33+
type Elem<'a> = &'a Geometry<f64>;
34+
35+
// A geometry row is decoded from its coordinate storage, which behind a null row holds arbitrary
36+
// coordinates that need not describe a well-formed geometry.
37+
const DENSE_SAFE: bool = false;
38+
// Decoding builds a geometry from stored coordinates, and a malformed one in a *valid* row is a
39+
// domain error rather than an infrastructural failure.
40+
const DECODE_INFALLIBLE: bool = false;
41+
42+
fn validate(dtype: &DType) -> VortexResult<()> {
43+
vortex_ensure!(
44+
is_native_geometry(dtype),
45+
"spatial: operand {dtype} is not a native geometry type"
46+
);
47+
Ok(())
48+
}
49+
50+
fn decode(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<Self::Column> {
51+
geometries(&array, ctx)
52+
}
53+
54+
fn can_decode_null_tolerant(array: &ArrayRef) -> VortexResult<bool> {
55+
can_decode_geometries_null_tolerant(array)
56+
}
57+
58+
fn get(column: &Self::Column, index: usize) -> &Geometry<f64> {
59+
&column[index]
60+
}
61+
62+
fn view(column: &Self::Column) -> Self::View<'_> {
63+
column.as_slice()
64+
}
65+
66+
fn get_from_view<'a>(view: &Self::View<'a>, index: usize) -> &'a Geometry<f64>
67+
where
68+
Self: 'a,
69+
{
70+
&view[index]
71+
}
72+
73+
unsafe fn get_from_view_unchecked<'a>(view: &Self::View<'a>, index: usize) -> &'a Geometry<f64>
74+
where
75+
Self: 'a,
76+
{
77+
// SAFETY: The caller established that `index` is below `ViewLen::len` for this view, which
78+
// is the geometry slice length.
79+
unsafe { view.get_unchecked(index) }
80+
}
81+
82+
/// Null rows decode to a placeholder geometry that the branch-and-skip row loop never reads.
83+
/// `Point` and `Polygon` columns are covered; other geometry types return `Ok(None)` and the
84+
/// batch falls back to the filter strategy.
85+
fn decode_null_tolerant(
86+
array: ArrayRef,
87+
ctx: &mut ExecutionCtx,
88+
) -> VortexResult<Option<Self::Column>> {
89+
geometries_null_tolerant(&array, ctx)
90+
}
91+
}

0 commit comments

Comments
 (0)