SQLite Graph Database Extension
A powerful SQLite extension that adds graph database capabilities with full Cypher query support. Part of the AgentFlare AI ecosystem. Build sophisticated graph applications with the reliability of SQLite and the expressiveness of Cypher.
⚠️ ALPHA RELEASE: This is an alpha release (v0.1.0-alpha.0) intended for testing and feedback. The API may change in future releases. Not recommended for production use.
Features (Alpha v0.1.0)
✅ Working Features
Core Graph Operations : Create, read, update, delete nodes and edges via SQL functions
: Create, read, update, delete nodes and edges via SQL functions Cypher Query Execution (NEW!): Full basic Cypher support working end-to-end CREATE (n) - Create anonymous nodes ✅ CREATE (p:Person {name: "Alice"}) - Create nodes with labels and properties ✅ CREATE (a)-[:TYPE]->(b) - Create relationships ✅ CREATE (a)-[:TYPE {props}]->(b) - Create relationships with properties ✅ MATCH (n) RETURN n - Basic pattern matching ✅ MATCH (n:Label) RETURN n - Label-based matching ✅ MATCH (a)-[r:TYPE]->(b) RETURN a, r, b - Relationship matching ✅ MATCH (n) WHERE n.prop > value RETURN n - Property filtering ✅ WHERE clause with all comparison operators: =, >, <, >=, <=, <> ✅ Full execution pipeline: parser → logical planner → physical planner → executor ✅ 70/70 CREATE TCK tests passing (100% openCypher compliance for CREATE)
(NEW!): Full basic Cypher support working end-to-end Graph Virtual Tables : SQLite virtual table integration for graph data
: SQLite virtual table integration for graph data Basic Graph Algorithms : Connectivity checks, density calculations, degree centrality
: Connectivity checks, density calculations, degree centrality SQL API : graph_node_add() , graph_edge_add() , graph_count_nodes() , graph_count_edges()
: , , , Performance : 300K+ nodes/sec, 390K+ edges/sec
: 300K+ nodes/sec, 390K+ edges/sec Python Bindings : Full Python 3.6+ support with examples
: Full Python 3.6+ support with examples Thread Safety : Fixed critical thread-safety issues for production use
: Fixed critical thread-safety issues for production use Security: Buffer overflow protections, SQL injection prevention
🚧 In Progress
Advanced Cypher Features : Bidirectional/reverse relationship matching ( <-[r]- , -[r]- ) Variable-length paths ( [r*1..3] ) Complex expressions in WHERE (AND, OR, NOT) Property expressions in RETURN (n.property) Aggregations (COUNT, SUM, etc.) ORDER BY, SKIP, LIMIT
: Graph Algorithms : Shortest path, PageRank (implementation incomplete)
: Shortest path, PageRank (implementation incomplete) Property Indexing: Basic support, optimization ongoing
📋 Roadmap (Not Yet Implemented)
Full openCypher Compliance : 100% TCK test suite passing
: 100% TCK test suite passing Advanced Write Operations : MERGE, SET, DELETE with complex patterns
: MERGE, SET, DELETE with complex patterns Advanced Pattern Matching : Multi-hop paths, variable-length patterns
: Multi-hop paths, variable-length patterns Advanced Algorithms : Betweenness centrality, community detection
: Betweenness centrality, community detection Query Optimization : Cost-based query planner with statistics
: Cost-based query planner with statistics Distributed Queries: Multi-database graph queries
See ROADMAP.md for detailed feature timeline.
Quick Start
Installation
Option 1: Download Pre-built Binary (Linux x86_64)
# Download from releases page wget https://github.com/agentflare-ai/sqlite-graph/releases/latest/download/libgraph.so # Verify checksum (recommended) wget https://github.com/agentflare-ai/sqlite-graph/releases/latest/download/checksums.txt sha256sum -c checksums.txt # Ready to use!
Option 2: Build from Source
# Clone the repository git clone https://github.com/agentflare-ai/sqlite-graph.git cd sqlite-graph # Build the extension make # The extension will be built as build/libgraph.so
See the Installation Guide for detailed instructions and platform-specific guidance.
Basic Usage (Alpha v0.1.0)
import sqlite3 import json # Load the extension conn = sqlite3 . connect ( ":memory:" ) conn . enable_load_extension ( True ) conn . load_extension ( "./build/libgraph.so" ) # Create a graph virtual table conn . execute ( "CREATE VIRTUAL TABLE graph USING graph()" ) # Option 1: Use Cypher queries (NEW!) # Create nodes with properties conn . execute ( "SELECT cypher_execute('CREATE (p:Person {name: \" Alice \" , age: 30})')" ) conn . execute ( "SELECT cypher_execute('CREATE (c:Company {name: \" Acme Inc \" })')" ) # Create relationships with properties conn . execute ( "SELECT cypher_execute('CREATE (a:Person {name: \" Bob \" })-[:KNOWS {since: 2020}]->(b:Person {name: \" Charlie \" })')" ) # Query with MATCH...RETURN cursor = conn . execute ( "SELECT cypher_execute('MATCH (n:Person) RETURN n')" ) results = json . loads ( cursor . fetchone ()[ 0 ]) print ( results ) # [{"n": Node(1)}, {"n": Node(2)}, ...] # Query relationships cursor = conn . execute ( "SELECT cypher_execute('MATCH (a)-[r:KNOWS]->(b) RETURN a, r, b')" ) results = json . loads ( cursor . fetchone ()[ 0 ]) print ( results ) # Returns matching relationships with nodes # Filter with WHERE clause cursor = conn . execute ( "SELECT cypher_execute('MATCH (p:Person) WHERE p.age > 25 RETURN p')" ) results = json . loads ( cursor . fetchone ()[ 0 ]) print ( results ) # Returns nodes where age > 25 # Option 2: Add nodes using SQL functions conn . execute ( "SELECT graph_node_add(1, ?) as id" , ( json . dumps ({ "name" : "Alice" , "age" : 30 }),)) conn . execute ( "SELECT graph_node_add(2, ?) as id" , ( json . dumps ({ "name" : "Bob" , "age" : 25 }),)) # Add edges conn . execute ( "SELECT graph_edge_add(1, 2, 'KNOWS', ?) as id" , ( json . dumps ({ "since" : "2020" }),)) # Query the graph node_count = conn . execute ( "SELECT graph_count_nodes()" ). fetchone ()[ 0 ] edge_count = conn . execute ( "SELECT graph_count_edges()" ). fetchone ()[ 0 ] print ( f"Nodes: { node_count } , Edges: { edge_count } " ) # Nodes: 4, Edges: 1 # Check graph properties is_connected = conn . execute ( "SELECT graph_is_connected()" ). fetchone ()[ 0 ] density = conn . execute ( "SELECT graph_density()" ). fetchone ()[ 0 ] centrality = conn . execute ( "SELECT graph_degree_centrality(1)" ). fetchone ()[ 0 ] print ( f"Connected: { bool ( is_connected ) } , Density: { density :.3f } , Alice centrality: { centrality :.3f } " ) # Verify Cypher-created nodes cypher_nodes = conn . execute ( "SELECT id, labels FROM graph_nodes WHERE labels != ''" ). fetchall () print ( f"Cypher nodes: { cypher_nodes } " ) # [(node_id, 'Person'), (node_id, 'Company')]
Working Examples
See the examples/ directory for fully functional demonstrations:
simple_graph_example.py - Complete working example with nodes, edges, and algorithms
- Complete working example with nodes, edges, and algorithms python_examples.py - 6 comprehensive examples showcasing all working features
- 6 comprehensive examples showcasing all working features cypher_demo.py - NEW! Cypher CREATE query examples
Note: Basic Cypher queries fully work! CREATE, MATCH, WHERE, and RETURN operations are functional, including relationship creation and matching. You can now build complete graph applications using only Cypher. Advanced features like bidirectional matching, variable-length paths, and aggregations are in development for v0.2.0. The alpha version also provides SQL function-based graph operations for advanced use cases.
Documentation
Essential Reading
FEATURES.md - ⭐ Start here! Complete feature status and API reference
- ⭐ Complete feature status and API reference ROADMAP.md - Development timeline and planned features
- Development timeline and planned features Installation Guide - Detailed build and installation instructions
Examples - Working code examples (simple_graph_example.py, python_examples.py)
Project Status (Alpha v0.1.0)
✅ What Works: Node/edge creation, full Cypher CREATE/MATCH/WHERE/RETURN, relationships with properties, basic algorithms, Python bindings 🚧 In Progress: Advanced MATCH features (bidirectional, variable-length paths), property projection in RETURN, aggregations 📋 Planned: Full Cypher compliance (Q1 2026), advanced algorithms (Q2 2026), query optimization
Architecture (Alpha Implementation)
The extension currently consists of:
✅ Virtual Table Interface : SQLite virtual table implementation for graph operations
: SQLite virtual table implementation for graph operations ✅ Storage Engine : Efficient node/edge storage with JSON properties
: Efficient node/edge storage with JSON properties ✅ Algorithm Library : Basic graph algorithms (connectivity, density, centrality)
: Basic graph algorithms (connectivity, density, centrality) ✅ Cypher Execution Engine : Parser → Planner → Iterator-based Executor ✅ Lexer and Parser (AST generation) ✅ Logical Plan generation ✅ Physical Plan optimization ✅ Volcano-model iterators ✅ Result serialization
: Parser → Planner → Iterator-based Executor ✅ Cypher Operators : CREATE, MATCH (with relationships), WHERE, RETURN all working ✅ AllNodesScan, LabelIndexScan iterators ✅ Expand iterator (relationship traversal) ✅ Filter iterator (WHERE clause) ✅ Create iterator (nodes and relationships)
: CREATE, MATCH (with relationships), WHERE, RETURN all working 📋 Query Optimizer: Cost-based optimization planned for v0.2.0
Performance (Alpha Benchmarks)
Node Creation : 300,000+ nodes/second (tested up to 1,000 nodes)
: 300,000+ nodes/second (tested up to 1,000 nodes) Edge Creation : 390,000+ edges/second (tested up to 999 edges)
: 390,000+ edges/second (tested up to 999 edges) Connectivity Check : <1ms for 1,000 node graphs
: <1ms for 1,000 node graphs Scalability : Currently tested up to 1,000 nodes/edges
: Currently tested up to 1,000 nodes/edges Memory: In-memory storage, persistence via SQLite database file
More Examples
Social Network Analysis (Working Alpha Code)
import json # Create person nodes alice_id = 1 bob_id = 2 carol_id = 3 conn . execute ( "SELECT graph_node_add(?, ?)" , ( alice_id , json . dumps ({ "name" : "Alice" , "city" : "NYC" }))) conn . execute ( "SELECT graph_node_add(?, ?)" , ( bob_id , json . dumps ({ "name" : "Bob" , "city" : "LA" }))) conn . execute ( "SELECT graph_node_add(?, ?)" , ( carol_id , json . dumps ({ "name" : "Carol" , "city" : "NYC" }))) # Add friendships conn . execute ( "SELECT graph_edge_add(?, ?, 'FRIENDS', ?)" , ( alice_id , bob_id , json . dumps ({}))) conn . execute ( "SELECT graph_edge_add(?, ?, 'FRIENDS', ?)" , ( alice_id , carol_id , json . dumps ({}))) # Query the graph with SQL mutual_friends = conn . execute ( """ SELECT DISTINCT n.id, n.properties FROM graph_nodes n JOIN graph_edges e1 ON e1.target = n.id JOIN graph_edges e2 ON e2.target = n.id WHERE e1.source = ? AND e2.source = ? AND e1.edge_type = 'FRIENDS' AND e2.edge_type = 'FRIENDS' """ , ( alice_id , bob_id )). fetchall () # Check connectivity is_connected = conn . execute ( "SELECT graph_is_connected()" ). fetchone ()[ 0 ] print ( f"Network is connected: { bool ( is_connected ) } " )
More Working Examples
See the examples/ directory for complete, tested code:
simple_graph_example.py - Basic operations walkthrough
- Basic operations walkthrough python_examples.py - 6 comprehensive examples with output
Testing
# Build the extension make # Run Python examples (all tests should pass) cd examples python3 simple_graph_example.py python3 python_examples.py # Expected output: All examples pass with ✅ indicators
License
This project is licensed under the MIT License - see the LICENSE file for details.
Contributing
We welcome contributions! Please check:
FEATURES.md - See what's implemented and what's not
ROADMAP.md - See planned features and timeline
GitHub Issues - Report bugs or request features
Support
Bug Reports : GitHub Issues
: GitHub Issues Feature Requests : Check ROADMAP.md first, then open an issue with [Feature Request] tag
: Check ROADMAP.md first, then open an issue with tag Questions: See FEATURES.md for detailed API documentation
Development Roadmap
Alpha v0.1.0 (Current): Core graph operations, basic algorithms v0.2.0 (Q1 2026): Full Cypher query execution v0.3.0 (Q2 2026): Advanced graph algorithms v0.4.0 (Q3 2026): Performance optimization & scale v1.0.0 (2027): Production ready with full openCypher compliance
See ROADMAP.md for detailed feature timeline.
Part of the AgentFlare AI ecosystem • Built with SQLite Alpha Release: v0.1.0-alpha.0 • Not for production use