Feat/performance benchmarks

nexum_core/Cargo.toml

@@ -23,6 +23,11 @@ log = "0.4"
 [dev-dependencies]
 tempfile = "3.24"
 criterion = { version = "0.5", features = ["html_reports"] }
+rusqlite = "0.31.0" # To interface with SQLite for comparison
+
+[[bench]]
+name = "db_comparison"
+harness = false
 
 [[bench]]
 name = "storage_bench"

nexum_core/benches/README.md

@@ -3,8 +3,51 @@
 This directory contains comprehensive performance benchmarks for the `nexum_core` module using the [Criterion](https://github.com/bheisler/criterion.rs) benchmarking framework.
 
 ## Benchmark Categories
+## Performance & Benchmarks (Feb 2026)
+To maintain the high performance expected of a Rust-based engine, NexumDB is continuously benchmarked against SQLite using the `criterion` suite.
 
-### 1. Storage Engine Benchmarks (`storage_bench.rs`)
+### Comparative Performance Results
+| Operation | SQLite | NexumDB | Delta |
+| :--- | :--- | :--- | :--- |
+| **Single INSERT** | 15.18 ms | **7.48 ms** | NexumDB ~2x Faster |
+| **Point SELECT (Cold)** | **140.5 µs** | 1.86 ms | SQLite Faster |
+| **Point SELECT (Cached)**| **143.8 µs** | 1.87 ms | SQLite Faster |
+
+### Analysis
+![Benchmark Visualization](./nexum_core/benches/bench_results.png)
+
+### Architectural Insights
+
+#### 1. Write Throughput: The LSM-Tree Advantage
+NexumDB’s storage engine (`sled`) utilizes a **Log-Structured Merge-tree (LSM-tree)**, whereas SQLite uses a traditional **B-tree**. 
+* **LSM-tree (NexumDB):** Optimizes for writes by batching updates into immutable segments, leading to the 2x speedup observed in our `INSERT` benchmarks.
+* **B-tree (SQLite):** Optimized for reads. Every write requires finding a leaf node on disk, which involves more synchronous I/O.
+
+
+
+#### 2. Read Latency & AI Overhead
+In small-scale point lookups (1,000 rows), SQLite's raw C-speed is superior. NexumDB's current ~1.8ms latency includes:
+* **SQL Parsing**: Converting strings to `Statement` enums.
+* **PyO3 Bridge**: The overhead of crossing the Rust-Python boundary for AI-native planning.
+* **Semantic Caching**: The current benchmark dataset is too small to show the "skip-the-disk" benefits of semantic caching, which scale exponentially with query complexity and data volume.
+
+---
+
+## Architecture
+* **Core System**: Rust-based storage engine using `sled`, with SQL parsing and intelligent execution.
+* **AI Engine**: Python-based semantic caching, NL translation, and RL optimization via local models.
+* **Integration**: PyO3 bindings for seamless Rust-Python interoperability.
+
+
+
+## Features
+### v0.4.0 - Core Correctness & Table Management
+* **Projection-Correct SELECT**: Column/alias projection with schema validation.
+* **Schema-Safe Writes**: INSERT/UPDATE validation with best-effort coercion.
+* **Table Management**: SHOW TABLES, DESCRIBE, DROP TABLE (IF EXISTS).
+* **Performance Suite**: Integrated benchmark framework for regression testing.
+
+---
 
 Tests the performance of the underlying storage engine operations:
 

nexum_core/benches/db_comparison.rs

@@ -0,0 +1,94 @@
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use rusqlite::Connection;
+use tempfile::{NamedTempFile, tempdir};
+
+use nexum_core::storage::StorageEngine; 
+use nexum_core::executor::Executor;
+use nexum_core::sql::parser::Parser; 
+
+fn setup_sqlite() -> Connection {
+    let db_file = NamedTempFile::new().unwrap();
+    let conn = Connection::open(db_file.path()).unwrap();
+    conn.execute("CREATE TABLE bench (id INTEGER PRIMARY KEY, val TEXT)", []).unwrap();
+    conn
+}
+
+fn setup_nexum() -> Executor {
+    let db_path = tempdir().unwrap();
+    let storage = StorageEngine::new(db_path.path()).unwrap();
+    let executor = Executor::new(storage);
+
+    let sql = "CREATE TABLE bench (id INTEGER, val TEXT)";
+    // Removed .remove(0) because parse returns a Statement directly
+    let statement = Parser::parse(sql).unwrap(); 
+    executor.execute(statement).unwrap();
+
+    executor
+}
+
+fn bench_inserts(c: &mut Criterion) {
+    let mut group = c.benchmark_group("Insert_Performance");
+
+    group.bench_function("SQLite_Single_Insert", |b| {
+        let conn = setup_sqlite();
+        b.iter(|| {
+            conn.execute("INSERT INTO bench (val) VALUES ('test_data')", []).unwrap();
+        });
+    });
+
+    group.bench_function("NexumDB_Single_Insert", |b| {
+        let executor = setup_nexum();
+        let sql = "INSERT INTO bench (id, val) VALUES (1, 'test_data')";
+        let statement = Parser::parse(sql).unwrap();
+        b.iter(|| {
+            executor.execute(statement.clone()).unwrap();
+        });
+    });
+
+    group.finish();
+}
+
+fn bench_selects(c: &mut Criterion) {
+    let mut group = c.benchmark_group("Select_Performance");
+    let row_count = 1000;
+
+    let sqlite_conn = setup_sqlite();
+    for i in 0..row_count {
+        sqlite_conn.execute("INSERT INTO bench (id, val) VALUES (?1, 'data')", [i]).unwrap();
+    }
+
+    let nexum_executor = setup_nexum();
+    let insert_sql = "INSERT INTO bench (id, val) VALUES (1, 'data')";
+    let insert_stmt = Parser::parse(insert_sql).unwrap();
+    for _ in 0..row_count {
+        nexum_executor.execute(insert_stmt.clone()).unwrap();
+    }
+
+    let select_sql = "SELECT val FROM bench WHERE id = 500";
+    let select_stmt = Parser::parse(select_sql).unwrap();
+
+    group.bench_function("SQLite_Point_Lookup", |b| {
+        b.iter(|| {
+            let mut stmt = sqlite_conn.prepare("SELECT val FROM bench WHERE id = 500").unwrap();
+            let _ = stmt.query_row([], |r| r.get::<_, String>(0)).unwrap();
+        });
+    });
+
+    group.bench_function("NexumDB_Point_Lookup_Cold", |b| {
+        b.iter(|| {
+            black_box(nexum_executor.execute(select_stmt.clone()).unwrap());
+        });
+    });
+
+    group.bench_function("NexumDB_Point_Lookup_Cached", |b| {
+        nexum_executor.execute(select_stmt.clone()).unwrap();
+        b.iter(|| {
+            black_box(nexum_executor.execute(select_stmt.clone()).unwrap());
+        });
+    });
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_inserts, bench_selects);
+criterion_main!(benches);

nexum_core/benches/storage_bench.rs

@@ -1,9 +1,12 @@
 use std::time::Duration;
 
+
 use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
 
 use nexum_core::StorageEngine;
 
+
+
 fn storage_write_throughput(c: &mut Criterion) {
     let mut group = c.benchmark_group("storage_write");
 

nexum_core/benches/visualize.py

@@ -0,0 +1,27 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+# Data from our bench run
+labels = ['INSERT', 'SELECT (Cold)', 'SELECT (Cached)']
+sqlite_times = [15.18, 0.143, 0.143] # converted to ms
+nexum_times = [7.48, 1.86, 1.87]    # in ms
+
+x = np.arange(len(labels))
+width = 0.35
+
+fig, ax = plt.subplots(figsize=(10, 6))
+rects1 = ax.bar(x - width/2, sqlite_times, width, label='SQLite', color='#3498db')
+rects2 = ax.bar(x + width/2, nexum_times, width, label='NexumDB', color='#e74c3c')
+
+ax.set_ylabel('Latency (ms) - Lower is Better')
+ax.set_title('NexumDB vs SQLite Performance Comparison')
+ax.set_xticks(x)
+ax.set_xticklabels(labels)
+ax.legend()
+
+# Log scale helps see the SELECT differences more clearly
+ax.set_yscale('log') 
+
+plt.tight_layout()
+plt.savefig('bench_results.png')
+print("Chart saved as bench_results.png")