Skip to content

Commit 74a2b86

Browse files
refactor(vortex-geo): generalize scalar function execution (#9215)
## Rationale for this change Native geometry scalar functions need consistent handling for constant operands, pairwise columns, null propagation, and all-null batches. Keeping those responsibilities in each function makes new unary and binary kernels harder to implement correctly. ## What changes are included in this PR? - Split shared geometry execution into unary, binary, and geo-types adapter modules. - Represent constant and column operands explicitly in shared execution state. - Centralize strict null propagation and all-null short-circuiting. - Preserve constant outputs when all operands are constant. - Migrate Envelope, Contains, Distance, and Intersects to the shared execution layer. - Keep bounding-box prechecks scoped to one-constant binary predicate paths. - Move native Rect array assembly into the Rect extension module. ## What APIs are changed? Are there any user-facing changes? This is an internal vortex-geo refactor. Existing scalar function semantics remain unchanged. --------- Signed-off-by: Nemo Yu <[email protected]>
1 parent 0f0390a commit 74a2b86

10 files changed

Lines changed: 777 additions & 521 deletions

File tree

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

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ use vortex_arrow::FromArrowArray;
6161
use vortex_buffer::Buffer;
6262
use vortex_error::VortexResult;
6363
use vortex_error::vortex_bail;
64-
use vortex_error::vortex_ensure;
6564
use vortex_error::vortex_err;
6665
pub use wkb::*;
6766

@@ -78,21 +77,6 @@ pub(crate) fn is_native_geometry(dtype: &DType) -> bool {
7877
})
7978
}
8079

81-
/// Validate the operands of a geo scalar function: each must be a native geometry type so the
82-
/// kernel can decode it. The two operands need not share a geometry type — e.g. a `Point` against
83-
/// a `Polygon` is valid, since distance/containment/intersection across types is meaningful.
84-
/// Nullable operands are allowed; the kernels propagate nulls (a null geometry input yields a null
85-
/// result) rather than decoding null rows.
86-
pub(crate) fn validate_geometry_operands(dtypes: &[DType]) -> VortexResult<()> {
87-
for dtype in dtypes {
88-
vortex_ensure!(
89-
is_native_geometry(dtype),
90-
"geo: operand {dtype} is not a native geometry type"
91-
);
92-
}
93-
Ok(())
94-
}
95-
9680
/// Flatten a native geometry column into a single coordinate `Struct<x, y, ...>` containing
9781
/// every vertex of every geometry.
9882
pub(crate) fn flatten_coordinates(

‎vortex-geo/src/extension/rect.rs‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ use vortex_array::ArrayRef;
2626
use vortex_array::ExecutionCtx;
2727
use vortex_array::IntoArray;
2828
use vortex_array::arrays::ExtensionArray;
29+
use vortex_array::arrays::StructArray;
2930
use vortex_array::arrays::extension::ExtensionArrayExt;
3031
use vortex_array::dtype::DType;
3132
use vortex_array::dtype::FieldNames;
@@ -36,6 +37,7 @@ use vortex_array::dtype::extension::ExtDType;
3637
use vortex_array::dtype::extension::ExtId;
3738
use vortex_array::dtype::extension::ExtVTable;
3839
use vortex_array::scalar::ScalarValue;
40+
use vortex_array::validity::Validity;
3941
use vortex_arrow::ArrowExport;
4042
use vortex_arrow::ArrowExportVTable;
4143
use vortex_arrow::ArrowImport;
@@ -155,6 +157,24 @@ pub(crate) fn box_dimension(dtype: &DType) -> VortexResult<Dimension> {
155157
.ok_or_else(|| vortex_err!("not a valid geoarrow.box dimension: {:?}", fields.names()))
156158
}
157159

160+
/// Build a native [`Rect`] array from canonical min/max ordinate columns.
161+
pub(crate) fn build_rect_array(
162+
ext_dtype: &ExtDType<Rect>,
163+
corners: Vec<ArrayRef>,
164+
len: usize,
165+
validity: Validity,
166+
) -> VortexResult<ArrayRef> {
167+
let dimension = box_dimension(ext_dtype.storage_dtype())?;
168+
let storage = StructArray::try_new(
169+
FieldNames::from(box_field_names(dimension)),
170+
corners,
171+
len,
172+
validity,
173+
)?
174+
.into_array();
175+
Ok(ExtensionArray::try_new(ext_dtype.clone().erased(), storage)?.into_array())
176+
}
177+
158178
static ARROW_BOX: CachedId = CachedId::new(BoxType::NAME);
159179

160180
/// The `geoarrow.box` extension type for `dimension`.

‎vortex-geo/src/scalar_fn/contains.rs‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,28 @@ use vortex_array::scalar_fn::ScalarFnId;
1919
use vortex_array::scalar_fn::ScalarFnVTable;
2020
use vortex_array::scalar_fn::TypedScalarFnInstance;
2121
use vortex_error::VortexResult;
22+
use vortex_error::vortex_ensure;
2223
use vortex_session::VortexSession;
2324
use vortex_session::registry::CachedId;
2425

25-
use crate::extension::validate_geometry_operands;
26-
use crate::scalar_fn::execute::execute_null_propagating;
26+
use crate::extension::is_native_geometry;
27+
use crate::scalar_fn::execute::execute_binary_geo_types;
28+
29+
/// Validate the two native geometry operands accepted by `ST_Contains`.
30+
fn validate_contains_operands(dtypes: &[DType]) -> VortexResult<()> {
31+
vortex_ensure!(
32+
dtypes.len() == 2,
33+
"geo: contains requires exactly two geometry operands, got {}",
34+
dtypes.len()
35+
);
36+
for dtype in dtypes {
37+
vortex_ensure!(
38+
is_native_geometry(dtype),
39+
"geo: contains operand {dtype} is not a native geometry type"
40+
);
41+
}
42+
Ok(())
43+
}
2744

2845
/// OGC `ST_Contains` between two native geometry operands, each a column or a constant
2946
/// literal: true where operand `b` lies completely inside operand `a` (boundary contact alone
@@ -71,7 +88,7 @@ impl ScalarFnVTable for GeoContains {
7188
}
7289

7390
fn return_dtype(&self, _: &Self::Options, dtypes: &[DType]) -> VortexResult<DType> {
74-
validate_geometry_operands(dtypes)?;
91+
validate_contains_operands(dtypes)?;
7592
let nullability = Nullability::from(dtypes.iter().any(DType::is_nullable));
7693
Ok(DType::Bool(nullability))
7794
}
@@ -87,7 +104,7 @@ impl ScalarFnVTable for GeoContains {
87104
// Containment is not symmetric: `a` is always the container and `b` the contained. A
88105
// container's rect must cover the contained's rect (`Rect::contains` is the closed
89106
// test), so a contained rect poking outside proves the row false.
90-
execute_null_propagating(
107+
execute_binary_geo_types(
91108
&a,
92109
&b,
93110
|a, b| a.contains(b),

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

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,28 @@ use vortex_array::scalar_fn::ScalarFnId;
2121
use vortex_array::scalar_fn::ScalarFnVTable;
2222
use vortex_array::scalar_fn::TypedScalarFnInstance;
2323
use vortex_error::VortexResult;
24+
use vortex_error::vortex_ensure;
2425
use vortex_session::VortexSession;
2526
use vortex_session::registry::CachedId;
2627

27-
use crate::extension::validate_geometry_operands;
28-
use crate::scalar_fn::execute::execute_null_propagating;
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+
"geo: 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+
"geo: distance operand {dtype} is not a native geometry type"
42+
);
43+
}
44+
Ok(())
45+
}
2946

3047
/// Planar (Euclidean) `ST_Distance` (no geodesic correction) between two native geometry
3148
/// operands, each a column or a constant literal.
@@ -72,7 +89,7 @@ impl ScalarFnVTable for GeoDistance {
7289
}
7390

7491
fn return_dtype(&self, _: &Self::Options, dtypes: &[DType]) -> VortexResult<DType> {
75-
validate_geometry_operands(dtypes)?;
92+
validate_distance_operands(dtypes)?;
7693
let nullability = Nullability::from(dtypes.iter().any(DType::is_nullable));
7794
Ok(DType::Primitive(PType::F64, nullability))
7895
}
@@ -86,7 +103,7 @@ impl ScalarFnVTable for GeoDistance {
86103
let a = args.get(0)?;
87104
let b = args.get(1)?;
88105
// Distance is a value, not a verdict: no bounding-rect test can decide it.
89-
execute_null_propagating(&a, &b, |x, y| Euclidean.distance(x, y), None, ctx)
106+
execute_binary_geo_types(&a, &b, |x, y| Euclidean.distance(x, y), None, ctx)
90107
}
91108

92109
fn validity(

0 commit comments

Comments
 (0)