nodedb_sql/visitor/plan_visitor/
args.rs

1// SPDX-License-Identifier: Apache-2.0
2
3//! Parameter structs for [`super::trait_def::PlanVisitor`] methods whose
4//! `SqlPlan` variant carries enough fields to exceed clippy's
5//! `too_many_arguments` threshold. Each struct bundles one method's
6//! parameters (minus `&mut self`) so the trait method itself stays under
7//! the arg-count cap while still exposing every field to implementors.
8
9use crate::temporal::TemporalScope;
10use crate::types::SqlPlan;
11use crate::types::filter::Filter;
12use crate::types::plan::{
13    ArrayPrefilter, MergePlanClause, TextScoreColumn, TextSearchShape, VectorAnnOptions,
14    VectorPrimaryInsertIntent, VectorPrimaryRow, WriteRoute,
15};
16use crate::types::query::{
17    AggregateExpr, EngineType, JoinType, Projection, SortKey, SpatialPredicate, WindowSpec,
18};
19use crate::types_array::{ArrayAttrAst, ArrayCellOrderAst, ArrayDimAst, ArrayTileOrderAst};
20use crate::types_expr::{SqlExpr, SqlPayloadAtom, SqlValue};
21use nodedb_types::vector_distance::DistanceMetric;
22
23/// Parameters for [`super::trait_def::PlanVisitor::scan`].
24pub struct ScanVisitArgs<'a> {
25    pub collection: &'a str,
26    pub alias: Option<&'a str>,
27    pub engine: EngineType,
28    pub filters: &'a [Filter],
29    pub projection: &'a [Projection],
30    pub sort_keys: &'a [SortKey],
31    pub limit: Option<usize>,
32    pub offset: usize,
33    pub distinct: bool,
34    pub window_functions: &'a [WindowSpec],
35    pub temporal: &'a TemporalScope,
36}
37
38/// Parameters for [`super::trait_def::PlanVisitor::subquery`].
39pub struct SubqueryVisitArgs<'a> {
40    pub input: &'a SqlPlan,
41    pub filters: &'a [Filter],
42    pub projection: &'a [Projection],
43    pub window_functions: &'a [WindowSpec],
44    pub sort_keys: &'a [SortKey],
45    pub offset: usize,
46    pub distinct: bool,
47    pub limit: Option<usize>,
48}
49
50/// Parameters for [`super::trait_def::PlanVisitor::document_index_lookup`].
51pub struct DocumentIndexLookupVisitArgs<'a> {
52    pub collection: &'a str,
53    pub alias: Option<&'a str>,
54    pub engine: EngineType,
55    pub field: &'a str,
56    pub value: &'a SqlValue,
57    pub filters: &'a [Filter],
58    pub projection: &'a [Projection],
59    pub sort_keys: &'a [SortKey],
60    pub limit: Option<usize>,
61    pub offset: usize,
62    pub distinct: bool,
63    pub window_functions: &'a [WindowSpec],
64    pub case_insensitive: bool,
65    pub temporal: &'a TemporalScope,
66}
67
68/// Parameters for [`super::trait_def::PlanVisitor::insert`].
69pub struct InsertVisitArgs<'a> {
70    pub collection: &'a str,
71    pub engine: EngineType,
72    /// The lowering these rows take, decided by the engine's `EngineRules`.
73    pub route: WriteRoute,
74    pub rows: &'a [Vec<(String, SqlValue)>],
75    pub if_absent: bool,
76    pub column_schema: &'a [(String, String)],
77    pub primary_key: Option<&'a str>,
78}
79
80/// Parameters for [`super::trait_def::PlanVisitor::upsert`].
81pub struct UpsertVisitArgs<'a> {
82    pub collection: &'a str,
83    pub engine: EngineType,
84    /// The lowering these rows take, decided by the engine's `EngineRules`.
85    pub route: WriteRoute,
86    pub rows: &'a [Vec<(String, SqlValue)>],
87    pub on_conflict_updates: &'a [(String, SqlExpr)],
88    pub column_schema: &'a [(String, String)],
89    pub primary_key: Option<&'a str>,
90}
91
92/// Parameters for [`super::trait_def::PlanVisitor::update_from`].
93pub struct UpdateFromVisitArgs<'a> {
94    pub collection: &'a str,
95    pub engine: EngineType,
96    pub source: &'a SqlPlan,
97    pub source_alias: &'a str,
98    pub target_join_col: &'a str,
99    pub source_join_col: &'a str,
100    pub assignments: &'a [(String, SqlExpr)],
101    pub target_filters: &'a [Filter],
102    pub returning: bool,
103}
104
105/// Parameters for [`super::trait_def::PlanVisitor::join`].
106pub struct JoinVisitArgs<'a> {
107    pub left: &'a SqlPlan,
108    pub right: &'a SqlPlan,
109    pub on: &'a [(String, String)],
110    pub join_type: JoinType,
111    pub condition: Option<&'a SqlExpr>,
112    pub limit: Option<usize>,
113    pub projection: &'a [Projection],
114    pub filters: &'a [Filter],
115}
116
117/// Parameters for [`super::trait_def::PlanVisitor::aggregate`].
118pub struct AggregateVisitArgs<'a> {
119    pub input: &'a SqlPlan,
120    pub group_by: &'a [SqlExpr],
121    pub aggregates: &'a [AggregateExpr],
122    pub having: &'a [Filter],
123    pub limit: usize,
124    pub grouping_sets: Option<&'a [Vec<usize>]>,
125    pub sort_keys: &'a [SortKey],
126}
127
128/// Parameters for [`super::trait_def::PlanVisitor::timeseries_scan`].
129pub struct TimeseriesScanVisitArgs<'a> {
130    pub collection: &'a str,
131    pub time_range: (i64, i64),
132    pub bucket_interval_ms: i64,
133    pub group_by: &'a [String],
134    pub aggregates: &'a [AggregateExpr],
135    pub filters: &'a [Filter],
136    /// HAVING predicates over the finalized group rows.
137    pub having: &'a [Filter],
138    pub projection: &'a [Projection],
139    pub gap_fill: &'a str,
140    pub limit: usize,
141    pub sort_keys: &'a [SortKey],
142    pub tiered: bool,
143    pub temporal: &'a TemporalScope,
144}
145
146/// Parameters for [`super::trait_def::PlanVisitor::vector_search`].
147pub struct VectorSearchVisitArgs<'a> {
148    pub collection: &'a str,
149    pub field: &'a str,
150    pub query_vector: &'a [f32],
151    pub top_k: usize,
152    pub ef_search: usize,
153    pub metric: DistanceMetric,
154    pub filters: &'a [Filter],
155    pub array_prefilter: Option<&'a ArrayPrefilter>,
156    pub ann_options: &'a VectorAnnOptions,
157    pub skip_payload_fetch: bool,
158    pub payload_filters: &'a [SqlPayloadAtom],
159    /// Primary keys the search ranks among. `None`: every row.
160    pub pk_prefilter: Option<&'a [SqlValue]>,
161}
162
163/// Parameters for [`super::trait_def::PlanVisitor::text_search`].
164pub struct TextSearchVisitArgs<'a> {
165    pub collection: &'a str,
166    pub shape: &'a TextSearchShape,
167    /// Residual WHERE predicates, applied before ranking.
168    pub filters: &'a [Filter],
169    /// Score columns the SELECT list or ORDER BY reads.
170    pub scores: &'a [TextScoreColumn],
171}
172
173/// Parameters for [`super::trait_def::PlanVisitor::hybrid_search`].
174pub struct HybridSearchVisitArgs<'a> {
175    pub collection: &'a str,
176    pub vector_field: &'a str,
177    pub query_vector: &'a [f32],
178    /// `None` for `bm25_score(*, q)`: the whole-document index.
179    pub text_field: Option<&'a str>,
180    pub query_text: &'a str,
181    /// Residual WHERE predicates, applied to both legs before fusion.
182    pub filters: &'a [Filter],
183    pub top_k: usize,
184    pub ef_search: usize,
185    pub vector_weight: f32,
186    pub mode: nodedb_types::text_search::QueryMode,
187    pub fuzzy: bool,
188    pub score_alias: Option<&'a str>,
189}
190
191/// Parameters for [`super::trait_def::PlanVisitor::hybrid_search_triple`].
192pub struct HybridSearchTripleVisitArgs<'a> {
193    pub collection: &'a str,
194    pub vector_field: &'a str,
195    pub query_vector: &'a [f32],
196    /// `None` for `bm25_score(*, q)`: the whole-document index.
197    pub text_field: Option<&'a str>,
198    pub query_text: &'a str,
199    /// Residual WHERE predicates, applied to every leg before fusion.
200    pub filters: &'a [Filter],
201    pub graph_seed_id: &'a str,
202    pub graph_depth: usize,
203    pub graph_edge_label: Option<&'a str>,
204    pub top_k: usize,
205    pub ef_search: usize,
206    pub mode: nodedb_types::text_search::QueryMode,
207    pub fuzzy: bool,
208    pub rrf_k: (f64, f64, f64),
209    pub score_alias: Option<&'a str>,
210}
211
212/// Parameters for [`super::trait_def::PlanVisitor::spatial_scan`].
213pub struct SpatialScanVisitArgs<'a> {
214    pub collection: &'a str,
215    pub field: &'a str,
216    pub predicate: &'a SpatialPredicate,
217    pub query_geometry: &'a nodedb_types::geometry::Geometry,
218    pub distance_meters: f64,
219    pub attribute_filters: &'a [Filter],
220    pub limit: usize,
221    pub projection: &'a [Projection],
222}
223
224/// Parameters for [`super::trait_def::PlanVisitor::recursive_scan`].
225pub struct RecursiveScanVisitArgs<'a> {
226    pub collection: &'a str,
227    pub base_filters: &'a [Filter],
228    pub recursive_filters: &'a [Filter],
229    pub join_link: Option<&'a (String, String)>,
230    pub max_iterations: usize,
231    pub distinct: bool,
232    pub limit: usize,
233}
234
235/// Parameters for [`super::trait_def::PlanVisitor::recursive_value`].
236pub struct RecursiveValueVisitArgs<'a> {
237    pub cte_name: &'a str,
238    pub columns: &'a [String],
239    pub init_exprs: &'a [String],
240    pub step_exprs: &'a [String],
241    pub condition: Option<&'a str>,
242    pub max_depth: usize,
243    pub distinct: bool,
244}
245
246/// Parameters for [`super::trait_def::PlanVisitor::create_array`].
247pub struct CreateArrayVisitArgs<'a> {
248    pub name: &'a str,
249    pub dims: &'a [ArrayDimAst],
250    pub attrs: &'a [ArrayAttrAst],
251    pub tile_extents: &'a [i64],
252    pub cell_order: ArrayCellOrderAst,
253    pub tile_order: ArrayTileOrderAst,
254    pub prefix_bits: u8,
255    pub audit_retain_ms: Option<u64>,
256    pub minimum_audit_retain_ms: Option<u64>,
257}
258
259/// Parameters for [`super::trait_def::PlanVisitor::merge`].
260pub struct MergeVisitArgs<'a> {
261    pub target: &'a str,
262    pub engine: EngineType,
263    pub source: &'a SqlPlan,
264    pub target_join_col: &'a str,
265    pub source_join_col: &'a str,
266    pub source_alias: &'a str,
267    pub clauses: &'a [MergePlanClause],
268    pub returning: bool,
269}
270
271/// Parameters for [`super::trait_def::PlanVisitor::lateral_top_k`].
272pub struct LateralTopKVisitArgs<'a> {
273    pub outer: &'a SqlPlan,
274    pub outer_alias: Option<&'a str>,
275    pub inner_collection: &'a str,
276    pub inner_filters: &'a [Filter],
277    pub inner_order_by: &'a [SortKey],
278    pub inner_limit: usize,
279    pub correlation_keys: &'a [(String, String)],
280    pub lateral_alias: &'a str,
281    pub projection: &'a [Projection],
282    pub left_join: bool,
283}
284
285/// Parameters for [`super::trait_def::PlanVisitor::lateral_loop`].
286pub struct LateralLoopVisitArgs<'a> {
287    pub outer: &'a SqlPlan,
288    pub outer_alias: Option<&'a str>,
289    pub inner: &'a SqlPlan,
290    pub correlation_predicates: &'a [(String, String)],
291    pub lateral_alias: &'a str,
292    pub projection: &'a [Projection],
293    pub outer_row_cap: usize,
294    pub left_join: bool,
295}
296
297/// Parameters for [`super::trait_def::PlanVisitor::vector_primary_insert`].
298pub struct VectorPrimaryInsertVisitArgs<'a> {
299    pub collection: &'a str,
300    pub field: &'a str,
301    pub quantization: nodedb_types::VectorQuantization,
302    pub storage_dtype: nodedb_types::VectorStorageDtype,
303    pub payload_indexes: &'a [(String, nodedb_types::PayloadIndexKind)],
304    pub rows: &'a [VectorPrimaryRow],
305    pub intent: VectorPrimaryInsertIntent,
306    pub on_conflict_updates: &'a [(String, SqlExpr)],
307    pub primary_key: Option<&'a str>,
308}
309
310/// Parameters for [`super::trait_def::PlanVisitor::vector_primary_delete`].
311pub struct VectorPrimaryDeleteVisitArgs<'a> {
312    pub collection: &'a str,
313    pub field: &'a str,
314    pub filters: &'a [Filter],
315    pub target_keys: &'a [SqlValue],
316    pub primary_key: Option<&'a str>,
317}
318
319/// Parameters for [`super::trait_def::PlanVisitor::vector_primary_update`].
320pub struct VectorPrimaryUpdateVisitArgs<'a> {
321    pub collection: &'a str,
322    pub field: &'a str,
323    pub quantization: nodedb_types::VectorQuantization,
324    pub storage_dtype: nodedb_types::VectorStorageDtype,
325    pub payload_indexes: &'a [(String, nodedb_types::PayloadIndexKind)],
326    pub new_vector: Option<&'a [f32]>,
327    pub assignments: &'a [(String, SqlExpr)],
328    pub filters: &'a [Filter],
329    pub target_keys: &'a [SqlValue],
330    pub returning: bool,
331    pub primary_key: Option<&'a str>,
332}
nodedb_sql/visitor/plan_visitor/args.rs

nodedb_sql/visitor/plan_visitor/
args.rs
