nodedb_physical/physical_plan/
spatial.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Spatial engine operations dispatched to the Data Plane.
4
5use nodedb_types::{Surrogate, SurrogateBitmap, geometry::Geometry};
6
7/// Spatial predicate type for R-tree index scan.
8#[derive(
9    Debug,
10    Clone,
11    Copy,
12    PartialEq,
13    Eq,
14    serde::Serialize,
15    serde::Deserialize,
16    zerompk::ToMessagePack,
17    zerompk::FromMessagePack,
18)]
19#[msgpack(c_enum)]
20pub enum SpatialPredicate {
21    /// ST_DWithin: geometry within distance (meters).
22    DWithin,
23    /// ST_Contains: query geometry contains document geometry.
24    Contains,
25    /// ST_Intersects: query geometry intersects document geometry.
26    Intersects,
27    /// ST_Within: document geometry is within query geometry.
28    Within,
29}
30
31/// Spatial engine physical operations.
32#[derive(
33    Debug,
34    Clone,
35    PartialEq,
36    serde::Serialize,
37    serde::Deserialize,
38    zerompk::ToMessagePack,
39    zerompk::FromMessagePack,
40)]
41pub enum SpatialOp {
42    /// Insert a geometry into the R-tree index for a document.
43    ///
44    /// Used by the sync inbound path to replicate spatial data from Lite to Origin.
45    /// The R-tree and sparse document store are keyed by the hex-encoded
46    /// `surrogate` (matching direct `INSERT INTO` semantics), so the
47    /// cross-engine prefilter bitmap intersect works without translation.
48    Insert {
49        collection: String,
50        field: String,
51        /// Stable global surrogate for the row, assigned on the Control Plane.
52        surrogate: Surrogate,
53        /// Typed geometry, deserialised on the Control Plane from wire bytes.
54        geometry: Geometry,
55    },
56    /// Remove a document's geometry from the R-tree index.
57    ///
58    /// Used by the sync inbound path. Keyed by the same hex-encoded surrogate
59    /// used at insert time.
60    Delete {
61        collection: String,
62        field: String,
63        /// Stable global surrogate for the row.
64        surrogate: Surrogate,
65    },
66    /// R-tree index scan with spatial predicate and exact refinement.
67    Scan {
68        collection: String,
69        field: String,
70        predicate: SpatialPredicate,
71        /// Typed query geometry, parsed and validated on the Control Plane.
72        query_geometry: Geometry,
73        /// Distance threshold in meters (for ST_DWithin). 0 for non-distance predicates.
74        distance_meters: f64,
75        /// Additional attribute filters applied after spatial candidates.
76        attribute_filters: Vec<u8>,
77        limit: usize,
78        projection: Vec<String>,
79        /// RLS post-candidate filters.
80        rls_filters: Vec<u8>,
81        /// Optional surrogate prefilter injected by a cross-engine sub-plan.
82        /// When present, only candidates whose surrogate is in this bitmap
83        /// are returned. `None` = no prefilter; all R-tree candidates pass.
84        prefilter: Option<SurrogateBitmap>,
85    },
86}
nodedb_physical/physical_plan/spatial.rs

nodedb_physical/physical_plan/
spatial.rs
