gqlite 1.8.1 → 1.8.2

data/ext/gqlitedb/src/interpreter/path/bfs.rs

@@ -0,0 +1,494 @@
+use rustc_hash::FxHashSet;
+use std::collections::VecDeque;
+
+use crate::{
+  graph,
+  interpreter::{
+    evaluators::{Stack, TryPopInto, eval_instructions},
+    instructions,
+    path::{self, PathUniqueness},
+  },
+  prelude::*,
+  store,
+  value_table::{self, MutableRowInterface, RowInterface},
+};
+
+/// State representing one position in the BFS frontier at a given depth.
+#[derive(Clone)]
+struct FrontierNode
+{
+  row: value_table::Row,
+  depth: usize,
+  path_edges: Vec<graph::Edge>,
+  group_lists: Vec<Vec<value::Value>>,
+  used_edges: FxHashSet<graph::Key>,
+}
+
+/// Execute a quantified path pattern using BFS (breadth-first search) shortest-path strategy.
+///
+/// BFS expands a frontier layer-by-layer by hop distance, stopping when `stop_condition` is satisfied:
+/// - `Shortest(k)`: Stop once k paths reaching destination-filter-passing nodes are found
+/// - `ShortestGroups(k)`: Expand until k distinct depth layers fully drained
+///
+/// Design decisions (WI#673):
+/// 1. Frontier expansion: Layer-by-layer by hop distance
+/// 2. Stop conditions: Support both SHORTEST and SHORTEST GROUPS variants
+/// 3. path_filter: Applied when candidate reaches destination, before admission
+/// 4. group_where_filter: Applied before accepting candidate (same as DFS)
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn execute<TStore: store::Store>(
+  block: &instructions::BlockMatch,
+  store: &TStore,
+  tx: &mut TStore::TransactionBox,
+  graph_name: &str,
+  stack: &mut Stack,
+  parameters: &crate::value::ValueMap,
+  row: &value_table::Row,
+  allow_recursive: bool,
+  new_rows: &mut Vec<value_table::Row>,
+) -> Result<()>
+{
+  let instructions::BlockMatch::MatchQuantifiedPath {
+    source_instructions,
+    source_variable,
+    source_filter,
+    destination_variable,
+    destination_filter,
+    path_variable,
+    quantifier,
+    group_instructions,
+    group_variables,
+    group_terminal_variable,
+    group_entry_variable,
+    group_where_filter,
+    path_filter,
+    strategy,
+  } = block
+  else
+  {
+    unreachable!("execute called with a non-MatchQuantifiedPath block");
+  };
+
+  if !allow_recursive
+  {
+    return Err(InternalError::UnsupportedRecursivePatternInMerge.into());
+  }
+
+  let min_hops = quantifier.start;
+  let max_hops = quantifier.end;
+
+  // Extract stop condition
+  let (stop_condition, is_groups_mode) = match strategy
+  {
+    instructions::PathStrategy::Bfs { stop_condition } => match stop_condition
+    {
+      instructions::StopCondition::Shortest(k_instructions) => (k_instructions, false),
+      instructions::StopCondition::ShortestGroups(k_instructions) => (k_instructions, true),
+    },
+    _ => unreachable!("execute called with non-Bfs strategy"),
+  };
+
+  // Resolve k from stop_condition
+  let k: usize = if !stop_condition.is_empty()
+  {
+    let mut eval_stack = Stack::default();
+    eval_instructions(&mut eval_stack, row, stop_condition, parameters)?;
+    let k_val: i64 = eval_stack.try_pop_into()?;
+    if k_val <= 0
+    {
+      return Err(Error::RunTime(RunTimeError::InvalidArgument {
+        function_name: "SHORTEST",
+        index: 0,
+        expected_type: "positive integer",
+        value: k_val.to_string(),
+      }));
+    }
+    k_val as usize
+  }
+  else
+  {
+    1 // Default to 1 if not specified
+  };
+
+  let capacity = max_hops.min(100);
+  let uniqueness = PathUniqueness::Trail;
+
+  // Resolve start nodes via shared function
+  let start_nodes = path::resolve_start_nodes(
+    source_instructions,
+    source_variable,
+    source_filter,
+    store,
+    tx,
+    graph_name,
+    parameters,
+    row,
+  )?;
+
+  for start_node in start_nodes
+  {
+    // BFS frontier: queue of (position, depth)
+    let mut frontier: VecDeque<FrontierNode> = VecDeque::new();
+
+    // Initialize with starting node(s) from executing group_instructions once
+    let mut position_row = row.clone();
+    if let Some(sv) = source_variable
+    {
+      position_row.set(*sv, start_node.clone().into())?;
+    }
+    // For the first iteration, set the group's entry point to the start node
+    position_row.set(*group_entry_variable, start_node.clone().into())?;
+
+    let initial_candidates = crate::interpreter::evaluators::execute_block_matches(
+      group_instructions,
+      store,
+      tx,
+      graph_name,
+      stack,
+      parameters,
+      vec![position_row],
+      allow_recursive,
+    )?;
+
+    // Add initial candidates to frontier at depth 1 (one real repetition
+    // already completed by the group_instructions execution above - not
+    // zero. Matches dfs.rs's convention: depth means hops taken so far.
+    for initial_row in initial_candidates
+    {
+      // Extract edges and populate group_lists from the initial row
+      let mut initial_path_edges = Vec::with_capacity(capacity);
+      let mut initial_group_lists = vec![Vec::with_capacity(capacity); group_variables.len()];
+
+      for (var_idx, var_col) in group_variables.iter().enumerate()
+      {
+        if let Ok(val) = initial_row.get(*var_col)
+        {
+          initial_group_lists[var_idx].push(val.clone());
+
+          // Add edge to path_edges if this value is an edge
+          if let crate::value::Value::Edge(edge) = val
+          {
+            initial_path_edges.push(edge.clone());
+          }
+        }
+      }
+
+      frontier.push_back(FrontierNode {
+        row: initial_row,
+        depth: 1,
+        path_edges: initial_path_edges,
+        group_lists: initial_group_lists,
+        used_edges: FxHashSet::with_capacity_and_hasher(capacity, Default::default()),
+      });
+    }
+
+    let mut found_paths = 0;
+    let mut depths_completed = 0;
+    let mut current_depth = 0;
+    let mut processing_depth = 0;
+    // Track if the current depth produced at least one admitted row (WI#693)
+    let mut current_depth_admitted_rows = false;
+
+    // Zero-repetition case: if min_hops == 0, the start node itself,
+    // with no edges traversed, is a valid match - nothing else in this
+    // function ever considers this, since initial_candidates always
+    // represents one repetition already completed.
+    if min_hops == 0
+    {
+      let mut zero_row = row.clone();
+      if let Some(sv) = source_variable
+      {
+        zero_row.set(*sv, start_node.clone().into())?;
+      }
+      for var_col in group_variables
+      {
+        zero_row.set(*var_col, value::Value::Array(Vec::new()))?;
+      }
+      if let Some(dv) = destination_variable
+      {
+        zero_row.set(*dv, start_node.clone().into())?;
+      }
+      if let Some(pv) = path_variable
+      {
+        zero_row.set(*pv, graph::Path::new(start_node.clone(), vec![]).into())?;
+      }
+
+      // When destination_variable refers back to source_variable (like pattern "(a) ... (a)"),
+      // the compiler skips building a destination_filter (since the variable is already set).
+      // We must explicitly verify they bind to the same node.
+      let mut skip_zero_row = false;
+      if source_variable.is_some()
+        && destination_variable.is_some()
+        && source_variable == destination_variable
+      {
+        // Extract the source node binding
+        let source_binding = match zero_row.get(source_variable.unwrap())
+        {
+          Ok(value::Value::Node(n)) => Some(n),
+          _ => None,
+        };
+        // Extract the destination node binding (should be start_node for zero-rep case)
+        let dest_binding = match zero_row.get(destination_variable.unwrap())
+        {
+          Ok(value::Value::Node(n)) => Some(n),
+          _ => None,
+        };
+        // For zero-rep case, both should point to start_node, so they should always be equal
+        // This check is mostly defensive; the zero-rep case should always satisfy this.
+        if let (Some(src), Some(dst)) = (source_binding, dest_binding)
+          && src.key() != dst.key()
+        {
+          skip_zero_row = true;
+        }
+      }
+
+      if !skip_zero_row
+        && path::check_destination_filter(destination_filter, &zero_row, parameters)?
+      {
+        new_rows.push(zero_row);
+        found_paths += 1;
+      }
+    }
+
+    // BFS main loop
+    while !frontier.is_empty() && (is_groups_mode || found_paths < k)
+    {
+      let frontier_node = match frontier.pop_front()
+      {
+        Some(fn_) => fn_,
+        None => break,
+      };
+
+      // Track depth changes for SHORTEST GROUPS. This must finalize the
+      // PREVIOUS depth's completion status before this node's own emission
+      // runs - otherwise a row emitted by the first node of a new depth gets
+      // misattributed as evidence the previous depth admitted rows, since
+      // current_depth_admitted_rows would be set by this same node before
+      // the transition check ever reads it.
+      if frontier_node.depth > processing_depth
+      {
+        processing_depth = frontier_node.depth;
+      }
+
+      if is_groups_mode && processing_depth > current_depth
+      {
+        if current_depth_admitted_rows
+        {
+          depths_completed += 1;
+        }
+        current_depth = processing_depth;
+        current_depth_admitted_rows = false;
+
+        if depths_completed >= k
+        {
+          break;
+        }
+      }
+
+      // Check if this node reaches destination and should be emitted
+      if frontier_node.depth >= min_hops
+      {
+        let mut emit_row = row.clone();
+
+        // Bind source node
+        if let Some(sv) = source_variable
+        {
+          emit_row.set(*sv, start_node.clone().into())?;
+        }
+
+        // Bind group variables as arrays, except for source/destination which stay as scalars
+        for (var_idx, var_col) in group_variables.iter().enumerate()
+        {
+          // Skip wrapping source and destination columns - they're already bound
+          // as scalars and should not be overwritten as arrays
+          if Some(*var_col) == *source_variable || Some(*var_col) == *destination_variable
+          {
+            continue;
+          }
+
+          emit_row.set(
+            *var_col,
+            value::Value::Array(frontier_node.group_lists[var_idx].clone()),
+          )?;
+        }
+
+        // Bind destination and path using shared function (fixes first-node-found heuristic in bfs.rs)
+        let (terminal_node, path) = path::bind_destination_and_path(
+          &frontier_node.row,
+          *group_terminal_variable,
+          group_variables,
+          &frontier_node.path_edges,
+          &start_node,
+        );
+
+        // Bind destination node (using pre-computed terminal_node)
+        if let Some(dv) = destination_variable
+          && let Some(ref node) = terminal_node
+        {
+          emit_row.set(*dv, node.clone().into())?;
+        }
+
+        // Save the terminal_node's key BEFORE it gets moved
+        let terminal_node_key = terminal_node.as_ref().map(|n| n.key());
+
+        // Bind path variable (using pre-computed path)
+        if let Some(pv) = path_variable
+          && let Some(path_value) = path
+        {
+          emit_row.set(*pv, path_value.into())?;
+        }
+
+        // Apply path_filter if present
+        let passes_path_filter = if let Some(pf) = path_filter
+        {
+          if pf.is_empty()
+          {
+            true
+          }
+          else
+          {
+            let mut eval_stack = Stack::default();
+            eval_instructions(&mut eval_stack, &emit_row, pf, parameters)?;
+            eval_stack.try_pop_as_boolean()?
+          }
+        }
+        else
+        {
+          true
+        };
+
+        // Apply destination_filter using shared function
+        let passes_destination_filter =
+          path::check_destination_filter(destination_filter, &emit_row, parameters)?;
+
+        // When destination_filter is empty (meaning the destination variable was already set),
+        // and the source and destination variables are the same, check that the destination node
+        // equals the start node (for patterns like "(a) ... (a)").
+        let is_same_variable_different_nodes = if destination_filter.is_empty()
+          && source_variable.is_some()
+          && source_variable == destination_variable
+        {
+          // The destination (terminal_node) must equal the start node
+          if let Some(tnk) = terminal_node_key
+          {
+            tnk != start_node.key()
+          }
+          else
+          {
+            false
+          }
+        }
+        else
+        {
+          false
+        };
+
+        if passes_path_filter && passes_destination_filter && !is_same_variable_different_nodes
+        {
+          new_rows.push(emit_row);
+          found_paths += 1;
+          // Track that this depth produced at least one admitted row (WI#693)
+          if frontier_node.depth == processing_depth
+          {
+            current_depth_admitted_rows = true;
+          }
+
+          // For SHORTEST mode, stop immediately when k is reached
+          if !is_groups_mode && found_paths >= k
+          {
+            break;
+          }
+        }
+      }
+
+      // Expansion is independent of both emission and min_hops: a node
+      // below min_hops still needs to search further, since a longer path
+      // through it might satisfy the minimum even though it doesn't itself.
+      if frontier_node.depth < max_hops
+      {
+        // Repetition N's landing point becomes repetition N+1's starting point.
+        // Nothing does this automatically - group_entry_variable and
+        // group_terminal_variable are different columns.
+        let mut next_row = frontier_node.row.clone();
+        let terminal_value = next_row.get(*group_terminal_variable)?.clone();
+        next_row.set(*group_entry_variable, terminal_value)?;
+
+        // Execute group_instructions to get next candidates
+        let next_candidates = crate::interpreter::evaluators::execute_block_matches(
+          group_instructions,
+          store,
+          tx,
+          graph_name,
+          stack,
+          parameters,
+          vec![next_row],
+          allow_recursive,
+        )?;
+
+        // Add next candidates to frontier
+        for next_row in next_candidates
+        {
+          // Extract edges using shared function
+          let candidate_edges = path::extract_edges(&next_row, group_variables);
+
+          // Check uniqueness
+          let all_available = candidate_edges
+            .iter()
+            .all(|ek| uniqueness.is_reusable(&frontier_node.used_edges, ek));
+
+          if !all_available
+          {
+            continue;
+          }
+
+          // Check group_where_filter
+          if let Some(gwf) = group_where_filter
+            && !gwf.is_empty()
+          {
+            let mut eval_stack = Stack::default();
+            eval_instructions(&mut eval_stack, &next_row, gwf, parameters)?;
+            let passes: bool = eval_stack.try_pop_as_boolean()?;
+            if !passes
+            {
+              continue;
+            }
+          }
+
+          // Create new frontier node
+          let mut new_node = FrontierNode {
+            row: next_row,
+            depth: frontier_node.depth + 1,
+            path_edges: frontier_node.path_edges.clone(),
+            group_lists: frontier_node.group_lists.to_vec(),
+            used_edges: frontier_node.used_edges.clone(),
+          };
+
+          // Mark edges as used
+          for edge_key in &candidate_edges
+          {
+            uniqueness.mark_used(&mut new_node.used_edges, *edge_key);
+          }
+
+          // Push group variable values
+          for (var_idx, var_col) in group_variables.iter().enumerate()
+          {
+            if let Ok(val) = new_node.row.get(*var_col)
+            {
+              new_node.group_lists[var_idx].push(val.clone());
+
+              // Add edge to path_edges
+              if let value::Value::Edge(edge) = val
+              {
+                new_node.path_edges.push(edge.clone());
+              }
+            }
+          }
+
+          frontier.push_back(new_node);
+        }
+      }
+    }
+  }
+
+  Ok(())
+}