sqlitegraph/
lib.rs

1//! SQLite-based graph database with unified backend support.
2//!
3//! sqlitegraph provides a lightweight, deterministic graph database for embedded Rust applications.
4//! It supports both SQLite and Native storage backends through a unified API.
5//!
6//! # Features
7//!
8//! - **Dual Backend Support**: Choose between SQLite (feature-rich) and Native (performance-optimized) backends
9//! - **Entity and Edge Storage**: Rich metadata support with JSON serialization
10//! - **Pattern Matching**: Efficient triple pattern matching with cache-enabled fast-path
11//! - **Traversal Algorithms**: Built-in BFS, k-hop, and shortest path algorithms
12//! - **MVCC Snapshots**: Read isolation with snapshot consistency
13//! - **Bulk Operations**: High-performance batch insertions for large datasets
14//! - **Configuration**: Runtime backend selection with fine-grained options
15//!
16//! # Quick Start
17//!
18//! ```rust,ignore
19//! use sqlitegraph::{open_graph, GraphConfig, BackendKind};
20//!
21//! // Use SQLite backend (default)
22//! let cfg = GraphConfig::sqlite();
23//! let graph = open_graph("my_graph.db", &cfg)?;
24//!
25//! // Or use Native backend
26//! let cfg = GraphConfig::native();
27//! let graph = open_graph("my_graph.db", &cfg)?;
28//!
29//! // Both backends support the same operations
30//! let node_id = graph.insert_node(/* node spec */)?;
31//! let neighbor_ids = graph.neighbors(node_id, /* query */)?;
32//! ```
33//!
34//! # Backend Selection
35//!
36//! ## SQLite Backend (Default)
37//! - ACID transactions with rollback support
38//! - Complex queries beyond basic graph operations
39//! - Standard SQLite file format and tooling
40//! - Mature ecosystem and compatibility
41//!
42//! ## Native Backend
43//! - Optimized for graph operations
44//! - Simplified deployment without SQLite dependencies
45//! - Fast startup with large datasets
46//! - Custom binary format for graph data
47//!
48//! # Public API Organization
49//!
50//! This crate exports a clean, stable public API organized as follows:
51//!
52//! ## Core Types
53//! - [`GraphEntity`] - Graph node/vertex representation
54//! - [`GraphEdge`] - Graph edge/relationship representation
55//! - [`GraphBackend`] - Unified trait for backend implementations
56//! - [`SqliteGraphBackend`] - SQLite backend implementation
57//! - [`NativeGraphBackend`] - Native backend implementation
58//!
59//! ## Configuration
60//! - [`BackendKind`] - Runtime backend selection enum
61//! - [`GraphConfig`] - Unified configuration for both backends
62//! - [`SqliteConfig`] - SQLite-specific options
63//! - [`NativeConfig`] - Native-specific options
64//! - [`open_graph()`] - Unified factory function
65//!
66//! ## Operations
67//! - [`insert_node()`], [`insert_edge()`] - Single entity/edge insertion
68//! - [`bulk_insert_entities()`], [`bulk_insert_edges()` - Batch operations
69//! - [`neighbors()`] - Direct neighbor queries
70//! - [`bfs()`], [`k_hop()`], [`shortest_path()`] - Graph traversal algorithms
71//! - [`pattern_engine`] - Pattern matching and triple storage
72//!
73//! ## Utilities
74//! - [`SqliteGraphError`] - Comprehensive error handling
75//! - [`GraphSnapshot`] - MVCC snapshot system
76//! - [`recovery`] - Database backup and restore utilities
77//! - [`query::GraphQuery`] - High-level query interface
78
79// Core public modules
80pub mod backend;
81pub mod config;
82pub mod errors;
83pub mod graph;
84
85// Re-export core utilities that are stable public APIs
86pub use api_ergonomics::{Label, NodeId, PropertyKey, PropertyValue};
87pub use graph_opt::{
88    GraphEdgeCreate, GraphEntityCreate, bulk_insert_edges, bulk_insert_entities, cache_stats,
89};
90pub use index::{add_label, add_property};
91pub use mvcc::{GraphSnapshot, SnapshotState};
92pub use pattern_engine::{PatternTriple, TripleMatch, match_triples};
93pub use pattern_engine_cache::match_triples_fast;
94pub use query::GraphQuery;
95pub use recovery::{dump_graph_to_path, load_graph_from_path, load_graph_from_reader};
96
97// Re-export backend implementations
98pub use backend::{BackendDirection, ChainStep, GraphBackend};
99pub use backend::{EdgeSpec, NativeGraphBackend, NeighborQuery, NodeSpec, SqliteGraphBackend};
100
101// Re-export configuration and factory
102pub use config::{BackendKind, GraphConfig, NativeConfig, SqliteConfig, open_graph};
103
104// Re-export error types
105pub use errors::SqliteGraphError;
106
107// Re-export graph core types
108pub use graph::{GraphEdge, GraphEntity, SqliteGraph};
109
110// Internal modules - not part of public API
111pub mod algo; // Public for tests
112mod api_ergonomics;
113pub mod backend_selector;
114pub mod bfs; // Public for tests
115pub mod cache; // Public for tests
116mod client; // Public for binary
117mod fault_injection; // Public for tests
118pub mod graph_opt; // Public for tests
119pub mod index; // Public for tests
120pub mod multi_hop; // Public for tests
121mod pattern_engine_cache; // Already moved to core above
122pub mod query_cache; // Public for internal use and tests
123mod reasoning; // Public for binary
124pub mod schema; // Public for tests // Public for tests
125
126// Core public modules (these were accidentally removed)
127pub mod mvcc; // Already exported above
128pub mod pattern_engine; // Already exported above
129pub mod query; // Already exported above
130pub mod recovery; // Already exported above
131
132// Modules that need to remain public for specific use cases
133pub mod bench_gates; // Public for tests
134pub mod bench_meta; // Public for tests
135pub mod bench_regression; // Public for tests
136pub mod bench_utils; // Public for tests
137pub mod dsl; // Public for examples
138pub mod hnsw;
139pub mod pattern; // Public for binary // HNSW vector search capabilities
140
141// Re-export cache statistics for benchmarking
142pub use cache::CacheStats;
sqlitegraph/lib.rs

sqlitegraph/
lib.rs
