Crate oxirs_core

Expand description

§OxiRS Core - RDF and SPARQL Foundation

Status: Production Release (v0.1.0) Stability: Public APIs are stabilizing. Production-ready for RDF/SPARQL core operations.

§Overview

oxirs-core is a high-performance, zero-dependency Rust-native RDF data model and SPARQL foundation for the OxiRS semantic web platform. It provides the fundamental types, traits, and operations that all other OxiRS crates build upon.

This crate is designed for:

Building semantic web applications in Rust
Processing large-scale knowledge graphs with minimal memory overhead
Developing SPARQL query engines and triple stores
Creating RDF-based data pipelines and transformations

§Key Features

§Core RDF Support

RDF 1.2 Compliance - Full implementation of the RDF 1.2 data model
Multiple Serialization Formats - Support for Turtle, N-Triples, TriG, N-Quads, RDF/XML, JSON-LD
Named Graphs - Full quad support with named graph management
RDF-star - Support for quoted triples (statement reification)

§Performance & Scalability

Memory Efficiency - Arena-based allocators and optimized data structures
Concurrent Operations - Lock-free data structures for high-throughput workloads
Parallel Processing - SIMD and multi-threaded query execution
Zero-Copy Parsing - Streaming parsers with minimal allocations

§SPARQL Foundation

SPARQL 1.1 Query - SELECT, CONSTRUCT, ASK, DESCRIBE queries
SPARQL 1.1 Update - INSERT, DELETE, LOAD, CLEAR operations
SPARQL 1.2 Features - Enhanced property paths, aggregations, and functions
Federation - SERVICE clause support for distributed queries

§Storage & Persistence

Pluggable Backends - In-memory and disk-based storage options
Persistent Storage - Automatic N-Quads serialization for durability
Indexed Access - Multi-index support (SPO, POS, OSP) for fast pattern matching
Transaction Support - ACID-compliant transactions for data integrity

§Production Features

Monitoring & Metrics - Built-in performance instrumentation via SciRS2
Error Handling - Rich error types with context and suggestions
Health Checks - Circuit breakers and resource quotas
Benchmarking - Comprehensive benchmark suite for performance validation

§Quick Start

§Creating a Store and Adding Data

use oxirs_core::RdfStore;
use oxirs_core::model::{NamedNode, Triple, Literal};

// Create an in-memory RDF store
let mut store = RdfStore::new()?;

// Create RDF terms
let alice = NamedNode::new("http://example.org/alice")?;
let knows = NamedNode::new("http://xmlns.com/foaf/0.1/knows")?;
let bob = NamedNode::new("http://example.org/bob")?;
let name = NamedNode::new("http://xmlns.com/foaf/0.1/name")?;

// Insert triples
store.insert_triple(Triple::new(alice.clone(), knows, bob))?;
store.insert_triple(Triple::new(alice, name, Literal::new("Alice")))?;

println!("Store contains {} triples", store.len()?);

§Querying with Pattern Matching

use oxirs_core::RdfStore;
use oxirs_core::model::{NamedNode, Subject, Predicate};

// Query all triples with a specific predicate
let knows = NamedNode::new("http://xmlns.com/foaf/0.1/knows")?;
let predicate = Predicate::NamedNode(knows);

let triples = store.query_triples(None, Some(&predicate), None)?;
for triple in triples {
    println!("{:?} knows {:?}", triple.subject(), triple.object());
}

§Executing SPARQL Queries

use oxirs_core::RdfStore;

// Execute a SPARQL SELECT query
let query = r#"
    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
    SELECT ?name WHERE {
        ?person foaf:name ?name .
    }
"#;

let results = store.query(query)?;
println!("Query returned {} results", results.len());

§Loading Data from Files

use oxirs_core::RdfStore;
use oxirs_core::parser::{Parser, RdfFormat};
use std::fs;

// Load RDF data from a Turtle file
let content = fs::read_to_string("data.ttl")
    .map_err(|e| oxirs_core::OxirsError::Io(e.to_string()))?;

let parser = Parser::new(RdfFormat::Turtle);
let quads = parser.parse_str_to_quads(&content)?;

for quad in quads {
    store.insert_quad(quad)?;
}

println!("Loaded {} quads from file", store.len()?);

§Persistent Storage

use oxirs_core::RdfStore;
use oxirs_core::model::{NamedNode, Triple, Literal};

// Create a persistent store (data saved to disk)
let mut store = RdfStore::open("./my_rdf_store")?;

// Add data - automatically persisted
let subject = NamedNode::new("http://example.org/resource")?;
let predicate = NamedNode::new("http://purl.org/dc/terms/title")?;
let object = Literal::new("My Resource");

store.insert_triple(Triple::new(subject, predicate, object))?;

// Data is automatically saved to disk on modifications
println!("Data persisted to disk");

§Advanced Features

§Named Graphs (Quads)

use oxirs_core::RdfStore;
use oxirs_core::model::{NamedNode, Quad, GraphName, Literal};

// Create a quad with a named graph
let graph = GraphName::NamedNode(NamedNode::new("http://example.org/graph1")?);
let subject = NamedNode::new("http://example.org/subject")?;
let predicate = NamedNode::new("http://example.org/predicate")?;
let object = Literal::new("value");

let quad = Quad::new(subject, predicate, object, graph);
store.insert_quad(quad)?;

// Query specific graph
let graph_node = NamedNode::new("http://example.org/graph1")?;
let quads = store.graph_quads(Some(&graph_node))?;
println!("Graph contains {} quads", quads.len());

§Bulk Operations for Performance

use oxirs_core::RdfStore;
use oxirs_core::model::{NamedNode, Quad, Literal};

// Prepare many quads for bulk insert
let mut quads = Vec::new();
for i in 0..1000 {
    let subject = NamedNode::new(&format!("http://example.org/item{}", i))?;
    let predicate = NamedNode::new("http://example.org/value")?;
    let object = Literal::new(&i.to_string());
    quads.push(Quad::from_triple(Triple::new(subject, predicate, object)));
}

// Bulk insert for better performance
let ids = store.bulk_insert_quads(quads)?;
println!("Inserted {} quads with IDs: {:?}", ids.len(), &ids[..5]);

§Module Organization

model - Core RDF data model types (IRI, Literal, Blank Node, Triple, Quad)
rdf_store - RDF store implementations with pluggable storage backends
parser - RDF parsers for multiple serialization formats
serializer - RDF serializers for exporting data
query - SPARQL query algebra and execution engine
sparql - SPARQL query processing and federation
storage - Storage backends (memory, disk, columnar)
indexing - Multi-index structures for fast pattern matching
concurrent - Lock-free data structures for concurrent access
optimization - Query optimization and execution planning
federation - SPARQL federation for distributed queries
production - Production features (monitoring, health checks, circuit breakers)

§Feature Flags

serde - Enable serialization support (default)
parallel - Enable parallel processing with rayon (default)
simd - Enable SIMD optimizations for x86_64
async - Enable async I/O support
rocksdb - Enable RocksDB storage backend
rdf-star - Enable RDF-star (quoted triples) support
sparql-12 - Enable SPARQL 1.2 features

§Performance Tips

Use bulk operations - bulk_insert_quads() is faster than individual inserts
Choose the right backend - UltraMemory backend for maximum performance
Enable parallel feature - Leverage multi-core CPUs for query execution
Use indexed queries - Pattern matching benefits from multi-index structures
Profile with built-in metrics - Use SciRS2 metrics for bottleneck identification

§API Stability

As of Beta 1 (v0.1.0):

Stable APIs: Core RDF model types (NamedNode, Literal, Triple, Quad)
Stable APIs: Store operations (RdfStore, insert, query, remove)
Stable APIs: Parser and serializer interfaces
Unstable APIs: Advanced optimization features (may change)
Experimental: Consciousness, molecular, and quantum modules

See MIGRATION_GUIDE.md for migration from alpha versions.

§Architecture

For detailed architecture documentation, see ARCHITECTURE.md.

§Examples

More examples are available in the examples/ directory:

basic_store.rs - Basic store operations
sparql_query.rs - SPARQL query examples
persistent_store.rs - Persistent storage usage
bulk_loading.rs - High-performance bulk data loading
federation.rs - Federated SPARQL queries

Re-exports§

pub use rdf_store::ConcreteStore;
pub use rdf_store::RdfStore;
pub use rdf_store::Store;
pub use transaction::AcidTransaction;
pub use transaction::IsolationLevel;
pub use transaction::TransactionId;
pub use transaction::TransactionManager;
pub use transaction::TransactionState;
pub use model::*;

Modules§

ai: AI/ML Integration Platform for OxiRS
concurrent: Concurrent data structures for high-performance graph operations
consciousness: Consciousness-Inspired Computing Module
distributed: Distributed storage and consensus modules
error: Core error types for OxiRS
federation: SPARQL Federation support for distributed query execution
format: RDF Format Support Module
graph: RDF graph abstraction and operations
indexing: Ultra-high performance indexing for RDF data
interning: String interning system for performance optimization
io: I/O utilities for RDF data processing
jsonld: JSON-LD processing functionality for OxiRS Core
model: Core RDF data model types and implementations
molecular: Molecular-Level Memory Management
optimization: Zero-copy operations and performance optimizations
oxigraph_compat: Oxigraph compatibility layer
parallel: Parallel processing abstractions for OxiRS
parser: RDF parsing utilities for various formats with high-performance streaming
platform: Platform capabilities detection for OxiRS
production: Production Hardening Features for OxiRS Core
quantum: Quantum-Inspired Computing Module
query: SPARQL query processing module with full SciRS2 integration
rdf_store: RDF store implementation with pluggable storage backends
rdfxml: RDF/XML parsing and serialization support for OxiRS
serializer: RDF serialization utilities for various formats
simd: SIMD operations abstraction for OxiRS
simd_triple_matching: SIMD-optimized RDF triple pattern matching with full SciRS2-core integration
sparql: SPARQL query processing modules
storage: Next-Generation Storage Engine for OxiRS
store: High-performance store module with multi-index graph and term interning
transaction: ACID transaction support with Write-Ahead Logging
vocab: Common RDF vocabularies and namespaces
zero_copy_rdf: Zero-copy RDF operations using SciRS2-core’s memory management

Enums§

OxirsError: Core error type for OxiRS operations

Constants§

VERSION: Version information for OxiRS Core

Functions§

init: Initialize OxiRS Core with default configuration

Type Aliases§

Result: Result type alias for OxiRS operations

Crate oxirs_core

Crate oxirs_core Copy item path

§OxiRS Core - RDF and SPARQL Foundation

§Overview

§Key Features

§Core RDF Support

§Performance & Scalability

§SPARQL Foundation

§Storage & Persistence

§Production Features

§Quick Start

§Creating a Store and Adding Data

§Querying with Pattern Matching

§Executing SPARQL Queries

§Loading Data from Files

§Persistent Storage

§Advanced Features

§Named Graphs (Quads)

§Bulk Operations for Performance

§Module Organization

§Feature Flags

§Performance Tips

§API Stability

§Architecture

§Examples

Re-exports§

Modules§

Enums§

Constants§

Functions§

Type Aliases§

Crate oxirs_core