Crate oxirs_star

Expand description

§OxiRS RDF-Star

Status: Production Release (v0.2.2) Stability: Public APIs are stable. Production-ready with comprehensive testing.

RDF-star and SPARQL-star implementation providing comprehensive support for quoted triples.

This crate extends the standard RDF model with RDF-star capabilities, allowing triples to be used as subjects or objects in other triples (quoted triples). It provides:

Complete RDF-star data model with proper type safety
Parsing support for Turtle-star, N-Triples-star, TriG-star, and N-Quads-star
SPARQL-star query execution with quoted triple patterns
Serialization to all major RDF-star formats
Storage backend integration with oxirs-core
Performance-optimized handling of nested quoted triples
Comprehensive CLI tools for validation and debugging
Advanced error handling with context and recovery suggestions

§Quick Start

§Basic Quoted Triple Creation

use oxirs_star::{StarStore, StarTriple, StarTerm};

let mut store = StarStore::new();

// Create a quoted triple
let quoted = StarTriple::new(
    StarTerm::iri("http://example.org/person1")?,
    StarTerm::iri("http://example.org/age")?,
    StarTerm::literal("25")?,
);

// Use the quoted triple as a subject
let meta_triple = StarTriple::new(
    StarTerm::quoted_triple(quoted),
    StarTerm::iri("http://example.org/certainty")?,
    StarTerm::literal("0.9")?,
);

store.insert(&meta_triple)?;
println!("Stored {} triples", store.len());

§Parsing RDF-star Data

use oxirs_star::parser::{StarParser, StarFormat};

let turtle_star = r#"
    @prefix ex: <http://example.org/> .

    << ex:alice ex:age 30 >> ex:certainty 0.9 .
    << ex:alice ex:name "Alice" >> ex:source ex:census2020 .
"#;

let mut parser = StarParser::new();
let graph = parser.parse_str(turtle_star, StarFormat::TurtleStar)?;

println!("Parsed {} quoted triples", graph.len());

§Using the CLI Tools

# Validate an RDF-star file
oxirs-star validate data.ttls --strict

# Convert between formats
oxirs-star convert input.ttls output.nts --to ntriples-star --pretty

# Analyze data structure
oxirs-star analyze large_dataset.ttls --json --output report.json

# Debug parsing issues
oxirs-star debug problematic.ttls --line 42 --context 5

§Advanced Usage

§Nested Quoted Triples

use oxirs_star::{StarStore, StarTriple, StarTerm, StarConfig};

// Configure for deep nesting
let config = StarConfig {
    max_nesting_depth: 20,
    ..Default::default()
};

let mut store = StarStore::with_config(config);

// Create deeply nested structure
let base = StarTriple::new(
    StarTerm::iri("http://example.org/alice")?,
    StarTerm::iri("http://example.org/age")?,
    StarTerm::literal("30")?,
);

let meta = StarTriple::new(
    StarTerm::quoted_triple(base),
    StarTerm::iri("http://example.org/certainty")?,
    StarTerm::literal("0.9")?,
);

let meta_meta = StarTriple::new(
    StarTerm::quoted_triple(meta),
    StarTerm::iri("http://example.org/source")?,
    StarTerm::iri("http://example.org/study2023")?,
);

store.insert(&meta_meta)?;
let stats = store.statistics();
println!("Max nesting depth: {}", stats.max_nesting_encountered);

§Performance Optimization

use oxirs_star::{StarStore, StarConfig};

// Configure for high-performance scenarios
let config = StarConfig {
    max_nesting_depth: 10,
    enable_reification_fallback: true,
    buffer_size: 16384,  // Larger buffer for streaming
    strict_mode: false,  // Allow recovery from minor issues
    ..Default::default()
};

let store = StarStore::with_config(config);
println!("Store configured for high performance");

§Error Handling

The crate provides detailed error types with context and recovery suggestions:

use oxirs_star::{StarError, StarResult};

fn handle_errors() -> StarResult<()> {
    // ... some operation that might fail
    Err(StarError::NestingDepthExceeded {
        max_depth: 10,
        current_depth: 15,
        context: Some("While parsing complex quoted triple".to_string()),
    })
}

match handle_errors() {
    Err(e) => {
        eprintln!("Error: {}", e);
        for suggestion in e.recovery_suggestions() {
            eprintln!("Suggestion: {}", suggestion);
        }
    }
    Ok(_) => println!("Success"),
}

§Troubleshooting

§Common Issues

Parsing Errors: Use oxirs-star debug to identify syntax issues
Performance Issues: Enable indexing and adjust buffer sizes
Memory Usage: Reduce nesting depth or enable reification fallback
Format Detection: Explicitly specify format if auto-detection fails

§Getting Help

Use the dev_tools module for validation and diagnostics
Check the comprehensive documentation in the docs module
Run oxirs-star --help for CLI usage information
See the examples directory for real-world usage patterns

Re-exports§

pub use enhanced_errors::EnhancedError;
pub use enhanced_errors::EnhancedResult;
pub use enhanced_errors::ErrorAggregator;
pub use enhanced_errors::ErrorCategory;
pub use enhanced_errors::ErrorContext;
pub use enhanced_errors::ErrorSeverity;
pub use enhanced_errors::WithErrorContext;
pub use store::StarStore;
pub use troubleshooting::DiagnosticAnalyzer;
pub use troubleshooting::MigrationAssistant;
pub use troubleshooting::TroubleshootingGuide;
pub use model::*;

Modules§

adaptive_query_optimizer: Adaptive Query Optimizer with Auto-Tuning Capabilities
advanced_query: Advanced SPARQL-star query patterns
annotation_aggregation: Annotation aggregation and rollup for RDF-star
annotation_graph
annotation_lifecycle: Annotation lifecycle management for RDF-star
annotation_paths: RDF-star Annotation Paths
annotation_profile: RDF-star annotation profiles.
annotations: Annotation support for RDF-star quoted triples
backup_restore: Backup and restore functionality for RDF-star data
bloom_filter: Bloom filter implementation for efficient existence checks in RDF-star stores
cache: Cache modules for RDF-star query results.
cli: Command-line interface tools for RDF-star validation and debugging.
cluster_scaling: Horizontal scaling support for RDF-star annotations
compact_annotation_storage: Compact storage format for RDF-star annotation metadata
compatibility: Legacy RDF compatibility layer for standard RDF tools
compliance: W3C RDF-star Compliance Checker
compliance_reporting: Compliance reporting for RDF-star operations
cryptographic_provenance: Cryptographic provenance chains with digital signatures
dev_tools: Developer tooling and debugging utilities
distributed: Distributed RDF-star query processing modules.
docs: Comprehensive documentation and examples for RDF-star.
enhanced_errors: Enhanced Error Handling for RDF-star
execution: Parallel and streaming SPARQL-star execution modules.
functions: SPARQL-star built-in functions for working with quoted triples.
governance: Meta-annotations for governance and policy enforcement
gpu_acceleration: GPU-Accelerated RDF-star Processing
graph_diff: Graph diff tool for comparing annotated RDF-star graphs
graph_merger: RDF-star graph merging with conflict resolution (v1.1.0 round 15).
graphql_star: GraphQL integration for querying RDF-star data
hdt_star: HDT-star Format Support
index: Indexing structures for RDF-star quoted triples.
jit_query_engine: JIT-Compiled SPARQL-star Query Engine
kg_embeddings: Knowledge Graph Embeddings for RDF-star
lsm_annotation_store: LSM-tree based annotation store for high-performance writes
materialized_views: Materialized views for RDF-star annotation queries
memory_efficient_store: Memory-efficient storage for large RDF-star graphs using scirs2-core
migration_tools: Migration tools for converting standard RDF to RDF-star
ml_embedding_pipeline: Production ML Pipeline for Knowledge Graph Embeddings
ml_sparql_optimizer: Machine Learning-Enhanced SPARQL-star Query Optimizer
model: RDF-star data model providing type-safe handling of quoted triples.
monitoring: Comprehensive monitoring and metrics for RDF-star operations
parallel_query: Parallel SPARQL-star query optimizer using scirs2-core
parser: RDF-star parsing implementations for various formats.
production: Production hardening features for RDF-star deployments
profiling: Performance profiling and analysis tools for RDF-star operations.
property_graph_bridge: Property Graph Bridge for RDF-star
provenance_tracker: RDF-star provenance tracking.
quantum_sparql_optimizer: Quantum-Enhanced SPARQL-star Query Optimizer
query: SPARQL-star query processing modules.
query_optimizer: Query plan optimization for SPARQL-star queries
quoted_graph: Optimized Storage for Quoted Triple Graphs (RDF-star)
quoted_triple_store
rdf_patch: RDF Patch format (W3C) for incremental graph changes.
rdf_star_formats: Turtle-star and N-Triples-star serializers and parsers with round-trip support.
rdf_star_serializer
reasoning: Reasoning engine for RDF-star with quoted triples
reification: Reification utilities for converting between RDF-star and standard RDF.
reification_bridge: Enhanced Reification Bridge: bidirectional conversion between legacy RDF reification (rdf:Statement) and RDF-star quoted triples.
reification_mapper: Mapping between RDF reification and RDF-star quoted triples.
security_audit: Security audit logging for RDF-star operations
semantics: RDF-star semantics and entailment rules
serialization: RDF-star serialization module.
serializer: RDF-star serialization module
shacl_star: SHACL-star support for validating RDF-star data with quoted triples
sparql: SPARQL-star query pattern matching.
sparql_enhanced: Enhanced SPARQL-star features for full specification compliance
sparql_star_bind_values: SPARQL-Star BIND/VALUES Extensions
sparql_star_extended: Extended SPARQL-star query patterns.
star_normalizer: RDF-star graph normalization.
star_pattern_matcher
star_query_rewriter: RDF-star query to standard RDF rewriting.
star_statistics: RDF-star graph statistics collector (v1.1.0 round 14). RDF-star graph statistics collector.
storage: Extended storage modules for RDF-star data.
storage_integration: Storage backend integration for RDF-star with oxirs-core
store: RDF-star storage implementation with efficient handling of quoted triples.
streaming_query: Streaming Query Processor for RDF-star
temporal_versioning: Temporal versioning for RDF-star annotations
testing_utilities: Testing utilities for RDF-star applications
tiered_storage: Tiered storage for RDF-star annotations
triple_diff: RDF / RDF-star graph diff: added/removed triples, RDF Patch generation/application, symmetric difference, blank-node-aware isomorphic diff (v1.1.0 round 13) RDF / RDF-star graph diff utilities.
triple_reifier
troubleshooting: Comprehensive troubleshooting and diagnostic tools for RDF-star.
trust_scoring: Trust scoring and confidence propagation for RDF-star annotations
validation_framework: Comprehensive validation framework for RDF-star data
w3c_compliance: W3C RDF-star Compliance: Quoted Triple handling, AnnotationPattern, Asserted/Unasserted distinction, and SPARQL-star function validation.
write_ahead_log: Write-Ahead Logging (WAL) for durability and crash recovery

Macros§

profile_operation: Convenience macro for profiling operations

Structs§

ParseErrorDetails: Parse error details for RDF-star format
StarConfig: Configuration for RDF-star processing
StarStatistics: Statistics for RDF-star processing

Enums§

StarError: RDF-star specific error types

Constants§

VERSION: Version information

Functions§

init_star_system: Initialize the RDF-star system with configuration
validate_nesting_depth: Utility function to validate quoted triple nesting depth

Type Aliases§

StarResult: Result type for RDF-star operations

Crate oxirs_star

Crate oxirs_star Copy item path

§OxiRS RDF-Star

§Quick Start

§Basic Quoted Triple Creation

§Parsing RDF-star Data

§Using the CLI Tools

§Advanced Usage

§Nested Quoted Triples

§Performance Optimization

§Error Handling

§Troubleshooting

§Common Issues

§Getting Help

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate oxirs_star