PoC: Property Graph Engine with GQL-inspired Query Language by adityamukho · Pull Request #2 · project-minigraf/minigraf

adityamukho · 2026-01-11T05:24:44Z

Overview

This PR introduces a working proof-of-concept for Minigraf - a tiny, portable GQL (Graph Query Language) engine written in Rust. The implementation demonstrates the core functionality needed for an embedded graph database following the "SQLite for graph databases" philosophy.

What's Included

Core Implementation

Property Graph Model:

✅ Nodes with multiple labels and typed properties
✅ Directed edges with labels and properties
✅ Property types: String, Integer, Float, Boolean, Null
✅ UUID-based identifiers for all entities

Storage Engine:

✅ Thread-safe in-memory storage using Arc<RwLock<HashMap>>
✅ CRUD operations for nodes and edges
✅ Query helpers for filtering and traversals

Query Language:

✅ GQL-inspired syntax parser
✅ CREATE NODE (:Label) {prop: value} - Create nodes with labels/properties
✅ CREATE EDGE (id1)-[LABEL]->(id2) {prop: value} - Create edges
✅ MATCH (:Label) [WHERE prop = value] - Query nodes
✅ MATCH -[:LABEL]-> - Query edges
✅ SHOW NODES / SHOW EDGES - List all entities
✅ HELP / EXIT - Console commands

Interactive REPL:

✅ User-friendly prompt-based console (minigraf>)
✅ Parse and execute queries with immediate feedback
✅ Graceful error handling and EOF detection
✅ Works with piped input and scripts

Testing & Quality

Test Coverage:

✅ 19 unit tests covering types, storage, parser, executor
✅ 1 integration test demonstrating complete workflow
✅ All tests passing
✅ Clean build with no errors

Documentation

Project Philosophy:

✅ PHILOSOPHY.md - "SQLite for graph databases" design principles
✅ 10 core principles (zero-config, embedded-first, single-file, etc.)
✅ Clear boundaries: what Minigraf IS and IS NOT
✅ Design decision framework for future development

Developer Guidance:

✅ CLAUDE.md - Instructions for AI-assisted development
✅ Mandatory philosophy compliance checking
✅ Architecture and implementation details

User Documentation:

✅ README.md - Complete getting started guide
✅ Query language examples
✅ GQL spec compliance tracking (~2-5% currently)
✅ Roadmap to eventual spec compliance

Technical Summary:

✅ POC_SUMMARY.md - Implementation details and test results

Key Design Decisions

In-Memory Storage: Switched from RocksDB to in-memory storage for the PoC to avoid compilation complexity. File-based persistence is planned for Phase 2.
Embedded-First: Library design, not client-server. Runs in-process with the application.
Simplified GQL: Implements a useful subset of ISO/IEC 39075:2024 GQL spec, prioritizing learning and practical use over full compliance.
Thread-Safe: Storage uses Arc/RwLock allowing safe concurrent access.
Zero-Configuration: No setup required - just cargo run and start querying.

Example Usage

$ cargo run
Minigraf v0.1.0 - Interactive Graph Query Console
Type HELP for available commands, EXIT to quit.

minigraf> CREATE NODE (:Person) {name: "Alice", age: 30}
Node created: 986f25e2-... (labels: Person, properties: {age: 30, name: "Alice"})

minigraf> CREATE NODE (:Person) {name: "Bob", age: 25}
Node created: 4699faa4-... (labels: Person, properties: {age: 25, name: "Bob"})

minigraf> MATCH (:Person) WHERE name = "Alice"
Found 1 node(s):
  - 986f25e2-... (labels: Person, properties: {age: 30, name: "Alice"})

minigraf> EXIT
Goodbye!

Module Structure

src/
├── graph/
│   ├── types.rs       # Node, Edge, PropertyValue types
│   └── storage.rs     # Thread-safe in-memory storage
├── query/
│   ├── parser.rs      # Query language parser
│   └── executor.rs    # Query execution engine
├── repl.rs            # Interactive console
├── lib.rs             # Public library API
└── main.rs            # Binary entry point

Commits in This PR

1. a020653 - Implemented GQL property graph PoC with REPL and in-memory storage
2. 41ac8af - Fix REPL infinite loop on EOF and remove unused schema file
3. a3d1d9b - Update CLAUDE.md to reflect current implementation
4. ea40815 - Demo commands for PoC
5. aea2ae3 - Add GQL spec compliance tracking section
6. 451dee4 - Add project philosophy and design principles documentation

Next Steps (Post-Merge)

Phase 2 will focus on:
- Single-file persistent storage (.graph file format)
- ACID transactions with write-ahead logging
- Basic indexes for common query patterns
- More complex graph traversals

Testing Instructions

# Build the project
cargo build

# Run all tests
cargo test

# Run the REPL
cargo run

# Run integration tests with output
cargo test --test integration_test -- --nocapture

All 20 tests pass successfully.

---
🤖 Co-authored with https://claude.com/claude-code

Replaced GraphQL parser with custom GQL (Graph Query Language) implementation featuring: - Property graph model (nodes, edges with labels and typed properties) - Thread-safe in-memory storage using Arc/RwLock - Query parser supporting CREATE, MATCH, and SHOW commands - Query executor with validation - Interactive REPL console - Comprehensive test coverage (20 tests) Architecture changes: - Added graph module (types, storage) - Added query module (parser, executor) - Added repl module for interactive console - Removed server module (logger, error_codes) - Updated dependencies (removed graphql-parser, added serde/anyhow/uuid) - Updated README with usage examples and documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Added EOF detection in REPL to exit gracefully when stdin closes - Previously read_line returning Ok(0) caused infinite loop with piped input - Removed schema.gql.example as it's not needed for in-memory storage Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Replaced outdated references to graphql-parser and src/server/ module - Documented current architecture: graph, query, and repl modules - Added comprehensive query syntax examples - Updated to reflect in-memory storage (not RocksDB) - Documented test coverage (19 unit tests + 1 integration test) - Added notes on EOF handling, thread-safety, and property types - Listed future work items Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Added comprehensive GQL ISO/IEC 39075:2024 compliance status to README - Current implementation: ~2-5% of full spec - Documented implemented features vs. missing features - Categorized missing features: patterns, clauses, expressions, aggregations, etc. - Added 8-phase roadmap to eventual spec compliance - Updated CLAUDE.md to reference compliance status upfront - Sets realistic expectations: this is a learning project, not a compliant implementation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Created PHILOSOPHY.md: - Defines Minigraf as "the SQLite of graph databases" - 10 core principles: zero-config, embedded-first, single-file, self-contained, cross-platform, reliability over features, stability, performance, documentation, long-term support - Clear boundaries: what Minigraf IS and IS NOT - Target use cases (mobile, desktop, WASM, embedded) - Design decision framework for evaluating features - Testing philosophy inspired by SQLite's rigor - Evolution strategy from PoC to maturity - When to say "no" to preserve focus Updated CLAUDE.md: - Added mandatory philosophy compliance checking section - Requires assessment of all features/changes against PHILOSOPHY.md - Defines warning protocol when philosophy violations are detected - Provides template for philosophy violation warnings - Ensures future development adheres to "SQLite for graphs" vision This establishes the long-term vision and decision-making framework for the project, preventing scope creep and maintaining focus on embedded, reliable, local-first graph database. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Why: harrekki P0 project-minigraf#2 — the resident daemon's perception is "what changed since my last tick"; export_fact_log() only offered a full export, so a small tail paid a committed full scan. A2 slice of docs/APP_ADOPTION_GAP_PLAN.md. Includes: CommittedFactReader::for_each_fact_since (default full-scan filter); CommittedFactLoaderImpl override — binary search over packed base pages via the tx-nondecreasing page invariant (last_tx_count probe in packed_pages.rs), falling back to the full filter on any non-packed or empty probe; LayeredFactLoaderImpl override — base probe plus in-memory delta filter; FactStorage::for_each_fact_since pending filter; public Minigraf::export_fact_log_since. Tests: CountingBackend page-read bound, layer-equivalence sweep, tx-nondecreasing invariant lock across base/delta/recompact, SinceOnlyLoader no-full-scan double, last_tx_count probe cases, 3 integration tests (filtered-subsequence equivalence, base/delta/pending spans, stored-cursor reopen poll), and the ignored 1M gate fixture. Verification: cargo test (1155 passed, 12 ignored); cargo test --release --test fact_log_since_benchmark -- --ignored --nocapture (100-record base tail 91µs cold vs 256ms full export at 1M facts); cargo clippy --all-targets error set identical to main (3 pre-existing). Known gaps: page probe falls back to a full-scan filter if a non-packed or zero-record page appears inside the committed fact-page range (no current writer path produces one); delta filter cost is proportional to total delta size, not per-segment skip — acceptable while maintenance bounds delta growth. Confidence: high Scope-risk: narrow Reversibility: clean Tested: cargo test; cargo test --release --test fact_log_since_benchmark -- --ignored --nocapture; cargo clippy --all-targets Rejected: watermark-only base skip | degrades to a committed full scan the tick after any recompact folds the tail into the base

…gelog - BENCHMARKS-FORK.md: fresh 2026-07-14 measurements — rules bands 1.8/10.8-11.1/98ms, 60k grid (two-hop 1.8ms LFTJ, ordered k=1 0.01ms), temporal grid, zone-map file evidence UPGRADED from historical to fresh (as-of 75.1->50.2ms, 50.61% pages skipped; poisoned valid-at 0% as designed), H18 release gate PASSED fresh (139.4s, zero MISMATCH, LFTJ <=1.10x regret on every class), 965k CPG spike re-run fresh (TSV regenerated from the spike parquet: load 2,893ms, warm bound closure 398.8ms, unbound 7,892ms, no truncation). - docs/UPSTREAM-REPORTS.md (new): four filing-ready reports; repros for project-minigraf#1 (u16 saturation: probe 0 rows, scan exactly 65,536/70,000) and project-minigraf#2 (multi-value collapse: 1 row vs 2) RUN AND CONFIRMED against upstream cbf899e; project-minigraf#3 verified-by-inspection (lines confirmed inside migrate_v5_to_v6); project-minigraf#4 red-reproduced on pre-fix code via git-archive. Plus fork-dialect notes (avg, :limit, :order-by, :max-results). - CHANGELOG-FORK.md (new): all 18 commits, one-liners verified against commit bodies. - minigraf-bench/README + design docs: temporal-workload usage note, landed-since annotations. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Co-Authored-By: Codex GPT-5.6 Terra <noreply@openai.com>

adityamukho and others added 6 commits January 11, 2026 09:00

Demo commands for PoC.

ea40815

adityamukho merged commit 903ce1f into main Jan 11, 2026
1 check passed

Navigation Menu

Repository navigation

PoC: Property Graph Engine with GQL-inspired Query Language - #2

PoC: Property Graph Engine with GQL-inspired Query Language#2
adityamukho merged 6 commits into
mainfrom
devel

adityamukho commented Jan 11, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

adityamukho commented Jan 11, 2026

Overview

What's Included

Core Implementation

Testing & Quality

Documentation

Key Design Decisions

Example Usage

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant