HyperQL - Unified Query Language for Hyperspatial Database

HyperQL is a revolutionary query language that unifies SQL-like syntax with graph traversal, geometric queries, and cascade operations. It enables seamless querying across multiple paradigms within the Hyperspatial database's unified hyperbolic space.

🌟 Why HyperQL?

Traditional databases force developers to use different query languages for different data models:

• SQL for relational data
• Cypher or SPARQL for graph traversals
• Custom APIs for vector similarity
• Domain-specific languages for time-series analysis

HyperQL eliminates this fragmentation by providing a unified syntax that can:

• Query entities by properties (SQL-like WHERE clauses)
• Traverse relationships (graph-style navigation)
• Find similar entities (vector similarity searches)
• Apply geometric filters (hyperbolic distance constraints)
• Propagate cascading measures (hierarchical computations)
• Combine all paradigms in a single query

🚀 Key Features

Multi-Paradigm Integration

HyperQL seamlessly combines multiple query paradigms:

SELECT entity, measure_value, influence_score
FROM users u
TRAVERSE connected_to -> friends f
       -> colleagues c
WHERE u.age > 25
  AND similarity(u.interests, f.interests) > 0.8
  AND hyperbolic_distance(u, f) < 2.0
  AND c.department = 'engineering'
CASCADE user_influence FROM u TO f WITH decay_factor(0.9)
ORDER BY measure_value DESC, influence_score DESC
LIMIT 100

Spatial Intelligence

Leverage the hyperbolic positioning system for:

• Natural clustering queries without explicit grouping
• Hierarchical traversals that respect learned structure
• Multi-signal similarity searches combining various signals
• Temporal queries over position trajectories

Advanced Cascade System

Powerful cascade operations for hierarchical computations:

-- Aggregate sales up organizational hierarchy
CASCADE total_sales = SUM(sales_amount)
FROM transactions t
PROPAGATE UP THROUGH organizational_hierarchy

-- Distribute budget down to teams
CASCADE budget_allocation = DISTRIBUTE(total_budget, allocation_weights)
FROM departments d
PROPAGATE DOWN TO teams

-- Compute influence propagation through social networks
CASCADE influence_score = INFLUENCE(base_score, decay_factor: 0.9)
FROM influencers i
PROPAGATE THROUGH social_network
WITH MAX_DEPTH 3

📖 Query Examples

Basic Relational Queries

-- Traditional SQL-style query
SELECT name, age, email
FROM users
WHERE age > 30 AND department = 'engineering'
ORDER BY name

Graph Traversal Queries

-- Find friends of friends with similar interests
SELECT u.name, f.name, ff.name
FROM users u
TRAVERSE friends -> f
       -> friends -> ff
WHERE similarity(u.interests, ff.interests) > 0.7
  AND u.id != ff.id

Geometric Queries

-- Find entities within hyperbolic distance
SELECT entity, hyperbolic_distance(entity, @anchor) as distance
FROM products
WHERE hyperbolic_distance(entity, @anchor) < 1.5
ORDER BY distance ASC

Vector Similarity Queries

-- K-nearest neighbors with filtering
SELECT item, similarity(item.embedding, @query_vector) as score
FROM items
WHERE category = 'electronics' 
  AND price < 500
ORDER BY similarity(item.embedding, @query_vector) DESC
LIMIT 10

Complex Multi-Paradigm Queries

-- Recommendation system combining multiple signals
SELECT 
    p.title,
    similarity(p.content_embedding, u.preference_vector) as content_score,
    hyperbolic_distance(p, u) as position_score,
    cascade_measure as social_score
FROM products p, users u
TRAVERSE u.friends -> f
WHERE u.id = @user_id
  AND p.category IN @preferred_categories
  AND similarity(p.content_embedding, u.preference_vector) > 0.6
CASCADE social_influence 
  FROM f.purchased_items 
  TO p 
  WITH influence_weight(f.social_score)
ORDER BY 
  (0.4 * content_score + 0.3 * position_score + 0.3 * social_score) DESC
LIMIT 20

Temporal Trajectory Queries

-- Analyze movement patterns over time
SELECT 
    entity,
    trajectory_similarity(entity.position_history, @pattern) as match_score
FROM moving_objects
WHERE timerange(entity.timestamps, '2024-01-01', '2024-12-31')
  AND trajectory_length(entity.position_history) > 100
ORDER BY match_score DESC

🔧 Usage Modes

1. Ad-Hoc Queries

Direct query execution for interactive analysis:

use hyperql::*;

#[tokio::main]
async fn main() -> Result<()> {
    let engine = HyperQLEngine::new().await?;
    
    let query = r#"
        SELECT name, age
        FROM users 
        WHERE age > 25
        TRAVERSE friends -> f
        WHERE similarity(interests, f.interests) > 0.8
    "#;
    
    let results = engine.execute(query).await?;
    for row in results {
        println!("{:?}", row);
    }
    
    Ok(())
}

2. Compiled Queries

Pre-compiled queries for production performance:

use hyperql::*;

#[tokio::main]
async fn main() -> Result<()> {
    let engine = HyperQLEngine::new().await?;
    
    // Compile query once
    let compiled = engine.compile(r#"
        SELECT entity, measure_value
        FROM users u
        TRAVERSE connected_to -> friends f
        WHERE u.age > $age_threshold
          AND similarity(u.interests, f.interests) > $similarity_threshold
        CASCADE user_influence FROM u TO f
        ORDER BY measure_value DESC
        LIMIT $limit
    "#).await?;
    
    // Execute multiple times with different parameters
    let results1 = compiled.execute(
        &[("age_threshold", 25), ("similarity_threshold", 0.8), ("limit", 50)]
    ).await?;
    
    let results2 = compiled.execute(
        &[("age_threshold", 30), ("similarity_threshold", 0.9), ("limit", 20)]
    ).await?;
    
    Ok(())
}

3. Hybrid Mode

Combine compiled templates with dynamic query construction:

use hyperql::*;

#[tokio::main]
async fn main() -> Result<()> {
    let engine = HyperQLEngine::new().await?;
    
    // Build query dynamically
    let mut query_builder = QueryBuilder::new()
        .select(["entity", "score"])
        .from("products")
        .where_clause("category = $category")
        .order_by("score DESC")
        .limit(10);
    
    // Add conditional traversal
    if include_recommendations {
        query_builder = query_builder
            .traverse("recommended_by -> users u")
            .where_and("u.trust_score > $trust_threshold");
    }
    
    let compiled = query_builder.compile(&engine).await?;
    let results = compiled.execute(
        &[("category", "electronics"), ("trust_threshold", 0.7)]
    ).await?;
    
    Ok(())
}

🏗️ Architecture

HyperQL follows a traditional compiler pipeline optimized for hyperbolic queries:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Query     │───▶│    AST      │───▶│ Execution   │───▶│   Results   │
│   Text      │    │             │    │   Plan      │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                   │                   │                   │
   ┌─────────┐         ┌─────────┐         ┌─────────┐         ┌─────────┐
   │ Parser  │         │Compiler │         │Executor │         │Hyperbolic│
   │ (Winnow)│         │         │         │ Engine  │         │  Space   │
   └─────────┘         └─────────┘         └─────────┘         └─────────┘

Core Components

• Parser: Winnow-based parser converts query text to AST
• Compiler: AST transforms into optimized execution plans
• Optimizer: Query plans are optimized for hyperbolic operations
• Executor: Plans execute against the hyperbolic space engine
• Runtime: Lua and WASM integration for custom functions

📁 Module Structure

src/
├── ast/                 # Abstract syntax tree definitions
│   ├── mod.rs
│   ├── query.rs        # Core query structures
│   ├── expression.rs   # Expression trees
│   ├── literal.rs      # Literal values
│   ├── identifier.rs   # Entity identifiers
│   ├── function.rs     # Function calls
│   ├── predicate.rs    # Boolean expressions
│   ├── traverse.rs     # Graph traversal
│   ├── cascade.rs      # Cascade operations
│   └── aggregate.rs    # Aggregation functions
├── parser/             # Winnow-based query parser
│   ├── mod.rs
│   ├── lexer.rs        # Tokenization
│   ├── grammar.rs      # Grammar rules
│   └── combinators.rs  # Parser combinators
├── compiler/           # AST to execution plan compilation
│   ├── mod.rs
│   ├── planner.rs      # Query planning
│   ├── type_checker.rs # Type analysis
│   └── code_gen.rs     # Code generation
├── executor/           # Query execution engine
│   ├── mod.rs
│   ├── engine.rs       # Execution engine
│   ├── operators.rs    # Query operators
│   └── results.rs      # Result handling
├── functions/          # Built-in function library
│   ├── mod.rs
│   ├── similarity.rs   # Vector similarity functions
│   ├── geometric.rs    # Hyperbolic geometry functions
│   ├── aggregates.rs   # Aggregation functions
│   └── temporal.rs     # Time-based functions
├── cascade/            # Cascade system for measure propagation
│   ├── mod.rs
│   ├── propagation.rs  # Propagation algorithms
│   ├── measures.rs     # Measure definitions
│   ├── hierarchy.rs    # Hierarchy detection
│   └── scheduler.rs    # Cascade scheduling
├── optimizer/          # Query optimization
│   ├── mod.rs
│   ├── rules.rs        # Optimization rules
│   ├── cost_model.rs   # Cost modeling
│   └── statistics.rs   # Query statistics
├── context/            # Query execution context
│   ├── mod.rs
│   ├── variables.rs    # Variable binding
│   └── scope.rs        # Scope management
├── runtime/            # Custom function runtime
│   ├── mod.rs
│   ├── lua.rs          # Lua integration
│   ├── wasm.rs         # WASM integration
│   ├── sandbox.rs      # Security sandbox
│   └── function_registry.rs # Function registry
├── ir/                 # Intermediate representation
│   ├── mod.rs
│   ├── operators.rs    # IR operators
│   ├── plans.rs        # Execution plans
│   └── serialization.rs # Plan serialization
├── error.rs            # Error types and handling
├── types.rs            # Core type definitions
└── lib.rs             # Library root with documentation

🔌 Integration with Hyperspatial

HyperQL is tightly integrated with the Hyperspatial database engine:

Hyperbolic Engine Integration

• Learned Positions: Leverages hyperbolic positions for geometric queries
• Distance Calculations: Efficient hyperbolic distance computations
• Spatial Indexing: Utilizes hyperbolic spatial indices for fast retrieval
• Clustering: Natural clustering based on hyperbolic proximity

Persistence Layer Integration

• Entity Access: Direct access to stored entities and properties
• Relationship Traversal: Efficient traversal of stored relationships
• Index Utilization: Leverages existing indices for query acceleration
• Transaction Support: Full ACID transaction support

Vector Operations Integration

• Embedding Storage: Access to stored vector embeddings
• Similarity Indices: Utilizes vector similarity indices (HNSW, IVF)
• Approximate Search: Efficient approximate nearest neighbor search
• Multi-Modal Vectors: Support for multiple embedding types per entity

Measure System Integration

• Cascade Computation: Integration with measure propagation system
• Incremental Updates: Efficient updates when underlying data changes
• Dependency Management: Automatic cascade dependency resolution
• Parallel Execution: Multi-threaded cascade computation

🎯 Custom Functions with Lua and WASM

Lua Integration

Extend HyperQL with custom Lua functions:

use hyperql::runtime::lua::LuaRuntime;

#[tokio::main]
async fn main() -> Result<()> {
    let mut runtime = LuaRuntime::new().await?;
    
    // Register custom Lua function
    runtime.register_function("custom_similarity", r#"
        function custom_similarity(vec1, vec2, weights)
            local sum = 0
            for i = 1, #vec1 do
                sum = sum + (vec1[i] * vec2[i] * weights[i])
            end
            return sum / (#vec1 * #vec2)
        end
    "#).await?;
    
    let engine = HyperQLEngine::with_runtime(runtime).await?;
    
    // Use custom function in queries
    let results = engine.execute(r#"
        SELECT entity, custom_similarity(entity.embedding, @query_vector, @weights) as score
        FROM products
        WHERE custom_similarity(entity.embedding, @query_vector, @weights) > 0.8
        ORDER BY score DESC
    "#).await?;
    
    Ok(())
}

WASM Integration

Deploy compiled functions for maximum performance:

use hyperql::runtime::wasm::WasmRuntime;

#[tokio::main]
async fn main() -> Result<()> {
    let mut runtime = WasmRuntime::new().await?;
    
    // Load compiled WASM module
    let wasm_bytes = std::fs::read("custom_functions.wasm")?;
    runtime.load_module("custom", &wasm_bytes).await?;
    
    let engine = HyperQLEngine::with_runtime(runtime).await?;
    
    // Use WASM functions in queries
    let results = engine.execute(r#"
        SELECT entity, custom.fast_similarity(entity.embedding, @query) as score
        FROM large_dataset
        WHERE custom.fast_similarity(entity.embedding, @query) > 0.9
    "#).await?;
    
    Ok(())
}

🚀 Installation

Add HyperQL to your Cargo.toml:

[dependencies]
hyperQL = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

📚 Getting Started

Basic Setup

use hyperql::*;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize the HyperQL engine
    let engine = HyperQLEngine::new().await?;
    
    // Execute a simple query
    let results = engine.execute(r#"
        SELECT name, age
        FROM users
        WHERE age > 25
        ORDER BY name
    "#).await?;
    
    // Process results
    for row in results {
        let name: String = row.get("name")?;
        let age: i32 = row.get("age")?;
        println!("{}: {} years old", name, age);
    }
    
    Ok(())
}

Advanced Configuration

use hyperql::*;
use hyperql::config::*;

#[tokio::main]
async fn main() -> Result<()> {
    let config = EngineConfig::builder()
        .max_parallel_queries(100)
        .enable_query_cache(true)
        .cascade_thread_pool_size(16)
        .lua_sandbox_enabled(true)
        .wasm_memory_limit(1_000_000)
        .build();
    
    let engine = HyperQLEngine::with_config(config).await?;
    
    // Engine is now ready with custom configuration
    Ok(())
}

🔬 Performance Characteristics

Query Complexity

• Simple Filters: O(n) with index acceleration
• Graph Traversals: O(d^k) where d=degree, k=depth
• Similarity Searches: O(log n) with proper indexing
• Cascade Operations: O(h * n) where h=hierarchy height
• Complex Multi-Paradigm: Optimized based on selectivity

Scalability

• Horizontal Scaling: Query parallelization across cores
• Memory Efficiency: Streaming results for large datasets
• Index Utilization: Automatic index selection and usage
• Caching: Query result and plan caching

Benchmarks

🛣️ Roadmap

Version 0.2.0 (Q2 2025)

• Advanced optimization rules
• Distributed query execution
• Streaming query results
• Enhanced WASM runtime

Version 0.3.0 (Q3 2025)

• Machine learning function library
• Temporal query extensions
• Advanced cascade algorithms
• Query debugging tools

Version 1.0.0 (Q4 2025)

• Production stability
• Complete SQL compatibility layer
• Visual query builder
• Enterprise features

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/hyperspatial/hyperQL.git
cd hyperQL

# Install dependencies
cargo build

# Run tests
cargo test

# Run examples
cargo run --example basic_query

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• The Rust community for excellent async ecosystem
• The Winnow parser combinator library
• The hyperbolic geometry research community
• Contributors to vector similarity algorithms

HyperQL - Revolutionizing database queries through unified multi-paradigm syntax and hyperbolic intelligence.

For more information, visit our documentation or join our community discussions.