nodedb_sql/types/plan/variants.rs
1// SPDX-License-Identifier: Apache-2.0
2
3//! The `SqlPlan` enum — top-level plan produced by the SQL planner.
4
5use crate::fts_types::FtsQuery;
6use crate::temporal::TemporalScope;
7use crate::types_array;
8use crate::types_expr::{SqlExpr, SqlPayloadAtom, SqlValue};
9pub use nodedb_types::vector_distance::DistanceMetric;
10
11use crate::types::filter::Filter;
12use crate::types::query::{
13 AggregateExpr, EngineType, JoinType, Projection, SortKey, SpatialPredicate, WindowSpec,
14};
15
16use super::merge_types::MergePlanClause;
17use super::row_types::{KvInsertIntent, VectorPrimaryRow};
18use super::vector_opts::{ArrayPrefilter, VectorAnnOptions};
19
20/// The top-level plan produced by the SQL planner.
21#[derive(Debug, Clone)]
22pub enum SqlPlan {
23 // ── Constant ──
24 /// Query with no FROM clause: SELECT 1, SELECT 'hello' AS name, etc.
25 /// Produces a single row with evaluated constant expressions.
26 ConstantResult {
27 columns: Vec<String>,
28 values: Vec<SqlValue>,
29 },
30
31 // ── Reads ──
32 Scan {
33 collection: String,
34 alias: Option<String>,
35 engine: EngineType,
36 filters: Vec<Filter>,
37 projection: Vec<Projection>,
38 sort_keys: Vec<SortKey>,
39 limit: Option<usize>,
40 offset: usize,
41 distinct: bool,
42 window_functions: Vec<WindowSpec>,
43 /// Bitemporal qualifier extracted from `FOR SYSTEM_TIME` /
44 /// `FOR VALID_TIME`. Default when the scan is current-state.
45 temporal: TemporalScope,
46 },
47 PointGet {
48 collection: String,
49 alias: Option<String>,
50 engine: EngineType,
51 key_column: String,
52 key_value: SqlValue,
53 },
54 /// Document fetch via a secondary index: equality predicate on an
55 /// indexed field. The executor performs an index lookup to resolve
56 /// matching document IDs, reads each document, and applies any
57 /// remaining filters, projection, sort, and limit.
58 ///
59 /// Emitted by `document_schemaless::plan_scan` /
60 /// `document_strict::plan_scan` when the WHERE clause contains a
61 /// single equality predicate on a `Ready` indexed field. Any
62 /// additional predicates fall through as post-filters.
63 DocumentIndexLookup {
64 collection: String,
65 alias: Option<String>,
66 engine: EngineType,
67 /// Indexed field path used for the lookup.
68 field: String,
69 /// Equality value from the WHERE clause.
70 value: SqlValue,
71 /// Remaining filters after extracting the equality used for lookup.
72 filters: Vec<Filter>,
73 projection: Vec<Projection>,
74 sort_keys: Vec<SortKey>,
75 limit: Option<usize>,
76 offset: usize,
77 distinct: bool,
78 window_functions: Vec<WindowSpec>,
79 /// Whether the chosen index is COLLATE NOCASE — the executor
80 /// lowercases the lookup value before probing.
81 case_insensitive: bool,
82 /// Bitemporal qualifier — mirrors `Scan::temporal`. Document
83 /// engines must honor it at the Ceiling stage.
84 temporal: TemporalScope,
85 },
86 RangeScan {
87 collection: String,
88 field: String,
89 lower: Option<SqlValue>,
90 upper: Option<SqlValue>,
91 limit: usize,
92 },
93
94 // ── Writes ──
95 Insert {
96 collection: String,
97 engine: EngineType,
98 rows: Vec<Vec<(String, SqlValue)>>,
99 /// Column defaults from schema: `(column_name, default_expr)`.
100 /// Used to auto-generate values for missing columns (e.g. `id` with `UUID_V7`).
101 column_defaults: Vec<(String, String)>,
102 /// `ON CONFLICT DO NOTHING` semantics: when true, duplicate-PK rows
103 /// are silently skipped instead of raising `unique_violation`. Plain
104 /// `INSERT` (no `ON CONFLICT` clause) sets this to `false`.
105 if_absent: bool,
106 },
107 /// KV INSERT: key and value are fundamentally separate.
108 /// Each entry is `(key, value_columns)`.
109 KvInsert {
110 collection: String,
111 entries: Vec<(SqlValue, Vec<(String, SqlValue)>)>,
112 /// TTL in seconds (0 = no expiry). Extracted from `ttl` column if present.
113 ttl_secs: u64,
114 /// INSERT-vs-UPSERT distinction. `KvOp::Put` is a Redis-SET-style
115 /// upsert by design; to honor SQL `INSERT` semantics the planner must
116 /// tell the converter whether a duplicate key should raise (plain
117 /// `INSERT`, `Insert`), be silently skipped (`ON CONFLICT DO NOTHING`,
118 /// `InsertIfAbsent`), or overwrite (`UPSERT` / `ON CONFLICT DO
119 /// UPDATE`, `Put`).
120 intent: KvInsertIntent,
121 /// `ON CONFLICT (key) DO UPDATE SET field = expr` assignments, carried
122 /// through when `intent == Put` via the ON-CONFLICT-DO-UPDATE path.
123 /// Empty for plain UPSERT (whole-value overwrite) and for INSERT
124 /// variants.
125 on_conflict_updates: Vec<(String, SqlExpr)>,
126 },
127 /// UPSERT: insert or merge if document exists.
128 Upsert {
129 collection: String,
130 engine: EngineType,
131 rows: Vec<Vec<(String, SqlValue)>>,
132 column_defaults: Vec<(String, String)>,
133 /// `ON CONFLICT (...) DO UPDATE SET field = expr` assignments.
134 /// When empty, upsert is a plain merge: new columns overwrite existing.
135 /// When non-empty, the engine applies these per-row against the
136 /// *existing* document instead of merging the inserted values.
137 on_conflict_updates: Vec<(String, SqlExpr)>,
138 },
139 InsertSelect {
140 target: String,
141 source: Box<SqlPlan>,
142 limit: usize,
143 },
144 Update {
145 collection: String,
146 engine: EngineType,
147 assignments: Vec<(String, SqlExpr)>,
148 filters: Vec<Filter>,
149 target_keys: Vec<SqlValue>,
150 returning: bool,
151 },
152 /// `UPDATE target SET col = src.col2 FROM src WHERE target.id = src.id`
153 ///
154 /// Two-phase execution: scan `source` with `source_filters`, then for
155 /// each matched source row that satisfies the join predicates against a
156 /// target row, apply `assignments` (which may reference source columns
157 /// via qualified names `src.col`).
158 ///
159 /// `join_predicates` are equality pairs `(target_col, source_col)` extracted
160 /// from the WHERE clause linking the two tables. `target_filters` are
161 /// remaining WHERE predicates that reference only `target`.
162 UpdateFrom {
163 collection: String,
164 engine: EngineType,
165 /// The FROM source: a `Scan`, `Join`, or other read plan.
166 source: Box<SqlPlan>,
167 /// Column name used as the target's join key (e.g. `"id"`).
168 target_join_col: String,
169 /// Column name used as the source's join key (e.g. `"id"`).
170 source_join_col: String,
171 /// SET assignments — RHS may be `SqlExpr::Column { table: Some("src"), .. }`.
172 assignments: Vec<(String, SqlExpr)>,
173 /// Filters that apply only to the target collection.
174 target_filters: Vec<Filter>,
175 returning: bool,
176 },
177 Delete {
178 collection: String,
179 engine: EngineType,
180 filters: Vec<Filter>,
181 target_keys: Vec<SqlValue>,
182 },
183 Truncate {
184 collection: String,
185 restart_identity: bool,
186 },
187
188 // ── Joins ──
189 Join {
190 left: Box<SqlPlan>,
191 right: Box<SqlPlan>,
192 on: Vec<(String, String)>,
193 join_type: JoinType,
194 condition: Option<SqlExpr>,
195 limit: usize,
196 /// Post-join projection: column names to keep (empty = all columns).
197 projection: Vec<Projection>,
198 /// Post-join filters (from WHERE clause).
199 filters: Vec<Filter>,
200 },
201
202 // ── Aggregation ──
203 Aggregate {
204 input: Box<SqlPlan>,
205 group_by: Vec<SqlExpr>,
206 aggregates: Vec<AggregateExpr>,
207 having: Vec<Filter>,
208 limit: usize,
209 /// When the GROUP BY contains ROLLUP/CUBE/GROUPING SETS, this field holds
210 /// the expansion. Each inner `Vec<usize>` is one grouping set — the indices
211 /// into `group_by` (the canonical key list) that are *present* (non-NULL)
212 /// for rows in that set. `None` = plain single-set GROUP BY.
213 grouping_sets: Option<Vec<Vec<usize>>>,
214 /// ORDER BY applied to the aggregated rows. Empty = no sort
215 /// (executor returns groups in hash-map iteration order).
216 /// Populated by `apply_order_by` when an outer ORDER BY
217 /// targets a GROUP BY result; the Aggregate executor sorts the
218 /// finalized group rows before returning.
219 sort_keys: Vec<SortKey>,
220 },
221
222 // ── Timeseries ──
223 TimeseriesScan {
224 collection: String,
225 time_range: (i64, i64),
226 bucket_interval_ms: i64,
227 group_by: Vec<String>,
228 aggregates: Vec<AggregateExpr>,
229 filters: Vec<Filter>,
230 projection: Vec<Projection>,
231 gap_fill: String,
232 limit: usize,
233 tiered: bool,
234 /// Bitemporal system-time / valid-time scope. Only non-default
235 /// on collections created `WITH BITEMPORAL`; `TimeseriesRules::plan_scan`
236 /// rejects temporal scopes otherwise.
237 temporal: TemporalScope,
238 },
239 TimeseriesIngest {
240 collection: String,
241 rows: Vec<Vec<(String, SqlValue)>>,
242 },
243
244 // ── Search (first-class) ──
245 VectorSearch {
246 collection: String,
247 field: String,
248 query_vector: Vec<f32>,
249 top_k: usize,
250 ef_search: usize,
251 /// Distance metric requested by the query operator (`<->`, `<=>`, `<#>`).
252 /// Overrides the collection-default metric at search time.
253 metric: DistanceMetric,
254 filters: Vec<Filter>,
255 /// Optional cross-engine prefilter: when set, the ND-array slice
256 /// runs first and its output cells' surrogates form a bitmap that
257 /// gates the HNSW candidate set. Set by the planner when an
258 /// `ORDER BY vector_distance(...) LIMIT k` query is JOINed against
259 /// `ARRAY_SLICE(...)`. The convert layer lowers this to
260 /// `VectorOp::Search { inline_prefilter_plan: Some(ArrayOp::SurrogateBitmapScan) }`.
261 array_prefilter: Option<ArrayPrefilter>,
262 /// ANN knobs parsed from the optional third JSON-string argument
263 /// to `vector_distance(field, query, '{...}')`.
264 ann_options: VectorAnnOptions,
265 /// When `true`, the projection contains only the surrogate/PK column
266 /// and/or `vector_distance(...)` — no payload fields. The Data Plane
267 /// can skip the document-body fetch entirely for vector-primary
268 /// collections. Always `false` for non-vector-primary collections
269 /// (document body is the primary result).
270 skip_payload_fetch: bool,
271 /// Predicates against payload-indexed columns on a vector-primary
272 /// collection. Each atom is `Eq(field, value)`, `In(field, values)`,
273 /// or `Range(field, ...)`. The convert layer translates SqlValue →
274 /// nodedb_types::Value and emits them as
275 /// `VectorOp::Search::payload_filters`. The Data Plane intersects
276 /// the resulting bitmap with the HNSW candidate set via the
277 /// per-collection `PayloadIndexSet::pre_filter`.
278 payload_filters: Vec<SqlPayloadAtom>,
279 },
280 MultiVectorSearch {
281 collection: String,
282 query_vector: Vec<f32>,
283 top_k: usize,
284 ef_search: usize,
285 },
286 TextSearch {
287 collection: String,
288 /// Structured FTS query. Use `FtsQuery::Plain { text, fuzzy }` for
289 /// simple keyword search. `FtsQuery::And/Or/Prefix` are supported;
290 /// `FtsQuery::Phrase` and `FtsQuery::Not` are represented but rejected
291 /// by the executor with `Unsupported`.
292 query: FtsQuery,
293 top_k: usize,
294 filters: Vec<Filter>,
295 /// When set, the SELECT list contains `bm25_score(field, term)` and the
296 /// caller wants a full-collection scan with the score injected under this
297 /// alias. The converter emits `TextOp::BM25ScoreScan` instead of
298 /// `TextOp::Search` so that all documents — including non-matching ones —
299 /// appear in the response with `null` for the score when they do not
300 /// contain the term.
301 score_alias: Option<String>,
302 },
303 HybridSearch {
304 collection: String,
305 query_vector: Vec<f32>,
306 query_text: String,
307 top_k: usize,
308 ef_search: usize,
309 vector_weight: f32,
310 fuzzy: bool,
311 /// SELECT-list alias the response should use for the RRF score
312 /// column. `None` means the executor falls back to the fixed
313 /// internal field name `rrf_score`. Set by the planner from the
314 /// SELECT projection's `AS <alias>` for the `rrf_score(...)` call.
315 score_alias: Option<String>,
316 },
317
318 /// Three-source hybrid search: vector + BM25 text + graph BFS, fused via weighted RRF.
319 ///
320 /// Produced when the planner detects `rrf_score(vector_distance(...),
321 /// bm25_score(...), graph_score(...))` with three source arguments.
322 HybridSearchTriple {
323 collection: String,
324 query_vector: Vec<f32>,
325 query_text: String,
326 /// Node id used as the BFS seed for the graph leg.
327 graph_seed_id: String,
328 /// Maximum BFS depth from the seed node.
329 graph_depth: usize,
330 /// Edge label filter for graph BFS. `None` = all edges.
331 graph_edge_label: Option<String>,
332 top_k: usize,
333 ef_search: usize,
334 fuzzy: bool,
335 /// Per-source RRF k constants: (vector_k, text_k, graph_k).
336 rrf_k: (f64, f64, f64),
337 /// SELECT-list alias for the fused RRF score column.
338 score_alias: Option<String>,
339 },
340 SpatialScan {
341 collection: String,
342 field: String,
343 predicate: SpatialPredicate,
344 query_geometry: nodedb_types::geometry::Geometry,
345 distance_meters: f64,
346 attribute_filters: Vec<Filter>,
347 limit: usize,
348 projection: Vec<Projection>,
349 },
350
351 // ── Composite ──
352 Union {
353 inputs: Vec<SqlPlan>,
354 distinct: bool,
355 },
356 Intersect {
357 left: Box<SqlPlan>,
358 right: Box<SqlPlan>,
359 all: bool,
360 },
361 Except {
362 left: Box<SqlPlan>,
363 right: Box<SqlPlan>,
364 all: bool,
365 },
366 RecursiveScan {
367 collection: String,
368 base_filters: Vec<Filter>,
369 recursive_filters: Vec<Filter>,
370 /// Equi-join link for tree-traversal recursion:
371 /// `(collection_field, working_table_field)`.
372 /// e.g. `("parent_id", "id")` means each iteration finds rows
373 /// where `collection.parent_id` matches a `working_table.id`.
374 join_link: Option<(String, String)>,
375 max_iterations: usize,
376 distinct: bool,
377 limit: usize,
378 },
379
380 /// Value-generating recursive CTE (`WITH RECURSIVE name(cols) AS (anchor UNION [ALL] step)`).
381 ///
382 /// Unlike `RecursiveScan`, this variant carries no collection reference — the anchor
383 /// row is produced entirely from literal expressions and each iteration applies the
384 /// step expressions to the previous row. The executor evaluates this iteratively
385 /// in the Data Plane without touching storage.
386 ///
387 /// All expressions are stored as raw SQL text so they can be serialised across the
388 /// SPSC bridge without requiring `SqlExpr` to implement `Serialize`. The executor
389 /// parses them at execution time via the same lightweight expression evaluator used
390 /// by the procedural executor.
391 RecursiveValue {
392 /// CTE name (used in error messages).
393 cte_name: String,
394 /// Column names declared on the CTE (e.g. `(n)` in `c(n) AS ...`).
395 columns: Vec<String>,
396 /// Anchor SELECT expressions as raw SQL text (one per column).
397 init_exprs: Vec<String>,
398 /// Recursive step SELECT expressions as raw SQL text (one per column).
399 /// May reference column names from `columns`.
400 step_exprs: Vec<String>,
401 /// Optional WHERE condition as raw SQL text applied to each new row
402 /// to decide whether to continue. `None` → run until fixed point.
403 condition: Option<String>,
404 /// Maximum iterations before a `RecursionDepthExceeded` error is raised.
405 max_depth: usize,
406 /// `false` → UNION ALL (keep duplicates); `true` → UNION (deduplicate).
407 distinct: bool,
408 },
409
410 /// Non-recursive CTE: execute each definition, then the outer query.
411 Cte {
412 /// CTE definitions: `(name, subquery_plan)`.
413 definitions: Vec<(String, SqlPlan)>,
414 /// The outer query that references CTE names.
415 outer: Box<SqlPlan>,
416 },
417
418 // ── Array (ND sparse) ─────────────────────────────────────
419 /// `CREATE ARRAY <name> DIMS (...) ATTRS (...) TILE_EXTENTS (...)`.
420 /// AST is engine-agnostic — the Origin converter builds the typed
421 /// `nodedb_array::ArraySchema` and persists the catalog row.
422 CreateArray {
423 name: String,
424 dims: Vec<types_array::ArrayDimAst>,
425 attrs: Vec<types_array::ArrayAttrAst>,
426 tile_extents: Vec<i64>,
427 cell_order: types_array::ArrayCellOrderAst,
428 tile_order: types_array::ArrayTileOrderAst,
429 /// Hilbert-prefix bits for vShard routing (1–16, default 8).
430 prefix_bits: u8,
431 /// Audit-retention horizon in milliseconds. `None` = non-bitemporal.
432 audit_retain_ms: Option<u64>,
433 /// Compliance floor for `audit_retain_ms`. `None` = no floor.
434 minimum_audit_retain_ms: Option<u64>,
435 },
436 /// `DROP ARRAY [IF EXISTS] <name>` — pure Control-Plane catalog
437 /// mutation. Per-core array store cleanup happens lazily.
438 DropArray { name: String, if_exists: bool },
439 /// `ALTER ARRAY <name> SET (audit_retain_ms = N, ...)`.
440 ///
441 /// Double-`Option` semantics for each diff field:
442 /// - `None` = key was absent from SET clause → field unchanged.
443 /// - `Some(None)` = key present with value `NULL` → field set to NULL.
444 /// - `Some(Some(v))` = key present with integer value → field set to v.
445 AlterArray {
446 name: String,
447 /// New value for `audit_retain_ms`. `Some(None)` unregisters
448 /// the array from the bitemporal retention registry.
449 audit_retain_ms: Option<Option<i64>>,
450 /// New value for `minimum_audit_retain_ms`. Cannot be NULL.
451 minimum_audit_retain_ms: Option<u64>,
452 },
453 /// `INSERT INTO ARRAY <name> COORDS (...) VALUES (...) [, ...]`.
454 InsertArray {
455 name: String,
456 rows: Vec<types_array::ArrayInsertRow>,
457 },
458 /// `DELETE FROM ARRAY <name> WHERE COORDS IN ((...), (...))`.
459 DeleteArray {
460 name: String,
461 coords: Vec<Vec<types_array::ArrayCoordLiteral>>,
462 },
463 /// `SELECT * FROM ARRAY_SLICE(name, {dim:[lo,hi],..}, [attrs], limit)`.
464 ArraySlice {
465 name: String,
466 slice: types_array::ArraySliceAst,
467 /// Attribute names. Empty = all attrs.
468 attr_projection: Vec<String>,
469 /// 0 = unlimited.
470 limit: u32,
471 /// Bitemporal qualifier. When both axes are `None` / `Any`, the Data
472 /// Plane returns the live (current) state — the default fast path.
473 /// Populated from `AS OF SYSTEM TIME` / `AS OF VALID TIME` clauses.
474 temporal: TemporalScope,
475 },
476 /// `SELECT * FROM ARRAY_PROJECT(name, [attrs])`.
477 ArrayProject {
478 name: String,
479 /// Attribute names. Must be non-empty.
480 attr_projection: Vec<String>,
481 },
482 /// `SELECT * FROM ARRAY_AGG(name, attr, reducer [, group_by_dim])`.
483 ArrayAgg {
484 name: String,
485 attr: String,
486 reducer: types_array::ArrayReducerAst,
487 /// `None` = scalar fold; `Some(name)` = group by that dim.
488 group_by_dim: Option<String>,
489 /// Bitemporal qualifier. When both axes are `None` / `Any`, the Data
490 /// Plane aggregates against the live (current) state — the default
491 /// fast path. Populated from `AS OF SYSTEM TIME` / `AS OF VALID TIME`.
492 temporal: TemporalScope,
493 },
494 /// `SELECT * FROM ARRAY_ELEMENTWISE(left, right, op, attr)`.
495 ArrayElementwise {
496 left: String,
497 right: String,
498 op: types_array::ArrayBinaryOpAst,
499 attr: String,
500 },
501 /// `SELECT ARRAY_FLUSH(name)` — returns one row `{result: BOOL}`.
502 ArrayFlush { name: String },
503 /// `SELECT ARRAY_COMPACT(name)` — returns one row `{result: BOOL}`.
504 ArrayCompact { name: String },
505
506 // ── MERGE ──────────────────────────────────────────────────────────
507 /// `MERGE INTO target USING source ON ... WHEN ... THEN ...`
508 ///
509 /// Supported only for `document_schemaless` and `document_strict` engines.
510 /// The Data Plane handler evaluates WHEN arms in declaration order and
511 /// applies the first matching action to each joined or unmatched row.
512 Merge {
513 target: String,
514 engine: EngineType,
515 /// Source plan (Scan, DocumentIndexLookup, or Join of a sub-select).
516 source: Box<SqlPlan>,
517 /// Column in the target used for the equi-join (from ON clause).
518 target_join_col: String,
519 /// Column in the source used for the equi-join (from ON clause).
520 source_join_col: String,
521 /// Alias used to qualify source columns in expressions (e.g. `src.col`).
522 source_alias: String,
523 /// WHEN arms in declaration order.
524 clauses: Vec<MergePlanClause>,
525 returning: bool,
526 },
527
528 // ── Lateral joins ───────────────────────────────────────────────────
529 /// LATERAL subquery that is equi-correlated and has ORDER BY + LIMIT k.
530 ///
531 /// Emitted when the inner subquery has an equi-key correlation to the outer
532 /// table plus an `ORDER BY ... LIMIT k` clause. The Data Plane scans the
533 /// inner collection once per outer row applying the equi-filter, sorts by
534 /// `inner_order_by`, and retains at most `inner_limit` rows.
535 ///
536 /// `correlation_keys` is `(outer_col, inner_col)` — the equi-join pairs
537 /// that correlate inner to outer.
538 LateralTopK {
539 /// Plan producing outer rows.
540 outer: Box<SqlPlan>,
541 /// Alias used to qualify outer table columns (e.g. `"u"`).
542 outer_alias: Option<String>,
543 /// Inner collection to scan.
544 inner_collection: String,
545 /// Pre-filter applied to inner rows (non-correlated filters).
546 inner_filters: Vec<Filter>,
547 /// Sort keys for the inner per-outer-row result.
548 inner_order_by: Vec<SortKey>,
549 /// Maximum number of inner rows per outer row.
550 inner_limit: usize,
551 /// Equi-join pairs `(outer_col, inner_col)`.
552 correlation_keys: Vec<(String, String)>,
553 /// Alias under which inner rows are presented.
554 lateral_alias: String,
555 /// Post-lateral projection.
556 projection: Vec<Projection>,
557 /// LEFT join semantics: preserve outer rows even when inner is empty.
558 left_join: bool,
559 },
560
561 /// General LATERAL subquery — per-outer-row correlated nested loop.
562 ///
563 /// Emitted for LATERAL subqueries that cannot be rewritten as equi-join
564 /// hash joins or `LateralTopK`. The Control Plane drives execution: it
565 /// materialises outer rows, then for each row substitutes the correlation
566 /// values as additional filters on the inner plan and re-dispatches it.
567 ///
568 /// Bounded by `outer_row_cap`; queries that exceed the cap receive a typed
569 /// `SqlError::Unsupported` before any data is returned.
570 LateralLoop {
571 /// Plan producing outer rows.
572 outer: Box<SqlPlan>,
573 /// Alias used to qualify outer table columns.
574 outer_alias: Option<String>,
575 /// Inner subquery plan (correlation predicates are injected at runtime).
576 inner: Box<SqlPlan>,
577 /// Correlated predicates extracted from the inner WHERE that reference
578 /// outer columns. Each entry is `(inner_field, outer_field)`.
579 correlation_predicates: Vec<(String, String)>,
580 /// Alias under which inner rows are presented.
581 lateral_alias: String,
582 /// Post-lateral projection.
583 projection: Vec<Projection>,
584 /// Maximum outer rows allowed. Queries exceeding this return an error.
585 outer_row_cap: usize,
586 /// LEFT join semantics: preserve outer rows even when inner is empty.
587 left_join: bool,
588 },
589
590 // ── Vector-primary ──────────────────────────────────────────────────
591 /// INSERT into a vector-primary collection.
592 ///
593 /// Emitted by the planner instead of the generic `Insert` variant when the
594 /// target collection has `primary = PrimaryEngine::Vector`. The Data Plane
595 /// routes each row through `VectorOp::DirectUpsert`, bypassing full-document
596 /// MessagePack encoding.
597 VectorPrimaryInsert {
598 collection: String,
599 /// Vector column name (matches `VectorPrimaryConfig::vector_field`).
600 /// Plumbed to `VectorOp::DirectUpsert` so the Data Plane keys its
601 /// HNSW index by `(tid, collection, field)` — the same key the SELECT
602 /// path uses.
603 field: String,
604 /// Collection-level quantization. Applied via `set_quantization` on
605 /// the first DirectUpsert so subsequent seals trigger codec-dispatch
606 /// rebuilds against the configured codec.
607 quantization: nodedb_types::VectorQuantization,
608 /// Payload field names that get equality bitmap indexes. Registered
609 /// via `payload.add_index` on the first DirectUpsert.
610 payload_indexes: Vec<(String, nodedb_types::PayloadIndexKind)>,
611 rows: Vec<VectorPrimaryRow>,
612 },
613}