Struct KNNPredicate 

pub struct KNNPredicate {
    pub left: Arc<dyn PhysicalExpr>,
    pub right: Arc<dyn PhysicalExpr>,
    pub k: u32,
    pub use_spheroid: bool,
    pub probe_side: JoinSide,
}

K-Nearest Neighbors (KNN) spatial join predicate.

This predicate represents a spatial join that finds the k nearest neighbors from the right side (object) table for each geometry in the left side (query) table. It’s commonly used for proximity analysis and spatial recommendations.

Example SQL

SELECT * FROM restaurants r
JOIN TABLE(ST_KNN(r.location, h.location, 5, false)) AS knn
ON r.id = knn.restaurant_id

Algorithm

For each geometry in the left (query) side:

1. Find the k nearest geometries from the right (object) side
2. Use spatial index for efficient nearest neighbor search
3. Handle tie-breaking when multiple geometries have the same distance

Performance Considerations

• Uses R-tree spatial index for efficient search
• Performance depends on k value and spatial distribution
• Tie-breaking may require additional distance calculations

Limitations

• Currently only supports planar (Euclidean) distance calculations
• Spheroid distance (use_spheroid=true) is not yet implemented

Fields

left: Arc<dyn PhysicalExpr>

The expression for evaluating the geometry value on the left side (queries side). The expression should be evaluated directly on the left side batches.

right: Arc<dyn PhysicalExpr>

The expression for evaluating the geometry value on the right side (object side). The expression should be evaluated directly on the right side batches.

k: u32

The number of nearest neighbors to find (literal value).

use_spheroid: bool

Whether to use spheroid distance calculation or planar distance (literal value). Currently must be false as spheroid distance is not yet implemented.

probe_side: JoinSide

Which execution plan side (Left or Right) the probe expression belongs to. This is used to correctly assign build/probe plans in execution.

Implementations

impl KNNPredicate

pub fn new( left: Arc<dyn PhysicalExpr>, right: Arc<dyn PhysicalExpr>, k: u32, use_spheroid: bool, probe_side: JoinSide, ) -> Self

Creates a new K-Nearest Neighbors predicate.

Arguments

• left - Expression for the left side (query) geometry
• right - Expression for the right side (object) geometry
• k - Number of nearest neighbors to find (literal value)
• use_spheroid - Whether to use spheroid distance (literal value, currently must be false)
• probe_side - Which execution plan side the probe expression belongs to, cannot be None

Trait Implementations

impl Clone for KNNPredicate

fn clone(&self) -> KNNPredicate

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KNNPredicate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for KNNPredicate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl SpatialPredicateTrait for KNNPredicate

fn swap_for_swapped_children(&self) -> Self

Returns a semantically equivalent predicate after the join children are swapped.

fn update_for_child_projections( &self, projected_left_exprs: &[ProjectionExpr], projected_right_exprs: &[ProjectionExpr], ) -> Result<Option<Self>>

Rewrites the predicate to reference projected child expressions.