Enum LogicalPlan 

pub enum LogicalPlan {
    Union {
        left: Box<LogicalPlan>,
        right: Box<LogicalPlan>,
        all: bool,
    },
    Scan {
        label_id: u16,
        labels: Vec<String>,
        variable: String,
        filter: Option<Expr>,
        optional: bool,
    },
    FusedIndexScan {
        label_id: u16,
        labels: Vec<String>,
        variable: String,
        filter: Option<Expr>,
        optional: bool,
        kind: FusionKind,
    },
    FusedIndexScanWrapped {
        inner: Box<LogicalPlan>,
        kind: FusionKind,
    },
    ExtIdLookup {
        variable: String,
        ext_id: String,
        filter: Option<Expr>,
        optional: bool,
    },
    ScanAll {
        variable: String,
        filter: Option<Expr>,
        optional: bool,
    },
    ScanMainByLabels {
        labels: Vec<String>,
        variable: String,
        filter: Option<Expr>,
        optional: bool,
    },
    Empty,
    Unwind {
        input: Box<LogicalPlan>,
        expr: Expr,
        variable: String,
    },
    Traverse {

        input: Box<LogicalPlan>,
        edge_type_ids: Vec<u32>,
        direction: Direction,
        source_variable: String,
        target_variable: String,
        target_label_id: u16,
        step_variable: Option<String>,
        min_hops: usize,
        max_hops: usize,
        optional: bool,
        target_filter: Option<Expr>,
        path_variable: Option<String>,
        edge_properties: HashSet<String>,
        is_variable_length: bool,
        optional_pattern_vars: HashSet<String>,
        scope_match_variables: HashSet<String>,
        edge_filter_expr: Option<Expr>,
        path_mode: PathMode,
        qpp_steps: Option<Vec<QppStepInfo>>,
    
},
    TraverseMainByType {

        type_names: Vec<String>,
        input: Box<LogicalPlan>,
        direction: Direction,
        source_variable: String,
        target_variable: String,
        step_variable: Option<String>,
        min_hops: usize,
        max_hops: usize,
        optional: bool,
        target_filter: Option<Expr>,
        path_variable: Option<String>,
        is_variable_length: bool,
        optional_pattern_vars: HashSet<String>,
        scope_match_variables: HashSet<String>,
        edge_filter_expr: Option<Expr>,
        path_mode: PathMode,
    
},
    Filter {
        input: Box<LogicalPlan>,
        predicate: Expr,
        optional_variables: HashSet<String>,
    },
    Create {
        input: Box<LogicalPlan>,
        pattern: Pattern,
    },
    CreateBatch {
        input: Box<LogicalPlan>,
        patterns: Vec<Pattern>,
    },
    Merge {
        input: Box<LogicalPlan>,
        pattern: Pattern,
        on_match: Option<SetClause>,
        on_create: Option<SetClause>,
    },
    Set {
        input: Box<LogicalPlan>,
        items: Vec<SetItem>,
    },
    Remove {
        input: Box<LogicalPlan>,
        items: Vec<RemoveItem>,
    },
    Delete {
        input: Box<LogicalPlan>,
        items: Vec<Expr>,
        detach: bool,
    },
    Foreach {
        input: Box<LogicalPlan>,
        variable: String,
        list: Expr,
        body: Vec<LogicalPlan>,
    },
    Sort {
        input: Box<LogicalPlan>,
        order_by: Vec<SortItem>,
    },
    Limit {
        input: Box<LogicalPlan>,
        skip: Option<usize>,
        fetch: Option<usize>,
    },
    Aggregate {
        input: Box<LogicalPlan>,
        group_by: Vec<Expr>,
        aggregates: Vec<Expr>,
    },
    Distinct {
        input: Box<LogicalPlan>,
    },
    Window {
        input: Box<LogicalPlan>,
        window_exprs: Vec<Expr>,
    },
    Project {
        input: Box<LogicalPlan>,
        projections: Vec<(Expr, Option<String>)>,
    },
    CrossJoin {
        left: Box<LogicalPlan>,
        right: Box<LogicalPlan>,
    },
    Apply {
        input: Box<LogicalPlan>,
        subquery: Box<LogicalPlan>,
        input_filter: Option<Expr>,
    },
    RecursiveCTE {
        cte_name: String,
        initial: Box<LogicalPlan>,
        recursive: Box<LogicalPlan>,
    },
    ProcedureCall {
        procedure_name: String,
        arguments: Vec<Expr>,
        yield_items: Vec<(String, Option<String>)>,
    },
    SubqueryCall {
        input: Box<LogicalPlan>,
        subquery: Box<LogicalPlan>,
    },
    VectorKnn {
        label_id: u16,
        variable: String,
        property: String,
        query: Expr,
        k: usize,
        threshold: Option<f32>,
    },
    InvertedIndexLookup {
        label_id: u16,
        variable: String,
        property: String,
        terms: Expr,
    },
    ShortestPath {
        input: Box<LogicalPlan>,
        edge_type_ids: Vec<u32>,
        direction: Direction,
        source_variable: String,
        target_variable: String,
        target_label_id: u16,
        path_variable: String,
        min_hops: u32,
        max_hops: u32,
    },
    AllShortestPaths {
        input: Box<LogicalPlan>,
        edge_type_ids: Vec<u32>,
        direction: Direction,
        source_variable: String,
        target_variable: String,
        target_label_id: u16,
        path_variable: String,
        min_hops: u32,
        max_hops: u32,
    },
    QuantifiedPattern {
        input: Box<LogicalPlan>,
        pattern_plan: Box<LogicalPlan>,
        min_iterations: u32,
        max_iterations: u32,
        path_variable: Option<String>,
        start_variable: String,
        binding_variable: String,
    },
    CreateVectorIndex {
        config: VectorIndexConfig,
        if_not_exists: bool,
    },
    CreateFullTextIndex {
        config: FullTextIndexConfig,
        if_not_exists: bool,
    },
    CreateScalarIndex {
        config: ScalarIndexConfig,
        if_not_exists: bool,
    },
    CreateJsonFtsIndex {
        config: JsonFtsIndexConfig,
        if_not_exists: bool,
    },
    DropIndex {
        name: String,
        if_exists: bool,
    },
    ShowIndexes {
        filter: Option<String>,
    },
    Copy {
        target: String,
        source: String,
        is_export: bool,
        options: HashMap<String, Value>,
    },
    Backup {
        destination: String,
        options: HashMap<String, Value>,
    },
    Explain {
        plan: Box<LogicalPlan>,
    },
    ShowDatabase,
    ShowConfig,
    ShowStatistics,
    Vacuum,
    Checkpoint,
    CopyTo {
        label: String,
        path: String,
        format: String,
        options: HashMap<String, Value>,
    },
    CopyFrom {
        label: String,
        path: String,
        format: String,
        options: HashMap<String, Value>,
    },
    CreateLabel(CreateLabel),
    CreateEdgeType(CreateEdgeType),
    AlterLabel(AlterLabel),
    AlterEdgeType(AlterEdgeType),
    DropLabel(DropLabel),
    DropEdgeType(DropEdgeType),
    CreateConstraint(CreateConstraint),
    DropConstraint(DropConstraint),
    ShowConstraints(ShowConstraints),
    BindZeroLengthPath {
        input: Box<LogicalPlan>,
        node_variable: String,
        path_variable: String,
    },
    BindPath {
        input: Box<LogicalPlan>,
        node_variables: Vec<String>,
        edge_variables: Vec<String>,
        path_variable: String,
    },
    LocyProgram {

        strata: Vec<LocyStratum>,
        commands: Vec<LocyCommand>,
        derived_scan_registry: Arc<DerivedScanRegistry>,
        max_iterations: usize,
        timeout: Duration,
        max_derived_bytes: usize,
        deterministic_best_by: bool,
        strict_probability_domain: bool,
        probability_epsilon: f64,
        exact_probability: bool,
        max_bdd_variables: usize,
        top_k_proofs: usize,
        semiring_kind: SemiringKind,
        classifier_registry: Arc<ClassifierRegistry>,
        classifier_cache: Option<Arc<ModelInvocationCache>>,
        classifier_provenance_store: Option<Arc<NeuralProvenanceStore>>,
    
},
    LocyFold {
        input: Box<LogicalPlan>,
        key_columns: Vec<String>,
        fold_bindings: Vec<(String, Expr)>,
        strict_probability_domain: bool,
        probability_epsilon: f64,
    },
    LocyBestBy {
        input: Box<LogicalPlan>,
        key_columns: Vec<String>,
        criteria: Vec<(Expr, bool)>,
    },
    LocyPriority {
        input: Box<LogicalPlan>,
        key_columns: Vec<String>,
    },
    LocyDerivedScan {
        scan_index: usize,
        data: Arc<RwLock<Vec<RecordBatch>>>,
        schema: SchemaRef,
    },
    LocyProject {
        input: Box<LogicalPlan>,
        projections: Vec<(Expr, Option<String>)>,
        target_types: Vec<DataType>,
    },
    LocyModelInvoke {
        input: Box<LogicalPlan>,
        invocations: Vec<ModelInvocation>,
        classifier_registry: Arc<ClassifierRegistry>,
        classifier_cache: Option<Arc<ModelInvocationCache>>,
        classifier_provenance_store: Option<Arc<NeuralProvenanceStore>>,
        path_context_handles: HashMap<String, PathContextHandle>,
    },
}

Logical query plan produced by QueryPlanner.

Each variant represents one step in the Cypher execution pipeline. Plans are tree-structured — leaf nodes produce rows, intermediate nodes transform or join them, and the root node defines the final output.

Variants

Union

UNION / UNION ALL of two sub-plans.

Fields

left: Box<LogicalPlan>

right: Box<LogicalPlan>

all: bool

When true, duplicate rows are preserved (UNION ALL semantics).

Scan

Scan vertices of a single labeled dataset.

Fields

label_id: u16

labels: Vec<String>

variable: String

filter: Option<Expr>

optional: bool

FusedIndexScan

Phase 5a-impl: fused scan over both primary’s index and the forked session’s fork-local index. Emitted by the planner only when (a) the session is forked AND (b) StorageManager::fork_index_exists returns Some(_) for the target column. Otherwise the planner keeps emitting Scan and Lance’s base_paths chain transparently covers parent-inherited indexes.

kind selects the per-type fusion strategy:

• BtreeUnion — union of parent + fork hits, dedup by VID.
• SortedKWayMerge — k-way merge of two pre-sorted streams.
• VidUidForkFirst — probe fork’s branch first, fall back to parent’s UID index on miss.

Fields

label_id: u16

labels: Vec<String>

variable: String

filter: Option<Expr>

optional: bool

kind: FusionKind

FusedIndexScanWrapped

Phase 5b followup: planner-side observability marker for the lossy fusion types. Wraps the original VectorKnn or InvertedIndexLookup (or any future leaf operator whose shape differs from Scan) without changing its fields, so the physical planner can decay it to inner unchanged.

Runtime behavior is identical to running inner directly; the wrap is purely for explain-plan and runtime-stats observability. The actual fusion happens at the BranchedBackend layer (per-branch Lance reads via base_paths), exactly as in Phase 5b’s core ship.

Fields

inner: Box<LogicalPlan>

kind: FusionKind

ExtIdLookup

Lookup vertices by ext_id using the main vertices table. Used when a query references ext_id without specifying a label.

Fields

variable: String

ext_id: String

filter: Option<Expr>

optional: bool

ScanAll

Scan all vertices from main table (MATCH (n) without label). Used for schemaless queries that don’t specify any label.

Fields

variable: String

filter: Option<Expr>

optional: bool

ScanMainByLabels

Scan main table filtering by label name (MATCH (n:Unknown)). Used for labels not defined in schema (schemaless support). Scan main vertices table by label name(s) for schemaless support. When labels has multiple entries, uses intersection semantics (must have ALL labels).

Fields

labels: Vec<String>

variable: String

filter: Option<Expr>

optional: bool

Empty

Produces exactly one empty row (used to bootstrap pipelines with no source).

Unwind

UNWIND: expand a list expression into one row per element.

Fields

input: Box<LogicalPlan>

expr: Expr

variable: String

Traverse

Fields

input: Box<LogicalPlan>

edge_type_ids: Vec<u32>

direction: Direction

source_variable: String

target_variable: String

target_label_id: u16

step_variable: Option<String>

min_hops: usize

max_hops: usize

optional: bool

target_filter: Option<Expr>

path_variable: Option<String>

edge_properties: HashSet<String>

is_variable_length: bool

Whether this is a variable-length pattern (has * range specifier). When true, step_variable holds a list of edges (even for *1..1).

optional_pattern_vars: HashSet<String>

All variables from this OPTIONAL MATCH pattern. When any hop in the pattern fails, ALL these variables should be set to NULL. This ensures proper multi-hop OPTIONAL MATCH semantics.

scope_match_variables: HashSet<String>

Variable names (node + edge) from the current MATCH clause scope. Used for relationship uniqueness scoping: only edge ID columns whose associated variable is in this set participate in uniqueness filtering. Variables from previous disconnected MATCH clauses are excluded.

edge_filter_expr: Option<Expr>

Edge property predicate for VLP inline filtering (instead of post-Filter).

path_mode: PathMode

Path traversal semantics (Trail by default for OpenCypher).

qpp_steps: Option<Vec<QppStepInfo>>

QPP steps for multi-hop quantified path patterns. None for simple VLP patterns; Some for QPP with per-step edge types/constraints. When present, min_hops/max_hops are derived from iterations × steps.len().

TraverseMainByType

Traverse main edges table filtering by type name(s) (MATCH (a)-[:Unknown]->(b)). Used for edge types not defined in schema (schemaless support). Supports OR relationship types like [:KNOWS|HATES] via multiple type_names.

Fields

type_names: Vec<String>

input: Box<LogicalPlan>

direction: Direction

source_variable: String

target_variable: String

step_variable: Option<String>

min_hops: usize

max_hops: usize

optional: bool

target_filter: Option<Expr>

path_variable: Option<String>

is_variable_length: bool

Whether this is a variable-length pattern (has * range specifier). When true, step_variable holds a list of edges (even for *1..1).

optional_pattern_vars: HashSet<String>

All variables from this OPTIONAL MATCH pattern. When any hop in the pattern fails, ALL these variables should be set to NULL.

scope_match_variables: HashSet<String>

Variables belonging to the current MATCH clause scope. Used for relationship uniqueness scoping: only edge columns whose associated variable is in this set participate in uniqueness filtering.

edge_filter_expr: Option<Expr>

Edge property predicate for VLP inline filtering (instead of post-Filter).

path_mode: PathMode

Path traversal semantics (Trail by default for OpenCypher).

Filter

Fields

input: Box<LogicalPlan>

predicate: Expr

optional_variables: HashSet<String>

Variables from OPTIONAL MATCH that should preserve NULL rows. When evaluating the filter, if any of these variables are NULL, the row is preserved regardless of the predicate result.

Create

Fields

input: Box<LogicalPlan>

pattern: Pattern

CreateBatch

Batched CREATE operations for multiple consecutive CREATE clauses.

This variant combines multiple CREATE patterns into a single plan node to avoid deep recursion when executing many CREATEs sequentially.

Fields

input: Box<LogicalPlan>

patterns: Vec<Pattern>

Merge

Fields

input: Box<LogicalPlan>

pattern: Pattern

on_match: Option<SetClause>

on_create: Option<SetClause>

Set

Fields

input: Box<LogicalPlan>

items: Vec<SetItem>

Remove

Fields

input: Box<LogicalPlan>

items: Vec<RemoveItem>

Delete

Fields

input: Box<LogicalPlan>

items: Vec<Expr>

detach: bool

Foreach

FOREACH (variable IN list | clauses)

Fields

input: Box<LogicalPlan>

variable: String

list: Expr

body: Vec<LogicalPlan>

Sort

Fields

input: Box<LogicalPlan>

order_by: Vec<SortItem>

Limit

Fields

input: Box<LogicalPlan>

skip: Option<usize>

fetch: Option<usize>

Aggregate

Fields

input: Box<LogicalPlan>

group_by: Vec<Expr>

aggregates: Vec<Expr>

Distinct

Fields

input: Box<LogicalPlan>

Window

Fields

input: Box<LogicalPlan>

window_exprs: Vec<Expr>

Project

Fields

input: Box<LogicalPlan>

projections: Vec<(Expr, Option<String>)>

CrossJoin

Fields

left: Box<LogicalPlan>

right: Box<LogicalPlan>

Apply

Fields

input: Box<LogicalPlan>

subquery: Box<LogicalPlan>

input_filter: Option<Expr>

RecursiveCTE

Fields

cte_name: String

initial: Box<LogicalPlan>

recursive: Box<LogicalPlan>

ProcedureCall

Fields

procedure_name: String

arguments: Vec<Expr>

yield_items: Vec<(String, Option<String>)>

SubqueryCall

Fields

input: Box<LogicalPlan>

subquery: Box<LogicalPlan>

VectorKnn

Fields

label_id: u16

variable: String

property: String

query: Expr

k: usize

threshold: Option<f32>

InvertedIndexLookup

Fields

label_id: u16

variable: String

property: String

terms: Expr

ShortestPath

Fields

input: Box<LogicalPlan>

edge_type_ids: Vec<u32>

direction: Direction

source_variable: String

target_variable: String

target_label_id: u16

path_variable: String

min_hops: u32

Minimum number of hops (edges) in the path. Default is 1.

max_hops: u32

Maximum number of hops (edges) in the path. Default is u32::MAX (unlimited).

AllShortestPaths

allShortestPaths() - Returns all paths with minimum length

Fields

input: Box<LogicalPlan>

edge_type_ids: Vec<u32>

direction: Direction

source_variable: String

target_variable: String

target_label_id: u16

path_variable: String

min_hops: u32

Minimum number of hops (edges) in the path. Default is 1.

max_hops: u32

Maximum number of hops (edges) in the path. Default is u32::MAX (unlimited).

QuantifiedPattern

Fields

input: Box<LogicalPlan>

pattern_plan: Box<LogicalPlan>

min_iterations: u32

max_iterations: u32

path_variable: Option<String>

start_variable: String

binding_variable: String

CreateVectorIndex

Fields

config: VectorIndexConfig

if_not_exists: bool

CreateFullTextIndex

Fields

config: FullTextIndexConfig

if_not_exists: bool

CreateScalarIndex

Fields

config: ScalarIndexConfig

if_not_exists: bool

CreateJsonFtsIndex

Fields

config: JsonFtsIndexConfig

if_not_exists: bool

DropIndex

Fields

name: String

if_exists: bool

ShowIndexes

Fields

filter: Option<String>

Copy

Fields

target: String

source: String

is_export: bool

options: HashMap<String, Value>

Backup

Fields

destination: String

options: HashMap<String, Value>

Explain

Fields

plan: Box<LogicalPlan>

ShowDatabase

ShowConfig

ShowStatistics

Vacuum

Checkpoint

CopyTo

Fields

label: String

path: String

format: String

options: HashMap<String, Value>

CopyFrom

Fields

label: String

path: String

format: String

options: HashMap<String, Value>

CreateLabel(CreateLabel)

CreateEdgeType(CreateEdgeType)

AlterLabel(AlterLabel)

AlterEdgeType(AlterEdgeType)

DropLabel(DropLabel)

DropEdgeType(DropEdgeType)

CreateConstraint(CreateConstraint)

DropConstraint(DropConstraint)

ShowConstraints(ShowConstraints)

BindZeroLengthPath

Bind a zero-length path (single node pattern with path variable). E.g., p = (a) creates a Path with one node and zero edges.

Fields

input: Box<LogicalPlan>

node_variable: String

path_variable: String

BindPath

Bind a fixed-length path from already-computed node and edge columns. E.g., p = (a)-[r]->(b) or p = (a)-[r1]->(b)-[r2]->(c).

Fields

input: Box<LogicalPlan>

node_variables: Vec<String>

edge_variables: Vec<String>

path_variable: String

LocyProgram

Top-level Locy program: stratified rules + commands.

Fields

strata: Vec<LocyStratum>

commands: Vec<LocyCommand>

derived_scan_registry: Arc<DerivedScanRegistry>

max_iterations: usize

timeout: Duration

max_derived_bytes: usize

deterministic_best_by: bool

strict_probability_domain: bool

probability_epsilon: f64

exact_probability: bool

max_bdd_variables: usize

top_k_proofs: usize

semiring_kind: SemiringKind

Active probability semiring (rollout D-7). Defaults to AddMultProb (Phase 1/2 byte-identical behavior). BddExact is selected by LocyConfig::resolve() when exact_probability is true.

classifier_registry: Arc<ClassifierRegistry>

Phase B Slice 3: per-evaluation registry of neural classifiers keyed by model name. Empty for programs without CREATE MODEL.

classifier_cache: Option<Arc<ModelInvocationCache>>

Phase B follow-up: optional memoization cache. None → runtime creates a fresh per-query cache; Some → shared across queries (caller-managed).

classifier_provenance_store: Option<Arc<NeuralProvenanceStore>>

Phase C B1-B3 follow-up: per-query side-channel store for per-invocation (raw, calibrated, confidence_band) records. Flows alongside classifier_cache into LocyProgramExec.

LocyFold

FOLD operator: lattice-join non-key columns per KEY group.

Fields

input: Box<LogicalPlan>

key_columns: Vec<String>

fold_bindings: Vec<(String, Expr)>

strict_probability_domain: bool

probability_epsilon: f64

LocyBestBy

BEST BY operator: select best row per KEY group by ordered criteria.

Fields

input: Box<LogicalPlan>

key_columns: Vec<String>

criteria: Vec<(Expr, bool)>

(expression, ascending) pairs.

LocyPriority

PRIORITY operator: keep only highest-priority clause’s rows per KEY group.

Fields

input: Box<LogicalPlan>

key_columns: Vec<String>

LocyDerivedScan

Scan a derived relation’s in-memory buffer during fixpoint iteration.

Fields

scan_index: usize

data: Arc<RwLock<Vec<RecordBatch>>>

schema: SchemaRef

LocyProject

Compact projection for Locy YIELD — emits ONLY the listed expressions, without carrying through helper/property columns like the regular Project.

Fields

input: Box<LogicalPlan>

projections: Vec<(Expr, Option<String>)>

target_types: Vec<DataType>

Expected output Arrow type per projection (for CAST support).

LocyModelInvoke

Phase B A4: invoke registered neural classifiers against the input batches and overwrite the per-invocation placeholder column with each row’s predicted probability. Wraps a Locy clause body plan when CompiledClause.model_invocations is non-empty; transparent (passes batches through unchanged) when the list is empty.

Registry and cache are carried on the node so that execute_subplan — which spins up a fresh HybridPhysicalPlanner per call — can lower it to a physical LocyModelInvokeExec without depending on planner-side runtime state.

Fields

input: Box<LogicalPlan>

invocations: Vec<ModelInvocation>

classifier_registry: Arc<ClassifierRegistry>

classifier_cache: Option<Arc<ModelInvocationCache>>

classifier_provenance_store: Option<Arc<NeuralProvenanceStore>>

Phase C B1-B3 follow-up: per-query side-channel store for per-invocation (raw, calibrated, confidence_band) records. LocyModelInvokeExec writes here after each classifier call; EXPLAIN reads via collect_neural_calls to surface NeuralProvenance for ALONG/FOLD-position invocations and Mode B re-execution paths.

path_context_handles: HashMap<String, PathContextHandle>

Phase D D3 runtime: one handle per path_context.source_rule referenced by any invocation on this node. The handle’s data: Arc<RwLock<Vec<RecordBatch>>> is shared with the DerivedScanRegistry; the source rule’s derived facts are already converged by the time this node executes (the dependency-graph builder ensures source rules sit in earlier strata).

Trait Implementations

impl Clone for LogicalPlan

fn clone(&self) -> LogicalPlan

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for LogicalPlan

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

Formats the value using the given formatter.