gqlite 1.8.0 → 1.8.2

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

@@ -0,0 +1,542 @@
+use rustc_hash::FxHashSet;
+
+use crate::{
+  graph,
+  interpreter::{
+    evaluators::{Stack, TryPopInto, eval_instructions},
+    instructions,
+  },
+  prelude::*,
+  store,
+  value::Value,
+  value_table::{self, MutableRowInterface, RowInterface},
+};
+
+pub(crate) mod bfs;
+pub(crate) mod dfs;
+pub(crate) mod group;
+
+/// Extract every Edge-typed value bound among `group_variables` on `row`.
+/// Used by both traversal strategies to determine which edges one
+/// repetition consumed, for trail-uniqueness bookkeeping.
+pub(crate) fn extract_edges(
+  row: &value_table::Row,
+  group_variables: &[value_table::ColId],
+) -> Vec<graph::Key>
+{
+  group_variables
+    .iter()
+    .filter_map(|col| row.get(*col).ok())
+    .filter_map(|val| match val
+    {
+      Value::Edge(e) => Some(e.key()),
+      _ => None,
+    })
+    .collect()
+}
+
+/// Resolves start nodes via `source_instructions`, then filters them
+/// through `source_filter` if present. Identical logic regardless of
+/// which traversal strategy follows.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn resolve_start_nodes<TStore: store::Store>(
+  source_instructions: &instructions::Instructions,
+  source_variable: &Option<value_table::ColId>,
+  source_filter: &instructions::Instructions,
+  store: &TStore,
+  tx: &mut TStore::TransactionBox,
+  graph_name: &str,
+  parameters: &crate::value::ValueMap,
+  row: &value_table::Row,
+) -> Result<Vec<graph::Node>>
+{
+  let mut start_nodes = Vec::new();
+
+  if !source_instructions.is_empty()
+  {
+    let mut eval_stack = Stack::default();
+    eval_instructions(&mut eval_stack, row, source_instructions, parameters)?;
+    let query: store::SelectNodeQuery = eval_stack.try_pop_into()?;
+    start_nodes = store.select_nodes(tx, graph_name, query)?;
+  }
+  else if let Some(src_col) = source_variable
+    && let Value::Node(node) = row.get(*src_col)?
+  {
+    start_nodes.push(node.clone())
+  }
+
+  // Apply source_filter to each start node
+  if !source_filter.is_empty()
+  {
+    start_nodes.retain(|node| {
+      let mut test_row = row.clone();
+      if let Some(sv) = source_variable
+        && let Err(_) = test_row.set(*sv, node.clone().into())
+      {
+        return false;
+      }
+      let mut eval_stack = Stack::default();
+      match eval_instructions(&mut eval_stack, &test_row, source_filter, parameters)
+      {
+        Ok(_) => eval_stack.try_pop_into().unwrap_or(false),
+        Err(_) => false,
+      }
+    });
+  }
+
+  Ok(start_nodes)
+}
+
+/// Checks `destination_filter` against `row`, if present.
+/// Decision made here, not left inconsistent: a filter-evaluation
+/// error is propagated (`?`), not silently treated as "doesn't pass" -
+/// matching `bfs.rs`'s existing choice, not `group.rs`'s
+/// `.unwrap_or(false)`. Swallowing an evaluation error into a silent
+/// non-match would hide a real bug behind what looks like an ordinary
+/// filtered-out candidate.
+pub(crate) fn check_destination_filter(
+  destination_filter: &instructions::Instructions,
+  row: &value_table::Row,
+  parameters: &crate::value::ValueMap,
+) -> Result<bool>
+{
+  if destination_filter.is_empty()
+  {
+    return Ok(true);
+  }
+  let mut eval_stack = Stack::default();
+  eval_instructions(&mut eval_stack, row, destination_filter, parameters)?;
+  eval_stack.try_pop_into()
+}
+
+/// Binds the destination node and assembles the `path_variable`'s
+/// `graph::Path`, reading scalar values from `candidate_row` - which
+/// must be the row as returned from `execute_block_matches` for this
+/// repetition, before `group_variables` columns are overwritten with
+/// their accumulated arrays. This is the exact logic that diverged
+/// between `group.rs` (correct) and `bfs.rs` (still using a
+/// first-node-found heuristic) - extracting it removes the possibility
+/// of that divergence happening again.
+pub(crate) fn bind_destination_and_path(
+  candidate_row: &value_table::Row,
+  group_terminal_variable: value_table::ColId,
+  group_variables: &[value_table::ColId],
+  path_edges: &[graph::Edge],
+  start_node: &graph::Node,
+) -> (Option<graph::Node>, Option<graph::Path>)
+{
+  let terminal_node = match candidate_row.get(group_terminal_variable)
+  {
+    Ok(Value::Node(node)) => Some(node.clone()),
+    _ => None,
+  };
+
+  let path = if !path_edges.is_empty()
+  {
+    let mut nodes = vec![start_node.clone()];
+    for var_col in group_variables
+    {
+      if let Ok(Value::Node(node)) = candidate_row.get(*var_col)
+      {
+        nodes.push(node.clone());
+      }
+    }
+    let path = if nodes.len() > 1
+    {
+      graph::Path::new(
+        start_node.clone(),
+        path_edges
+          .iter()
+          .zip(nodes.iter().skip(1))
+          .map(|(e, n)| (e.clone(), n.clone()))
+          .collect(),
+      )
+    }
+    else
+    {
+      graph::Path::new(start_node.clone(), vec![])
+    };
+    Some(path)
+  }
+  else
+  {
+    None
+  };
+
+  (terminal_node, path)
+}
+
+/// can be reused within a single path traversal. `Trail` ensures no edge is
+/// repeated (the only implemented variant).
+#[derive(Debug, Clone, Copy)]
+pub(crate) enum PathUniqueness
+{
+  /// Trail uniqueness: no edge may be repeated within a single path.
+  /// This is the standard constraint for Cypher path expressions.
+  Trail,
+}
+
+impl PathUniqueness
+{
+  /// Check if an edge can be traversed given the current set of used edges.
+  /// For `Trail`, returns true iff the edge has not been used yet.
+  pub(crate) fn is_reusable(
+    &self,
+    used_edges: &FxHashSet<graph::Key>,
+    edge_key: &graph::Key,
+  ) -> bool
+  {
+    match self
+    {
+      PathUniqueness::Trail => !used_edges.contains(edge_key),
+    }
+  }
+
+  /// Mark an edge as used in the current path traversal.
+  /// For `Trail`, inserts the edge into the used set.
+  pub(crate) fn mark_used(&self, used_edges: &mut FxHashSet<graph::Key>, edge_key: graph::Key)
+  {
+    match self
+    {
+      PathUniqueness::Trail =>
+      {
+        used_edges.insert(edge_key);
+      }
+    }
+  }
+
+  /// Mark an edge as unused when backtracking out of a branch.
+  /// For `Trail`, removes the edge from the used set for future branches.
+  pub(crate) fn mark_unused(&self, used_edges: &mut FxHashSet<graph::Key>, edge_key: &graph::Key)
+  {
+    match self
+    {
+      PathUniqueness::Trail =>
+      {
+        used_edges.remove(edge_key);
+      }
+    }
+  }
+}
+
+/// Executes a `BlockMatch::MatchEdge` against a single row, appending any
+/// resulting rows into `new_rows`.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn execute_match_edge<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::MatchEdge {
+    instructions,
+    left_variable,
+    edge_variable,
+    right_variable,
+    path_variable,
+    filter,
+    directivity,
+    recursive_range,
+  } = block
+  else
+  {
+    unreachable!("execute_match_edge called with a non-MatchEdge block");
+  };
+
+  eval_instructions(stack, row, instructions, parameters)?;
+  let query = stack.try_pop_into()?;
+
+  match recursive_range
+  {
+    None =>
+    {
+      let edges = store.select_edges(tx, graph_name, query, *directivity)?;
+
+      for edge in edges.into_iter()
+      {
+        let mut new_row = row.clone();
+        let (left, right) = if edge.reversed
+        {
+          (edge.path.destination(), edge.path.source())
+        }
+        else
+        {
+          (edge.path.source(), edge.path.destination())
+        };
+
+        if let Some(left_variable) = left_variable
+        {
+          new_row.set(*left_variable, left.to_owned().into())?;
+        }
+        if let Some(right_variable) = right_variable
+        {
+          new_row.set(*right_variable, right.to_owned().into())?;
+        }
+        if let Some(edge_variable) = edge_variable
+        {
+          new_row.set(*edge_variable, edge.path.to_edge().into())?;
+        }
+        if let Some(path_variable) = path_variable
+        {
+          new_row.set(*path_variable, edge.path.to_owned().into())?;
+        }
+
+        let should_add_row = if filter.is_empty()
+        {
+          true
+        }
+        else
+        {
+          let mut stack = Stack::default();
+          stack.push(true);
+          stack.push(edge.path.to_edge());
+          eval_instructions(&mut stack, &new_row, filter, parameters)?;
+          stack.try_pop()?;
+          stack.try_pop_into()?
+        };
+
+        if should_add_row
+        {
+          new_rows.push(new_row);
+        }
+      }
+    }
+    Some(recursive_range) =>
+    {
+      dfs::execute(
+        recursive_range,
+        &query,
+        left_variable,
+        edge_variable,
+        right_variable,
+        path_variable,
+        filter,
+        *directivity,
+        store,
+        tx,
+        graph_name,
+        parameters,
+        row,
+        allow_recursive,
+        new_rows,
+        PathUniqueness::Trail,
+      )?;
+    }
+  }
+
+  Ok(())
+}
+
+/// Dispatch entry point for `MatchQuantifiedPath` execution.
+/// Routes to the appropriate strategy handler (list-capture/DFS, BFS, etc.)
+/// based on the `strategy` field.
+///
+/// This is called from `execute_block_match` when encountering a `MatchQuantifiedPath` block.
+#[allow(clippy::too_many_arguments)]
+pub(crate) fn execute_match_quantified_path<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 { strategy, .. } = block
+  else
+  {
+    unreachable!("execute_match_quantified_path called with a non-MatchQuantifiedPath block");
+  };
+  match strategy
+  {
+    instructions::PathStrategy::Dfs => group::execute(
+      block,
+      store,
+      tx,
+      graph_name,
+      stack,
+      parameters,
+      row,
+      allow_recursive,
+      new_rows,
+    ),
+    instructions::PathStrategy::Bfs { .. } => bfs::execute(
+      block,
+      store,
+      tx,
+      graph_name,
+      stack,
+      parameters,
+      row,
+      allow_recursive,
+      new_rows,
+    ),
+  }
+}
+
+#[cfg(test)]
+mod tests
+{
+  use super::*;
+  use crate::value::Value;
+  use crate::value_table::{ColId, MutableRowInterface, Row};
+
+  #[test]
+  fn test_extract_edges_mixed_types()
+  {
+    // Create a row with capacity for 4 columns
+    let mut row = Row::new(vec![], 4);
+    let col_edge1 = ColId::from(0usize);
+    let col_edge2 = ColId::from(1usize);
+    let col_node = ColId::from(2usize);
+    let col_other = ColId::from(3usize);
+
+    // Create test edges and nodes using default constructors
+    let edge1 = graph::Edge::new(None, Default::default(), vec![], Default::default());
+    let edge2 = graph::Edge::new(None, Default::default(), vec![], Default::default());
+    let node = graph::Node::new(None, Default::default(), vec![], Default::default());
+
+    // Set values in row
+    row.set(col_edge1, Value::Edge(edge1.clone())).unwrap();
+    row.set(col_edge2, Value::Edge(edge2.clone())).unwrap();
+    row.set(col_node, Value::Node(node)).unwrap();
+    row.set(col_other, Value::Null).unwrap();
+
+    let group_variables = vec![col_edge1, col_edge2, col_node, col_other];
+    let edges = extract_edges(&row, &group_variables);
+
+    // Should only extract the two edges
+    assert_eq!(edges.len(), 2);
+  }
+
+  #[test]
+  fn test_extract_edges_no_edges()
+  {
+    let mut row = Row::new(vec![], 2);
+    let col_node = ColId::from(0usize);
+    let col_other = ColId::from(1usize);
+
+    let node = graph::Node::new(None, Default::default(), vec![], Default::default());
+    row.set(col_node, Value::Node(node)).unwrap();
+    row.set(col_other, Value::Null).unwrap();
+
+    let group_variables = vec![col_node, col_other];
+    let edges = extract_edges(&row, &group_variables);
+
+    assert_eq!(edges.len(), 0);
+  }
+
+  #[test]
+  fn test_check_destination_filter_empty_filter()
+  {
+    let row = Row::new(vec![], 0);
+    let empty_filter = instructions::Instructions::default();
+    let params = Default::default();
+
+    let result = check_destination_filter(&empty_filter, &row, &params).unwrap();
+    assert!(result, "Empty filter should always return true");
+  }
+
+  #[test]
+  fn test_bind_destination_and_path_with_edges()
+  {
+    let mut candidate_row = Row::new(vec![], 2);
+    let group_term_col = ColId::from(0usize);
+    let group_var_col = ColId::from(1usize);
+
+    let terminal_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+    let intermediate_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+    let start_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+
+    candidate_row
+      .set(group_term_col, Value::Node(terminal_node.clone()))
+      .unwrap();
+    candidate_row
+      .set(group_var_col, Value::Node(intermediate_node.clone()))
+      .unwrap();
+
+    let edge = graph::Edge::new(None, Default::default(), vec![], Default::default());
+
+    let group_variables = vec![group_var_col];
+    let path_edges = vec![edge.clone()];
+
+    let (dest_node, path) = bind_destination_and_path(
+      &candidate_row,
+      group_term_col,
+      &group_variables,
+      &path_edges,
+      &start_node,
+    );
+
+    assert_eq!(dest_node.unwrap().key(), terminal_node.key());
+    assert!(path.is_some());
+  }
+
+  #[test]
+  fn test_bind_destination_and_path_no_edges()
+  {
+    let mut candidate_row = Row::new(vec![], 1);
+    let group_term_col = ColId::from(0usize);
+
+    let terminal_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+    let start_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+
+    candidate_row
+      .set(group_term_col, Value::Node(terminal_node.clone()))
+      .unwrap();
+
+    let group_variables = vec![];
+    let path_edges = vec![];
+
+    let (dest_node, path) = bind_destination_and_path(
+      &candidate_row,
+      group_term_col,
+      &group_variables,
+      &path_edges,
+      &start_node,
+    );
+
+    assert_eq!(dest_node.unwrap().key(), terminal_node.key());
+    assert!(
+      path.is_none(),
+      "Path should be None when path_edges is empty"
+    );
+  }
+
+  #[test]
+  fn test_bind_destination_and_path_missing_terminal()
+  {
+    let candidate_row = Row::new(vec![], 1);
+    let group_term_col = ColId::from(0usize);
+    let start_node = graph::Node::new(None, Default::default(), vec![], Default::default());
+
+    let group_variables = vec![];
+    let path_edges = vec![];
+
+    let (dest_node, path) = bind_destination_and_path(
+      &candidate_row,
+      group_term_col,
+      &group_variables,
+      &path_edges,
+      &start_node,
+    );
+
+    assert!(
+      dest_node.is_none(),
+      "Destination node should be None if not set"
+    );
+    assert!(
+      path.is_none(),
+      "Path should be None when path_edges is empty"
+    );
+  }
+}