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        /// Sync provenance: identifies the originating peer and sequence for idempotency.
56        #[serde(default)]
57        provenance: Option<nodedb_types::sync::wire::SyncProvenance>,
58    },
59    /// Remove a document's geometry from the R-tree index.
60    ///
61    /// Used by the sync inbound path. Keyed by the same hex-encoded surrogate
62    /// used at insert time.
63    Delete {
64        collection: String,
65        field: String,
66        /// Stable global surrogate for the row.
67        surrogate: Surrogate,
68        /// Sync provenance: identifies the originating peer and sequence for idempotency.
69        #[serde(default)]
70        provenance: Option<nodedb_types::sync::wire::SyncProvenance>,
71    },
72    /// R-tree index scan with spatial predicate and exact refinement.
73    Scan {
74        collection: String,
75        field: String,
76        predicate: SpatialPredicate,
77        /// Typed query geometry, parsed and validated on the Control Plane.
78        query_geometry: Geometry,
79        /// Distance threshold in meters (for ST_DWithin). 0 for non-distance predicates.
80        distance_meters: f64,
81        /// Additional attribute filters applied after spatial candidates.
82        attribute_filters: Vec<u8>,
83        limit: usize,
84        projection: Vec<String>,
85        /// RLS post-candidate filters.
86        rls_filters: Vec<u8>,
87        /// Optional surrogate prefilter injected by a cross-engine sub-plan.
88        /// When present, only candidates whose surrogate is in this bitmap
89        /// are returned. `None` = no prefilter; all R-tree candidates pass.
90        prefilter: Option<SurrogateBitmap>,
91    },
92}
nodedb_physical/physical_plan/spatial.rs

nodedb_physical/physical_plan/
spatial.rs
