wifi-densepose/vendor/ruvector/docs/research/gnn-v2/03-neuro-symbolic-query.md

Neuro-Symbolic Query Execution - Implementation Plan

Overview

Problem Statement

Current vector search in ruvector is purely neural (similarity-based): given a query vector, find the k most similar vectors by cosine/Euclidean distance. However, real-world queries often involve logical constraints that pure vector similarity cannot express:

Examples of Unsupported Queries:

• "Find vectors similar to X AND published after 2023 AND tagged as 'research'"
• "Find vectors similar to X OR similar to Y, EXCLUDING category 'spam'"
• "Find vectors where metadata.price < 100 AND similarity > 0.8"
• "Find vectors in graph community C AND within 2 hops of node N"

Current Limitations:

• No support for boolean logic (AND, OR, NOT)
• Cannot filter by metadata attributes
• Cannot combine vector similarity with graph structure
• Forces post-processing filtering (inefficient)
• No way to express complex multi-modal queries

Performance Impact:

• Retrieving 10,000 vectors then filtering to 10 wastes 99.9% of computation
• No index acceleration for metadata predicates
• Cannot push down filters to HNSW search

Proposed Solution

Neuro-Symbolic Query Execution: A hybrid query engine that combines neural vector similarity with symbolic logical constraints.

Key Components:

1. Query Language: Extend existing Cypher/SQL support with vector similarity operators
2. Hybrid Scoring: Combine vector similarity scores with predicate satisfaction
3. Filter Pushdown: Apply logical constraints during HNSW search (not after)
4. Multi-Modal Indexing: Index metadata attributes alongside vectors
5. Constraint Propagation: Use graph structure to prune search space

Architecture:

Query: "MATCH (v:Vector) WHERE vector_similarity(v.embedding, $query) > 0.8
        AND v.year >= 2023 AND v.category IN ['research', 'papers']
        RETURN v ORDER BY similarity DESC LIMIT 10"

      ↓ Parse & Optimize

Neural Component:        Symbolic Component:
vector_similarity > 0.8  year >= 2023 AND category IN [...]
      ↓                        ↓
  HNSW Search            Metadata Index
      ↓                        ↓
      └──────── Merge ─────────┘
               ↓
        Hybrid Scoring (α * neural + β * symbolic)
               ↓
        Top-K Results

Expected Benefits

Quantified Performance Improvements:

Query Type	Current (Post-Filter)	Neuro-Symbolic	Improvement
Similarity + 1 filter	50ms (10K retrieved)	5ms (100 retrieved)	10x faster
Similarity + 3 filters	200ms (50K retrieved)	8ms (200 retrieved)	25x faster
Complex boolean logic	Not supported	15ms	∞ (new capability)
Multi-modal query	Manual joins	20ms	50x faster

Qualitative Benefits:

• Express complex queries naturally (no manual post-processing)
• Efficient execution with filter pushdown
• Support for real-world use cases (e-commerce, research, RAG)
• Better accuracy through multi-modal fusion
• Graph-aware queries (community detection, path constraints)

Technical Design

Architecture Diagram (ASCII Art)

┌─────────────────────────────────────────────────────────────────┐
│              Neuro-Symbolic Query Execution Pipeline             │
└─────────────────────────────────────────────────────────────────┘

User Query (SQL/Cypher + Vector Similarity)
     │
     │  Example: "SELECT * FROM vectors
     │             WHERE cosine_similarity(embedding, $query) > 0.8
     │             AND category = 'research' AND year >= 2023
     │             ORDER BY similarity DESC LIMIT 10"
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│  Query Parser & AST Builder                                      │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Parse query into Abstract Syntax Tree (AST)               │ │
│  │  ┌──────────────────────────────────────────────────────┐  │ │
│  │  │ SELECT                                               │  │ │
│  │  │   WHERE                                              │  │ │
│  │  │     AND                                              │  │ │
│  │  │       ├─ cosine_similarity(emb, $q) > 0.8 [NEURAL]  │  │ │
│  │  │       ├─ category = 'research'        [SYMBOLIC]    │  │ │
│  │  │       └─ year >= 2023                 [SYMBOLIC]    │  │ │
│  │  │   ORDER BY similarity DESC                           │  │ │
│  │  │   LIMIT 10                                           │  │ │
│  │  └──────────────────────────────────────────────────────┘  │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│  Query Optimizer                                                 │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Analyze predicates and rewrite query for efficiency      │ │
│  │                                                             │ │
│  │  1. Predicate Pushdown:                                    │ │
│  │     Move filters into HNSW search (before candidate gen)   │ │
│  │                                                             │ │
│  │  2. Index Selection:                                       │ │
│  │     Choose best index for symbolic predicates              │ │
│  │     - category: inverted index                             │ │
│  │     - year: range index (B-tree)                           │ │
│  │                                                             │ │
│  │  3. Execution Strategy:                                    │ │
│  │     - If few categories: scan category index first         │ │
│  │     - If similarity selective: HNSW first, then filter     │ │
│  │     - If balanced: hybrid merge                            │ │
│  │                                                             │ │
│  │  4. Hybrid Scoring:                                        │ │
│  │     score = α * neural_sim + β * symbolic_score            │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│  Execution Plan                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Step 1: HNSW Search (neural)                              │ │
│  │    - Target: similarity > 0.8                              │ │
│  │    - Candidate pool: ef=200                                │ │
│  │    - Early termination: collect ~100 candidates            │ │
│  │    - Filter during search: year >= 2023                    │ │
│  │    Output: {node_id, similarity} for ~100 candidates       │ │
│  │                                                             │ │
│  │  Step 2: Symbolic Filtering (metadata index)               │ │
│  │    - Lookup category index: category = 'research'          │ │
│  │    - Intersect with HNSW candidates                        │ │
│  │    Output: {node_id, similarity, metadata} for ~30 nodes   │ │
│  │                                                             │ │
│  │  Step 3: Hybrid Scoring                                    │ │
│  │    - Compute symbolic_score (e.g., recency bonus)          │ │
│  │    - Combined: 0.7 * similarity + 0.3 * symbolic_score     │ │
│  │    Output: {node_id, hybrid_score}                         │ │
│  │                                                             │ │
│  │  Step 4: Top-K Selection                                   │ │
│  │    - Sort by hybrid_score DESC                             │ │
│  │    - Return top 10                                         │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
     │
     ▼
┌─────────────────────────────────────────────────────────────────┐
│  Result Set                                                      │
│  [{id: 42, similarity: 0.95, category: 'research', year: 2024}, │
│   {id: 137, similarity: 0.92, category: 'research', year: 2023},│
│   ...]                                                           │
└─────────────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────────────┐
│              Indexing & Storage Architecture                     │
└─────────────────────────────────────────────────────────────────┘

Vector Data:
┌─────────────────────────────────────────────────────────────────┐
│  HNSW Index (vector similarity)                                  │
│  - Node ID → Embedding vector                                   │
│  - Graph structure for approximate NN search                    │
└─────────────────────────────────────────────────────────────────┘

Metadata Data:
┌─────────────────────────────────────────────────────────────────┐
│  Inverted Index (categorical attributes)                        │
│  - category → {node_ids}                                        │
│  - tag → {node_ids}                                             │
│  - author → {node_ids}                                          │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  B-Tree Index (range attributes)                                │
│  - year → sorted {node_ids}                                     │
│  - price → sorted {node_ids}                                    │
│  - timestamp → sorted {node_ids}                                │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  Roaring Bitmap Index (set operations)                          │
│  - Efficient AND/OR/NOT on node ID sets                         │
│  - Compressed storage for sparse sets                           │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│  Graph Index (structural constraints)                           │
│  - Community membership: community_id → {node_ids}              │
│  - k-hop neighborhoods: precomputed for common queries          │
│  - Path constraints: shortest path caches                       │
└─────────────────────────────────────────────────────────────────┘

Core Data Structures (Rust)

// File: crates/ruvector-query/src/neuro_symbolic/mod.rs

use std::collections::{HashMap, HashSet};
use serde::{Deserialize, Serialize};

/// Neuro-symbolic query execution engine
pub struct NeuroSymbolicEngine {
    /// HNSW index for vector similarity
    hnsw_index: Arc<HnswIndex>,

    /// Metadata indexes (inverted, B-tree, etc.)
    metadata_indexes: MetadataIndexes,

    /// Query optimizer
    optimizer: QueryOptimizer,

    /// Execution planner
    planner: ExecutionPlanner,

    /// Hybrid scoring configuration
    scoring_config: HybridScoringConfig,
}

/// Query representation (SQL/Cypher AST)
#[derive(Debug, Clone)]
pub struct Query {
    /// SELECT clause (which fields to return)
    pub select: Vec<String>,

    /// WHERE clause (predicates)
    pub where_clause: Option<Predicate>,

    /// ORDER BY clause
    pub order_by: Vec<OrderBy>,

    /// LIMIT clause
    pub limit: Option<usize>,

    /// OFFSET clause
    pub offset: Option<usize>,
}

/// Predicate tree (boolean logic)
#[derive(Debug, Clone)]
pub enum Predicate {
    /// Neural predicate: vector similarity
    VectorSimilarity {
        field: String,
        query_vector: Vec<f32>,
        operator: ComparisonOp,  // >, <, =
        threshold: f32,
        metric: SimilarityMetric,  // cosine, euclidean, dot
    },

    /// Symbolic predicate: metadata constraint
    Attribute {
        field: String,
        operator: ComparisonOp,
        value: Value,
    },

    /// Graph predicate: structural constraint
    Graph {
        constraint: GraphConstraint,
    },

    /// Boolean operators
    And(Box<Predicate>, Box<Predicate>),
    Or(Box<Predicate>, Box<Predicate>),
    Not(Box<Predicate>),
}

#[derive(Debug, Clone)]
pub enum GraphConstraint {
    /// Node in community
    InCommunity { community_id: u32 },

    /// Within k hops of node
    WithinKHops { source_node: u32, k: usize },

    /// On path between two nodes
    OnPath { source: u32, target: u32 },

    /// Has edge to node
    ConnectedTo { node_id: u32 },
}

#[derive(Debug, Clone, Copy)]
pub enum ComparisonOp {
    Eq,    // =
    Ne,    // !=
    Lt,    // <
    Le,    // <=
    Gt,    // >
    Ge,    // >=
    In,    // IN (...)
    Like,  // LIKE (string pattern)
}

#[derive(Debug, Clone)]
pub enum Value {
    Int(i64),
    Float(f64),
    String(String),
    Bool(bool),
    List(Vec<Value>),
}

#[derive(Debug, Clone, Copy)]
pub enum SimilarityMetric {
    Cosine,
    Euclidean,
    DotProduct,
    L1,
}

/// Metadata indexing structures
pub struct MetadataIndexes {
    /// Inverted indexes for categorical fields
    inverted: HashMap<String, InvertedIndex>,

    /// B-tree indexes for range queries
    btree: HashMap<String, BTreeIndex>,

    /// Roaring bitmap for set operations
    bitmap_store: BitmapStore,

    /// Graph structural indexes
    graph_index: GraphStructureIndex,
}

/// Inverted index: field_value → {node_ids}
pub struct InvertedIndex {
    /// Map from value to posting list (node IDs)
    postings: HashMap<String, RoaringBitmap>,

    /// Statistics for query optimization
    stats: IndexStats,
}

/// B-tree index for range queries
pub struct BTreeIndex {
    /// Sorted map from value to node IDs
    tree: BTreeMap<OrderedValue, RoaringBitmap>,

    /// Statistics
    stats: IndexStats,
}

/// Roaring bitmap store for efficient set operations
pub struct BitmapStore {
    /// Node ID sets as compressed bitmaps
    bitmaps: HashMap<String, RoaringBitmap>,
}

/// Graph structure indexes
pub struct GraphStructureIndex {
    /// Community assignments
    communities: HashMap<u32, RoaringBitmap>,

    /// k-hop neighborhoods (precomputed)
    khop_cache: HashMap<(u32, usize), RoaringBitmap>,

    /// Shortest path cache
    path_cache: PathCache,
}

#[derive(Debug, Default)]
pub struct IndexStats {
    pub num_unique_values: usize,
    pub total_postings: usize,
    pub avg_posting_length: f64,
    pub selectivity: f64,  // fraction of nodes matching
}

/// Query execution plan
#[derive(Debug)]
pub struct ExecutionPlan {
    /// Ordered steps to execute
    pub steps: Vec<ExecutionStep>,

    /// Estimated cost
    pub estimated_cost: f64,

    /// Estimated result size
    pub estimated_results: usize,
}

#[derive(Debug)]
pub enum ExecutionStep {
    /// HNSW vector search
    VectorSearch {
        query_vector: Vec<f32>,
        similarity_threshold: f32,
        metric: SimilarityMetric,
        ef: usize,
        filters: Vec<InlineFilter>,  // Filters applied during search
    },

    /// Metadata index lookup
    IndexScan {
        index_name: String,
        predicate: Predicate,
    },

    /// Graph structure traversal
    GraphTraversal {
        constraint: GraphConstraint,
    },

    /// Set intersection (AND)
    Intersect {
        left: Box<ExecutionStep>,
        right: Box<ExecutionStep>,
    },

    /// Set union (OR)
    Union {
        left: Box<ExecutionStep>,
        right: Box<ExecutionStep>,
    },

    /// Set difference (NOT)
    Difference {
        left: Box<ExecutionStep>,
        right: Box<ExecutionStep>,
    },

    /// Hybrid scoring
    HybridScore {
        neural_scores: HashMap<u32, f32>,
        symbolic_scores: HashMap<u32, f32>,
        alpha: f32,  // neural weight
        beta: f32,   // symbolic weight
    },

    /// Top-K selection
    TopK {
        input: Box<ExecutionStep>,
        k: usize,
        order_by: Vec<OrderBy>,
    },
}

/// Filter applied during HNSW search (pushdown)
#[derive(Debug, Clone)]
pub struct InlineFilter {
    pub field: String,
    pub operator: ComparisonOp,
    pub value: Value,
}

/// Hybrid scoring configuration
#[derive(Debug, Clone)]
pub struct HybridScoringConfig {
    /// Weight for neural similarity score
    pub neural_weight: f32,

    /// Weight for symbolic score
    pub symbolic_weight: f32,

    /// Normalization method
    pub normalization: NormalizationMethod,
}

#[derive(Debug, Clone, Copy)]
pub enum NormalizationMethod {
    /// Min-max normalization [0, 1]
    MinMax,

    /// Z-score normalization
    ZScore,

    /// None (assume scores already normalized)
    None,
}

/// Query result
#[derive(Debug, Serialize, Deserialize)]
pub struct QueryResult {
    /// Matched node IDs
    pub node_ids: Vec<u32>,

    /// Neural similarity scores
    pub neural_scores: Vec<f32>,

    /// Symbolic scores (if applicable)
    pub symbolic_scores: Option<Vec<f32>>,

    /// Hybrid scores
    pub hybrid_scores: Vec<f32>,

    /// Metadata for each result
    pub metadata: Vec<HashMap<String, Value>>,

    /// Query execution statistics
    pub stats: QueryStats,
}

#[derive(Debug, Serialize, Deserialize, Default)]
pub struct QueryStats {
    /// Total execution time (milliseconds)
    pub total_time_ms: f64,

    /// Time breakdown by step
    pub step_times: Vec<(String, f64)>,

    /// Number of candidates evaluated
    pub candidates_evaluated: usize,

    /// Number of results returned
    pub results_returned: usize,

    /// Index usage
    pub indexes_used: Vec<String>,
}

#[derive(Debug, Clone)]
pub struct OrderBy {
    pub field: String,
    pub direction: SortDirection,
}

#[derive(Debug, Clone, Copy)]
pub enum SortDirection {
    Asc,
    Desc,
}

/// Wrapper for ordered values in B-tree
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum OrderedValue {
    Int(i64),
    Float(OrderedFloat<f64>),
    String(String),
}

use ordered_float::OrderedFloat;
use roaring::RoaringBitmap;
use std::collections::BTreeMap;
use std::sync::Arc;

Key Algorithms (Pseudocode)

1. Query Execution Algorithm

function execute_neuro_symbolic_query(query: Query, engine: NeuroSymbolicEngine) -> QueryResult:
    """
    Execute neuro-symbolic query with hybrid scoring.

    Main algorithm: parse → optimize → plan → execute → score → return
    """
    start_time = now()

    # Step 1: Parse query into AST (already done, query is AST)
    # Step 2: Optimize query (predicate pushdown, index selection)
    optimized_query = engine.optimizer.optimize(query)

    # Step 3: Generate execution plan
    plan = engine.planner.create_plan(optimized_query)

    # Step 4: Execute plan steps
    result_set = execute_plan(plan, engine)

    # Step 5: Hybrid scoring
    if has_both_neural_and_symbolic(plan):
        result_set = apply_hybrid_scoring(
            result_set,
            engine.scoring_config
        )

    # Step 6: Apply ORDER BY and LIMIT
    result_set = sort_and_limit(
        result_set,
        query.order_by,
        query.limit,
        query.offset
    )

    # Step 7: Fetch metadata for results
    metadata = fetch_metadata(result_set.node_ids, query.select)

    execution_time = now() - start_time

    return QueryResult(
        node_ids=result_set.node_ids,
        neural_scores=result_set.neural_scores,
        symbolic_scores=result_set.symbolic_scores,
        hybrid_scores=result_set.hybrid_scores,
        metadata=metadata,
        stats=QueryStats(
            total_time_ms=execution_time,
            candidates_evaluated=result_set.candidates_evaluated,
            results_returned=len(result_set.node_ids),
            indexes_used=plan.indexes_used
        )
    )


function execute_plan(plan: ExecutionPlan, engine: NeuroSymbolicEngine) -> IntermediateResult:
    """
    Recursively execute plan steps.
    """
    results = None

    for step in plan.steps:
        match step:
            case VectorSearch:
                # HNSW search with optional filters
                results = execute_vector_search(step, engine.hnsw_index)

            case IndexScan:
                # Lookup in metadata index
                results = execute_index_scan(step, engine.metadata_indexes)

            case GraphTraversal:
                # Graph structure query
                results = execute_graph_traversal(step, engine.metadata_indexes.graph_index)

            case Intersect:
                # AND: set intersection
                left = execute_plan_step(step.left, engine)
                right = execute_plan_step(step.right, engine)
                results = intersect_results(left, right)

            case Union:
                # OR: set union
                left = execute_plan_step(step.left, engine)
                right = execute_plan_step(step.right, engine)
                results = union_results(left, right)

            case Difference:
                # NOT: set difference
                left = execute_plan_step(step.left, engine)
                right = execute_plan_step(step.right, engine)
                results = difference_results(left, right)

            case HybridScore:
                # Compute hybrid scores
                results = compute_hybrid_scores(
                    step.neural_scores,
                    step.symbolic_scores,
                    step.alpha,
                    step.beta
                )

            case TopK:
                # Select top-k results
                input_results = execute_plan_step(step.input, engine)
                results = select_top_k(input_results, step.k, step.order_by)

    return results


function execute_vector_search(step: VectorSearch, hnsw: HnswIndex) -> IntermediateResult:
    """
    HNSW search with filter pushdown.

    Key optimization: Apply symbolic filters during HNSW traversal
    to avoid generating candidates that will be filtered out anyway.
    """
    query_vector = step.query_vector
    similarity_threshold = step.similarity_threshold
    ef = step.ef
    inline_filters = step.filters

    # HNSW search with inline filtering
    candidates = []
    visited = set()

    # Start from entry point
    current_node = hnsw.entry_point
    layer = hnsw.max_layer

    while layer >= 0:
        # Greedy search at this layer
        while True:
            neighbors = hnsw.get_neighbors(current_node, layer)
            best_neighbor = None
            best_distance = float('inf')

            for neighbor in neighbors:
                if neighbor in visited:
                    continue

                # Apply inline filters BEFORE computing distance
                if not passes_inline_filters(neighbor, inline_filters, hnsw.metadata):
                    continue  # Skip this neighbor entirely

                # Compute distance only for filtered candidates
                distance = compute_distance(query_vector, hnsw.get_vector(neighbor))
                similarity = distance_to_similarity(distance, step.metric)

                if similarity >= similarity_threshold:
                    candidates.append((neighbor, similarity))

                if distance < best_distance:
                    best_distance = distance
                    best_neighbor = neighbor

                visited.add(neighbor)

            if best_neighbor is None:
                break  # No improvement

            current_node = best_neighbor

        layer -= 1

    # Sort candidates by similarity
    candidates.sort(key=lambda x: x[1], reverse=True)

    return IntermediateResult(
        node_ids=[node_id for node_id, _ in candidates],
        neural_scores=[score for _, score in candidates],
        candidates_evaluated=len(visited)
    )


function passes_inline_filters(node_id: u32, filters: List[InlineFilter], metadata: MetadataStore) -> bool:
    """
    Check if node passes all inline filters.

    This avoids computing distance for nodes that fail metadata constraints.
    """
    for filter in filters:
        node_value = metadata.get(node_id, filter.field)
        if not evaluate_predicate(node_value, filter.operator, filter.value):
            return False  # Failed a filter

    return True  # Passed all filters


function execute_index_scan(step: IndexScan, indexes: MetadataIndexes) -> IntermediateResult:
    """
    Scan metadata index to get matching node IDs.
    """
    index_name = step.index_name
    predicate = step.predicate

    match predicate:
        case Attribute(field, operator, value):
            if operator == ComparisonOp.Eq:
                # Exact match: use inverted index
                posting_list = indexes.inverted[field].lookup(value)
                return IntermediateResult(
                    node_ids=posting_list.to_vec(),
                    symbolic_scores=[1.0] * len(posting_list)  # Binary: matches or not
                )

            elif operator in [ComparisonOp.Lt, ComparisonOp.Le, ComparisonOp.Gt, ComparisonOp.Ge]:
                # Range query: use B-tree index
                matching_nodes = indexes.btree[field].range_query(operator, value)
                return IntermediateResult(
                    node_ids=matching_nodes.to_vec(),
                    symbolic_scores=[1.0] * len(matching_nodes)
                )

            elif operator == ComparisonOp.In:
                # IN query: union of inverted index lookups
                all_nodes = RoaringBitmap()
                for v in value.list:
                    posting_list = indexes.inverted[field].lookup(v)
                    all_nodes |= posting_list  # Union

                return IntermediateResult(
                    node_ids=all_nodes.to_vec(),
                    symbolic_scores=[1.0] * len(all_nodes)
                )


function execute_graph_traversal(step: GraphTraversal, graph_index: GraphStructureIndex) -> IntermediateResult:
    """
    Execute graph structural constraint.
    """
    match step.constraint:
        case InCommunity(community_id):
            # Lookup precomputed community membership
            node_ids = graph_index.communities.get(community_id)
            return IntermediateResult(
                node_ids=node_ids.to_vec(),
                symbolic_scores=[1.0] * len(node_ids)
            )

        case WithinKHops(source_node, k):
            # Lookup precomputed k-hop neighborhood
            key = (source_node, k)
            if key in graph_index.khop_cache:
                node_ids = graph_index.khop_cache[key]
            else:
                # Compute on-the-fly via BFS
                node_ids = compute_khop_neighbors(source_node, k, graph_index.graph)

            return IntermediateResult(
                node_ids=node_ids.to_vec(),
                symbolic_scores=[1.0 / (1 + distance)] for distance in range(len(node_ids))
            )

        case OnPath(source, target):
            # Check path cache
            path_nodes = graph_index.path_cache.get_path(source, target)
            return IntermediateResult(
                node_ids=path_nodes,
                symbolic_scores=[1.0] * len(path_nodes)
            )


function intersect_results(left: IntermediateResult, right: IntermediateResult) -> IntermediateResult:
    """
    Set intersection (AND): keep nodes in both sets.

    Use Roaring Bitmap for efficient intersection.
    """
    left_bitmap = RoaringBitmap.from_sorted(left.node_ids)
    right_bitmap = RoaringBitmap.from_sorted(right.node_ids)

    intersection = left_bitmap & right_bitmap  # Bitmap AND

    # Combine scores (average for simplicity)
    node_ids = intersection.to_vec()
    combined_scores = []
    for node_id in node_ids:
        left_score = left.get_score(node_id)
        right_score = right.get_score(node_id)
        combined_scores.append((left_score + right_score) / 2.0)

    return IntermediateResult(
        node_ids=node_ids,
        scores=combined_scores
    )


function apply_hybrid_scoring(result_set, config: HybridScoringConfig) -> IntermediateResult:
    """
    Combine neural and symbolic scores.

    Formula: hybrid_score = α * normalize(neural) + β * normalize(symbolic)
    """
    neural_scores = result_set.neural_scores
    symbolic_scores = result_set.symbolic_scores

    # Normalize scores to [0, 1]
    if config.normalization == NormalizationMethod.MinMax:
        neural_norm = min_max_normalize(neural_scores)
        symbolic_norm = min_max_normalize(symbolic_scores)
    elif config.normalization == NormalizationMethod.ZScore:
        neural_norm = z_score_normalize(neural_scores)
        symbolic_norm = z_score_normalize(symbolic_scores)
    else:
        neural_norm = neural_scores
        symbolic_norm = symbolic_scores

    # Combine with weights
    alpha = config.neural_weight
    beta = config.symbolic_weight
    hybrid_scores = [
        alpha * n + beta * s
        for n, s in zip(neural_norm, symbolic_norm)
    ]

    result_set.hybrid_scores = hybrid_scores
    return result_set

2. Query Optimization

function optimize_query(query: Query, optimizer: QueryOptimizer) -> Query:
    """
    Optimize query execution plan.

    Key optimizations:
    1. Predicate pushdown (filters into HNSW search)
    2. Index selection (choose best index for each predicate)
    3. Join reordering (cheapest predicates first)
    4. Early termination (stop when enough candidates found)
    """
    # Extract predicates from WHERE clause
    predicates = extract_predicates(query.where_clause)

    # Classify predicates
    neural_preds = [p for p in predicates if is_neural_predicate(p)]
    symbolic_preds = [p for p in predicates if is_symbolic_predicate(p)]
    graph_preds = [p for p in predicates if is_graph_predicate(p)]

    # Estimate selectivity for each predicate
    selectivities = {}
    for pred in predicates:
        selectivities[pred] = estimate_selectivity(pred, optimizer.stats)

    # Predicate pushdown: which filters can be applied during HNSW search?
    inline_filters = []
    post_filters = []

    for pred in symbolic_preds:
        if can_pushdown(pred):
            inline_filters.append(pred)
        else:
            post_filters.append(pred)

    # Index selection: choose best index for each symbolic predicate
    index_plan = {}
    for pred in symbolic_preds:
        best_index = choose_best_index(pred, optimizer.indexes, selectivities[pred])
        index_plan[pred] = best_index

    # Reorder predicates: most selective first
    ordered_predicates = sorted(predicates, key=lambda p: selectivities[p])

    # Build optimized execution plan
    optimized_query = rewrite_query(
        query,
        inline_filters=inline_filters,
        post_filters=post_filters,
        index_plan=index_plan,
        predicate_order=ordered_predicates
    )

    return optimized_query


function estimate_selectivity(predicate, stats) -> float:
    """
    Estimate fraction of nodes matching predicate.

    Uses index statistics (histograms, cardinality, etc.)
    """
    match predicate:
        case VectorSimilarity(threshold):
            # Estimate based on similarity distribution
            return estimate_similarity_selectivity(threshold, stats.similarity_histogram)

        case Attribute(field, operator, value):
            # Estimate based on attribute distribution
            if operator == ComparisonOp.Eq:
                return 1.0 / stats.cardinality[field]  # Uniform assumption
            elif operator in [Lt, Le, Gt, Ge]:
                return estimate_range_selectivity(field, operator, value, stats)
            elif operator == In:
                return len(value.list) / stats.cardinality[field]

        case Graph(constraint):
            # Estimate based on graph structure
            match constraint:
                case InCommunity(id):
                    return stats.community_sizes[id] / stats.total_nodes
                case WithinKHops(node, k):
                    return estimate_khop_size(node, k, stats) / stats.total_nodes


function can_pushdown(predicate) -> bool:
    """
    Check if predicate can be pushed into HNSW search.

    Only simple equality/range predicates on indexed fields can be pushed down.
    """
    match predicate:
        case Attribute(field, operator, value):
            # Can pushdown if operator is simple and field is indexed
            return operator in [Eq, Lt, Le, Gt, Ge, In] and is_indexed(field)

        case _:
            return False  # Complex predicates handled post-search

API Design (Function Signatures)

// File: crates/ruvector-query/src/neuro_symbolic/mod.rs

impl NeuroSymbolicEngine {
    /// Create a new neuro-symbolic query engine
    pub fn new(
        hnsw_index: Arc<HnswIndex>,
        metadata_path: impl AsRef<Path>,
    ) -> Result<Self, QueryError>;

    /// Execute a query (SQL or Cypher syntax)
    pub fn execute_query(
        &self,
        query: &str,
    ) -> Result<QueryResult, QueryError>;

    /// Execute a parsed query (AST)
    pub fn execute_parsed_query(
        &self,
        query: Query,
    ) -> Result<QueryResult, QueryError>;

    /// Add metadata index for a field
    pub fn create_index(
        &mut self,
        field: &str,
        index_type: IndexType,
    ) -> Result<(), QueryError>;

    /// Update hybrid scoring configuration
    pub fn set_scoring_config(&mut self, config: HybridScoringConfig);

    /// Get query execution statistics
    pub fn stats(&self) -> QueryEngineStats;
}

#[derive(Debug, Clone, Copy)]
pub enum IndexType {
    Inverted,  // Categorical fields
    BTree,     // Range queries
    Bitmap,    // Set operations
}

impl Query {
    /// Parse SQL query string into AST
    pub fn parse_sql(query: &str) -> Result<Self, ParseError>;

    /// Parse Cypher query string into AST
    pub fn parse_cypher(query: &str) -> Result<Self, ParseError>;

    /// Validate query syntax and semantics
    pub fn validate(&self) -> Result<(), ValidationError>;
}

impl Predicate {
    /// Evaluate predicate on a node
    pub fn evaluate(
        &self,
        node_id: u32,
        vector_store: &VectorStore,
        metadata_store: &MetadataStore,
    ) -> bool;

    /// Extract referenced fields
    pub fn referenced_fields(&self) -> Vec<String>;

    /// Check if predicate is neural (vector similarity)
    pub fn is_neural(&self) -> bool;

    /// Check if predicate is symbolic (metadata)
    pub fn is_symbolic(&self) -> bool;

    /// Check if predicate is graph-structural
    pub fn is_graph_structural(&self) -> bool;
}

impl MetadataIndexes {
    /// Create indexes from metadata file
    pub fn from_metadata(path: impl AsRef<Path>) -> Result<Self, IndexError>;

    /// Add inverted index for field
    pub fn add_inverted_index(
        &mut self,
        field: &str,
        values: HashMap<String, Vec<u32>>,
    ) -> Result<(), IndexError>;

    /// Add B-tree index for field
    pub fn add_btree_index(
        &mut self,
        field: &str,
        values: Vec<(OrderedValue, u32)>,
    ) -> Result<(), IndexError>;

    /// Query inverted index
    pub fn query_inverted(
        &self,
        field: &str,
        value: &str,
    ) -> Option<&RoaringBitmap>;

    /// Query B-tree index (range)
    pub fn query_btree_range(
        &self,
        field: &str,
        operator: ComparisonOp,
        value: OrderedValue,
    ) -> Option<RoaringBitmap>;

    /// Intersect bitmaps (AND operation)
    pub fn intersect(&self, bitmaps: &[RoaringBitmap]) -> RoaringBitmap;

    /// Union bitmaps (OR operation)
    pub fn union(&self, bitmaps: &[RoaringBitmap]) -> RoaringBitmap;

    /// Difference bitmaps (NOT operation)
    pub fn difference(&self, left: &RoaringBitmap, right: &RoaringBitmap) -> RoaringBitmap;
}

#[derive(Debug, Default)]
pub struct QueryEngineStats {
    pub total_queries: u64,
    pub avg_query_time_ms: f64,
    pub cache_hit_rate: f64,
    pub avg_candidates_evaluated: f64,
}

Integration Points

Affected Crates/Modules

1. ruvector-query (New Crate)

   • New module: src/neuro_symbolic/mod.rs - Core engine
   • New module: src/neuro_symbolic/parser.rs - SQL/Cypher parser
   • New module: src/neuro_symbolic/optimizer.rs - Query optimizer
   • New module: src/neuro_symbolic/planner.rs - Execution planner
   • New module: src/neuro_symbolic/indexes.rs - Metadata indexing

2. ruvector-core (Integration)

   • Modified: src/index/hnsw.rs - Add filter callback support
   • Modified: src/vector_store.rs - Expose metadata API

3. ruvector-api (Exposure)

   • Modified: src/query.rs - Add neuro-symbolic query endpoint
   • New: src/query/sql.rs - SQL query interface
   • New: src/query/cypher.rs - Cypher query interface

4. ruvector-bindings (Language Bindings)

   • Modified: python/src/lib.rs - Expose query API
   • Modified: nodejs/src/lib.rs - Expose query API

New Modules to Create

crates/ruvector-query/   # New crate
├── src/
│   ├── neuro_symbolic/
│   │   ├── mod.rs              # Core engine
│   │   ├── parser.rs           # Query parsing
│   │   ├── optimizer.rs        # Query optimization
│   │   ├── planner.rs          # Execution planning
│   │   ├── executor.rs         # Query execution
│   │   ├── indexes.rs          # Metadata indexing
│   │   ├── scoring.rs          # Hybrid scoring
│   │   └── stats.rs            # Statistics collection
│   └── lib.rs

examples/
├── neuro_symbolic_queries/
│   ├── sql_examples.rs         # SQL query examples
│   ├── cypher_examples.rs      # Cypher query examples
│   ├── hybrid_scoring.rs       # Hybrid scoring examples
│   └── README.md

Dependencies on Other Features

Depends On:

• HNSW Index: Core vector search functionality
• Existing Cypher Support: Extend existing graph query support

Synergies With:

• GNN-Guided Routing (Feature 1): Can use GNN for smarter query execution
• Incremental Learning (Feature 2): Real-time index updates support streaming queries

External Dependencies:

• sqlparser - SQL parsing
• cypher-parser - Cypher parsing (if not already present)
• roaring - Roaring Bitmap for efficient set operations
• serde - Query serialization

Regression Prevention

What Existing Functionality Could Break

1. Pure Vector Search Performance

   • Risk: Adding metadata lookups slows down simple vector queries
   • Impact: Regression in baseline HNSW performance

2. Memory Usage

   • Risk: Metadata indexes consume excessive RAM
   • Impact: OOM on large datasets

3. Query Correctness

   • Risk: Filter pushdown logic has bugs, returns wrong results
   • Impact: Incorrect search results

4. Cypher Compatibility

   • Risk: Extending Cypher syntax breaks existing queries
   • Impact: Breaking change for existing users

Test Cases to Prevent Regressions

// File: crates/ruvector-query/tests/neuro_symbolic_regression_tests.rs

#[test]
fn test_pure_vector_search_unchanged() {
    // Simple vector queries should have zero overhead
    let engine = setup_test_engine();

    // Baseline: pure HNSW search (no filters)
    let query_baseline = "SELECT * FROM vectors ORDER BY similarity(embedding, $query) DESC LIMIT 10";

    let start = Instant::now();
    let results = engine.execute_query(query_baseline).unwrap();
    let time_with_engine = start.elapsed();

    // Direct HNSW (without query engine)
    let start = Instant::now();
    let results_direct = engine.hnsw_index.search(&query_vector, 10).unwrap();
    let time_direct = start.elapsed();

    // Query engine should add <5% overhead
    let overhead = (time_with_engine.as_secs_f64() / time_direct.as_secs_f64()) - 1.0;
    assert!(overhead < 0.05, "Overhead: {:.2}%, expected <5%", overhead * 100.0);

    // Results should be identical
    assert_eq!(results.node_ids, results_direct.node_ids);
}

#[test]
fn test_filter_correctness() {
    // Filtered queries must return correct subset
    let engine = setup_test_engine_with_metadata();

    let query = "SELECT * FROM vectors
                 WHERE similarity(embedding, $query) > 0.8
                 AND category = 'research'
                 AND year >= 2023
                 LIMIT 10";

    let results = engine.execute_query(query).unwrap();

    // Verify each result matches ALL predicates
    for node_id in &results.node_ids {
        let similarity = compute_similarity(&query_vector, engine.get_vector(*node_id));
        assert!(similarity > 0.8, "Node {} similarity: {}, expected >0.8", node_id, similarity);

        let category = engine.get_metadata(*node_id, "category");
        assert_eq!(category, "research", "Node {} category: {}, expected 'research'", node_id, category);

        let year = engine.get_metadata(*node_id, "year").parse::<i32>().unwrap();
        assert!(year >= 2023, "Node {} year: {}, expected >=2023", node_id, year);
    }
}

#[test]
fn test_filter_pushdown_performance() {
    // Pushdown filters should be much faster than post-filtering
    let engine = setup_test_engine_with_metadata();

    // With pushdown (optimized)
    let query_pushdown = "SELECT * FROM vectors
                          WHERE similarity(embedding, $query) > 0.8
                          AND category = 'research'
                          LIMIT 10";

    let start = Instant::now();
    let results_pushdown = engine.execute_query(query_pushdown).unwrap();
    let time_pushdown = start.elapsed();

    // Without pushdown (post-filter, manual implementation)
    let all_results = engine.hnsw_index.search(&query_vector, 10000).unwrap();
    let start = Instant::now();
    let results_post: Vec<_> = all_results.into_iter()
        .filter(|r| r.similarity > 0.8)
        .filter(|r| engine.get_metadata(r.node_id, "category") == "research")
        .take(10)
        .collect();
    let time_post = start.elapsed();

    // Pushdown should be ≥5x faster
    let speedup = time_post.as_secs_f64() / time_pushdown.as_secs_f64();
    assert!(speedup >= 5.0, "Speedup: {:.1}x, expected ≥5x", speedup);

    // Results should be identical
    assert_eq!(results_pushdown.node_ids.len(), results_post.len());
}

#[test]
fn test_hybrid_scoring_correctness() {
    // Hybrid scores should combine neural and symbolic correctly
    let engine = setup_test_engine();
    engine.set_scoring_config(HybridScoringConfig {
        neural_weight: 0.7,
        symbolic_weight: 0.3,
        normalization: NormalizationMethod::MinMax,
    });

    let query = "SELECT * FROM vectors
                 WHERE similarity(embedding, $query) > 0.5
                 AND year >= 2020
                 ORDER BY hybrid_score DESC
                 LIMIT 10";

    let results = engine.execute_query(query).unwrap();

    // Verify hybrid score formula
    for i in 0..results.node_ids.len() {
        let neural = results.neural_scores[i];
        let symbolic = results.symbolic_scores.as_ref().unwrap()[i];

        // Normalize (min-max)
        let neural_norm = (neural - 0.5) / (1.0 - 0.5);  // Assuming min=0.5, max=1.0
        let symbolic_norm = (symbolic - 0.0) / (1.0 - 0.0);  // Assuming min=0.0, max=1.0

        let expected_hybrid = 0.7 * neural_norm + 0.3 * symbolic_norm;
        let actual_hybrid = results.hybrid_scores[i];

        assert!((expected_hybrid - actual_hybrid).abs() < 1e-5,
            "Hybrid score mismatch: expected {}, got {}", expected_hybrid, actual_hybrid);
    }
}

#[test]
fn test_boolean_logic_correctness() {
    // AND/OR/NOT operations must be correct
    let engine = setup_test_engine();

    // Test AND
    let query_and = "SELECT * FROM vectors
                     WHERE category = 'A' AND tag = 'X'";
    let results_and = engine.execute_query(query_and).unwrap();

    for node_id in &results_and.node_ids {
        assert_eq!(engine.get_metadata(*node_id, "category"), "A");
        assert_eq!(engine.get_metadata(*node_id, "tag"), "X");
    }

    // Test OR
    let query_or = "SELECT * FROM vectors
                    WHERE category = 'A' OR category = 'B'";
    let results_or = engine.execute_query(query_or).unwrap();

    for node_id in &results_or.node_ids {
        let category = engine.get_metadata(*node_id, "category");
        assert!(category == "A" || category == "B");
    }

    // Test NOT
    let query_not = "SELECT * FROM vectors
                     WHERE category = 'A' AND NOT tag = 'X'";
    let results_not = engine.execute_query(query_not).unwrap();

    for node_id in &results_not.node_ids {
        assert_eq!(engine.get_metadata(*node_id, "category"), "A");
        assert_ne!(engine.get_metadata(*node_id, "tag"), "X");
    }
}

Backward Compatibility Strategy

1. Opt-In Feature

   • Neuro-symbolic queries are opt-in (require explicit SQL/Cypher syntax)
   • Existing vector search API unchanged

2. Graceful Degradation

   • If metadata indexes not available, fallback to post-filtering
   • Log warning but do not crash

3. Configuration

   query:
     neuro_symbolic:
       enabled: true  # Default: true
       metadata_indexes: true  # Default: true
       hybrid_scoring: true  # Default: true
   

4. API Versioning

   • New endpoints for neuro-symbolic queries (/query/sql, /query/cypher)
   • Existing endpoints (/search) unchanged

Implementation Phases

Phase 1: Core Infrastructure (Week 1-2)

Goal: Query parsing and basic execution

Tasks:

1. Implement SQL/Cypher parser
2. Build AST representation
3. Implement basic query executor (no optimization)
4. Unit tests for parsing and execution

Deliverables:

• neuro_symbolic/parser.rs
• neuro_symbolic/executor.rs
• Passing unit tests

Success Criteria:

• Can parse and execute simple queries (vector similarity only)
• Correct results (matches HNSW baseline)

Phase 2: Metadata Indexing (Week 2-3)

Goal: Support symbolic predicates

Tasks:

1. Implement inverted index for categorical fields
2. Implement B-tree index for range queries
3. Integrate Roaring Bitmap for set operations
4. Test index correctness and performance

Deliverables:

• neuro_symbolic/indexes.rs
• Index creation and query APIs
• Benchmark report

Success Criteria:

• Indexes correctly return matching nodes
• Index queries <10ms for typical workloads
• Memory overhead <20% of vector data

Phase 3: Filter Pushdown (Week 3-4)

Goal: Optimize query execution

Tasks:

1. Implement filter pushdown into HNSW search
2. Modify HNSW to support filter callbacks
3. Benchmark speedup vs post-filtering
4. Test correctness of pushdown logic

Deliverables:

• Modified hnsw.rs with filter support
• neuro_symbolic/optimizer.rs
• Performance benchmarks

Success Criteria:

• ≥5x speedup for filtered queries
• Zero correctness regressions
• Works with complex boolean logic (AND/OR/NOT)

Phase 4: Hybrid Scoring (Week 4-5)

Goal: Combine neural and symbolic scores

Tasks:

1. Implement hybrid scoring algorithm
2. Add score normalization methods
3. Tune weights (α, β) for best results
4. Test on real-world datasets

Deliverables:

• neuro_symbolic/scoring.rs
• Hybrid scoring benchmarks
• Configuration guide

Success Criteria:

• Hybrid queries improve relevance metrics (NDCG, MRR)
• Configurable weights work as expected
• Performance <20ms for typical queries

Phase 5: Production Hardening (Week 5-6)

Goal: Production-ready feature

Tasks:

1. Add comprehensive error handling
2. Write documentation and examples
3. Stress testing (large datasets, complex queries)
4. Integration with existing Cypher support

Deliverables:

• Full error handling
• User documentation
• Example queries
• Regression test suite

Success Criteria:

• Zero crashes in stress tests
• Documentation complete
• Ready for alpha release

Success Metrics

Performance Benchmarks

Primary Metrics (Must Achieve):

Query Type	Baseline (Post-Filter)	Neuro-Symbolic	Target Improvement
Similarity + 1 filter	50ms	5ms	10x faster
Similarity + 3 filters	200ms	8ms	25x faster
Complex boolean (AND/OR/NOT)	N/A (manual)	15ms	New capability
Multi-modal (vector + graph)	500ms (manual joins)	20ms	25x faster

Secondary Metrics:

Metric	Target
Index memory overhead	<20% of vector data
Query parsing time	<1ms
Hybrid scoring overhead	<2ms
Concurrent query throughput	Same as baseline

Accuracy Metrics

Relevance Improvement (on benchmark datasets):

• NDCG@10: +15% (hybrid scoring vs pure vector)
• MRR (Mean Reciprocal Rank): +20%
• Precision@10: +10%

Correctness:

• 100% of filtered results match all predicates
• Zero false positives or false negatives

Memory/Latency Targets

Memory:

• Inverted indexes: <100MB per 1M nodes (categorical fields)
• B-tree indexes: <50MB per 1M nodes (range fields)
• Total overhead: <20% of vector index size

Latency:

• Simple query (1 filter): <10ms
• Complex query (3+ filters): <20ms
• Hybrid scoring: <5ms overhead
• P99 latency: <50ms

Throughput:

• Concurrent queries: Same as baseline HNSW
• No lock contention on indexes

Risks and Mitigations

Technical Risks

Risk 1: Query Parser Complexity

Probability: Medium | Impact: Medium

Description: SQL/Cypher parsing is complex, could have bugs or performance issues.

Mitigation:

• Use established parsing libraries (sqlparser, cypher-parser)
• Extensive test suite with edge cases
• Validate AST before execution
• Provide query validation tool

Contingency: Start with simple query subset, expand incrementally.

---

Risk 2: Index Memory Overhead

Probability: High | Impact: Medium

Description: Metadata indexes could consume excessive memory on large datasets.

Mitigation:

• Use compressed indexes (Roaring Bitmap for sparse sets)
• Make indexing optional (user chooses which fields to index)
• Monitor memory usage in tests
• Provide index size estimation tool

Contingency: Support external indexes (e.g., SQLite) for low-memory environments.

---

Risk 3: Filter Pushdown Bugs

Probability: Medium | Impact: Critical

Description: Incorrect filter logic could return wrong results.

Mitigation:

• Extensive correctness testing (ground truth validation)
• Compare pushdown results vs post-filtering
• Add assertion checks in debug builds
• Fuzzing for edge cases

Contingency: Add "safe mode" that validates results against post-filtering.

---

Risk 4: Hybrid Scoring Tuning Difficulty

Probability: High | Impact: Low

Description: Users may struggle to tune α/β weights for hybrid scoring.

Mitigation:

• Provide automatic weight tuning (based on query logs)
• Document recommended defaults for common use cases
• Add visualization tools for score distributions
• Support A/B testing framework

Contingency: Default to pure neural scoring (α=1, β=0) if user unsure.

---

Risk 5: Cypher Integration Conflicts

Probability: Low | Impact: Medium

Description: Extending Cypher syntax could conflict with existing graph queries.

Mitigation:

• Careful syntax design (use reserved keywords)
• Version Cypher extensions separately
• Extensive compatibility testing
• Document syntax differences

Contingency: Use separate query language (e.g., extended SQL only) if conflicts arise.

---

Summary Risk Matrix

Risk	Probability	Impact	Mitigation Priority
Query parser complexity	Medium	Medium	Medium
Index memory overhead	High	Medium	HIGH
Filter pushdown bugs	Medium	Critical	CRITICAL
Hybrid scoring tuning	High	Low	LOW
Cypher integration conflicts	Low	Medium	Medium

---

Next Steps

1. Prototype Phase 1: Build SQL parser and basic executor (1 week)
2. Validate Queries: Test on simple queries, measure correctness (2 days)
3. Add Metadata Indexes: Implement inverted + B-tree indexes (1 week)
4. Benchmark Performance: Measure speedup vs post-filtering (3 days)
5. Iterate: Optimize based on profiling (ongoing)

Key Decision Points:

• After Phase 1: Is query parsing fast enough? (<1ms target)
• After Phase 3: Does filter pushdown work correctly? (Zero regressions)
• After Phase 4: Does hybrid scoring improve relevance? (+10% NDCG required)

Go/No-Go Criteria:

• ✅ 5x+ speedup on filtered queries
• ✅ Zero correctness regressions
• ✅ Memory overhead <20%
• ✅ Improved relevance metrics