oxirs_arq/
materialized_views_types.rs

1//! Type definitions for the materialized view subsystem.
2//!
3//! This sibling module hosts the configuration, view, view-data, metadata,
4//! maintenance, cost, dependency, and recommendation types used by the
5//! [`materialized_views`](crate::materialized_views) facade.  The runtime
6//! manager, storage, scheduler, and recommendation engine implementations
7//! live in their own sibling modules.
8
9use std::collections::{HashMap, HashSet, VecDeque};
10use std::sync::{Arc, Mutex, RwLock};
11use std::time::{Duration, Instant, SystemTime};
12
13use crate::algebra::Solution;
14use crate::algebra::{Algebra, Expression, TriplePattern, Variable};
15use crate::cost_model::{CostEstimate, CostModel};
16use crate::statistics_collector::StatisticsCollector;
17
18/// Materialized view manager for query optimization
19pub struct MaterializedViewManager {
20    pub(crate) config: MaterializedViewConfig,
21    pub(crate) views: Arc<RwLock<HashMap<String, MaterializedView>>>,
22    pub(crate) view_storage: Arc<RwLock<ViewStorage>>,
23    pub(crate) rewriter: QueryRewriter,
24    pub(crate) maintenance_scheduler: MaintenanceScheduler,
25    pub(crate) cost_model: Arc<Mutex<CostModel>>,
26    #[allow(dead_code)]
27    pub(crate) statistics_collector: Arc<StatisticsCollector>,
28    pub(crate) usage_statistics: Arc<RwLock<ViewUsageStatistics>>,
29    pub(crate) recommendation_engine: ViewRecommendationEngine,
30}
31
32/// Configuration for materialized view management
33#[derive(Debug, Clone)]
34pub struct MaterializedViewConfig {
35    /// Maximum number of materialized views to maintain
36    pub max_views: usize,
37    /// Maximum memory usage for views (bytes)
38    pub max_memory_usage: usize,
39    /// Enable automatic view creation based on query patterns
40    pub auto_view_creation: bool,
41    /// Maintenance strategy for view updates
42    pub maintenance_strategy: MaintenanceStrategy,
43    /// Threshold for view utilization before considering removal
44    pub utilization_threshold: f64,
45    /// Maximum staleness allowed for views (seconds)
46    pub max_staleness: Duration,
47    /// Enable cost-based view selection
48    pub cost_based_selection: bool,
49    /// Enable incremental maintenance
50    pub incremental_maintenance: bool,
51}
52
53impl Default for MaterializedViewConfig {
54    fn default() -> Self {
55        Self {
56            max_views: 100,
57            max_memory_usage: 2 * 1024 * 1024 * 1024, // 2GB
58            auto_view_creation: true,
59            maintenance_strategy: MaintenanceStrategy::Lazy,
60            utilization_threshold: 0.1,               // 10% utilization
61            max_staleness: Duration::from_secs(3600), // 1 hour
62            cost_based_selection: true,
63            incremental_maintenance: true,
64        }
65    }
66}
67
68/// Maintenance strategies for materialized views
69#[derive(Debug, Clone, PartialEq, Eq)]
70pub enum MaintenanceStrategy {
71    /// Update views immediately when base data changes
72    Immediate,
73    /// Update views periodically
74    Periodic(Duration),
75    /// Update views when accessed and stale
76    Lazy,
77    /// Update views based on cost analysis
78    CostBased,
79    /// Hybrid approach combining multiple strategies
80    Hybrid,
81}
82
83/// Definition of a materialized view
84#[derive(Debug, Clone)]
85pub struct MaterializedView {
86    /// Unique identifier for the view
87    pub id: String,
88    /// Human-readable name
89    pub name: String,
90    /// Algebra expression defining the view query
91    pub definition: Algebra,
92    /// Current materialized data
93    pub data: ViewData,
94    /// Metadata about the view
95    pub metadata: ViewMetadata,
96    /// Maintenance information
97    pub maintenance_info: MaintenanceInfo,
98    /// Cost estimates for using this view
99    pub cost_estimates: ViewCostEstimates,
100    /// Dependencies on base data
101    pub dependencies: ViewDependencies,
102}
103
104/// Materialized data for a view
105#[derive(Debug, Clone)]
106pub struct ViewData {
107    /// Result set from the view query
108    pub results: Solution,
109    /// Size of the materialized data in bytes
110    pub size_bytes: usize,
111    /// Number of rows in the view
112    pub row_count: usize,
113    /// Timestamp when data was last materialized
114    pub materialized_at: SystemTime,
115    /// Checksum for data integrity
116    pub checksum: u64,
117}
118
119/// Metadata about a materialized view
120#[derive(Debug, Clone)]
121pub struct ViewMetadata {
122    /// When the view was created
123    pub created_at: SystemTime,
124    /// Who or what created the view
125    pub created_by: String,
126    /// Description of the view's purpose
127    pub description: String,
128    /// Tags for categorization
129    pub tags: Vec<String>,
130    /// Priority for maintenance (higher = more important)
131    pub priority: u8,
132    /// Expected lifetime of the view
133    pub expected_lifetime: Duration,
134}
135
136/// Maintenance information for a view
137#[derive(Debug, Clone)]
138pub struct MaintenanceInfo {
139    /// Last time the view was updated
140    pub last_updated: SystemTime,
141    /// Next scheduled maintenance time
142    pub next_maintenance: Option<SystemTime>,
143    /// Maintenance strategy for this specific view
144    pub strategy: MaintenanceStrategy,
145    /// Number of times the view has been updated
146    pub update_count: usize,
147    /// Total time spent maintaining the view
148    pub total_maintenance_time: Duration,
149    /// Whether the view needs updating
150    pub needs_update: bool,
151    /// Incremental update state
152    pub incremental_state: Option<IncrementalState>,
153}
154
155/// State for incremental view maintenance
156#[derive(Debug, Clone)]
157pub struct IncrementalState {
158    /// Last processed transaction ID
159    pub last_transaction_id: u64,
160    /// Change log for incremental updates
161    pub change_log: Vec<ChangeLogEntry>,
162    /// Delta computation state
163    pub delta_state: DeltaState,
164}
165
166/// Entry in the change log for incremental maintenance
167#[derive(Debug, Clone)]
168pub struct ChangeLogEntry {
169    /// Type of change (insert, delete, update)
170    pub change_type: ChangeType,
171    /// Affected triple or quad
172    pub affected_data: TriplePattern,
173    /// Timestamp of the change
174    pub timestamp: SystemTime,
175    /// Transaction ID
176    pub transaction_id: u64,
177}
178
179/// Types of changes for incremental maintenance
180#[derive(Debug, Clone, PartialEq, Eq)]
181pub enum ChangeType {
182    Insert,
183    Delete,
184    Update,
185}
186
187/// Delta computation state for incremental updates
188#[derive(Debug, Clone)]
189pub struct DeltaState {
190    /// Positive delta (insertions)
191    pub positive_delta: Solution,
192    /// Negative delta (deletions)
193    pub negative_delta: Solution,
194    /// Dirty flags for affected partitions
195    pub dirty_partitions: HashSet<u64>,
196}
197
198/// Cost estimates for using a materialized view
199#[derive(Debug, Clone)]
200pub struct ViewCostEstimates {
201    /// Cost of accessing the view
202    pub access_cost: CostEstimate,
203    /// Cost of maintaining the view
204    pub maintenance_cost: CostEstimate,
205    /// Storage cost (memory/disk usage)
206    pub storage_cost: f64,
207    /// Cost benefit compared to computing from scratch
208    pub benefit_ratio: f64,
209    /// Last time costs were estimated
210    pub last_estimated: SystemTime,
211}
212
213/// Dependencies of a view on base data
214#[derive(Debug, Clone)]
215pub struct ViewDependencies {
216    /// Base tables/graphs referenced by the view
217    pub base_tables: Vec<String>,
218    /// Specific triple patterns the view depends on
219    pub dependent_patterns: Vec<TriplePattern>,
220    /// Variables that affect view results
221    pub dependent_variables: HashSet<Variable>,
222    /// Join dependencies
223    pub join_dependencies: Vec<JoinDependency>,
224}
225
226/// Join dependency information
227#[derive(Debug, Clone)]
228pub struct JoinDependency {
229    /// Left side of the join
230    pub left_pattern: TriplePattern,
231    /// Right side of the join
232    pub right_pattern: TriplePattern,
233    /// Join variables
234    pub join_variables: Vec<Variable>,
235    /// Estimated selectivity
236    pub selectivity: f64,
237}
238
239/// Storage for materialized view data
240#[derive(Debug)]
241pub struct ViewStorage {
242    /// In-memory storage for view data
243    pub(crate) memory_storage: HashMap<String, ViewData>,
244    /// Disk-based storage path
245    pub(crate) disk_storage_path: Option<std::path::PathBuf>,
246    /// Maximum memory usage allowed
247    pub(crate) max_memory: usize,
248    /// Current memory usage
249    pub(crate) memory_usage: usize,
250    /// Storage statistics
251    pub(crate) storage_stats: StorageStatistics,
252}
253
254/// Statistics about view storage
255#[derive(Debug, Clone, Default)]
256pub struct StorageStatistics {
257    /// Total memory usage
258    pub total_memory_usage: usize,
259    /// Total disk usage
260    pub total_disk_usage: usize,
261    /// Number of views stored in memory
262    pub memory_view_count: usize,
263    /// Number of views stored on disk
264    pub disk_view_count: usize,
265    /// Cache hit rate
266    pub cache_hit_rate: f64,
267    /// Average access time
268    pub average_access_time: Duration,
269}
270
271/// Query rewriter for utilizing materialized views
272pub struct QueryRewriter {
273    pub(crate) view_index: ViewIndex,
274    #[allow(dead_code)]
275    pub(crate) rewrite_rules: Vec<RewriteRule>,
276    #[allow(dead_code)]
277    pub(crate) cost_threshold: f64,
278}
279
280/// Index for efficient view lookup during query rewriting
281#[derive(Debug)]
282pub struct ViewIndex {
283    /// Index by pattern structure
284    #[allow(dead_code)]
285    pub(crate) pattern_index: HashMap<String, Vec<String>>,
286    /// Index by variables
287    #[allow(dead_code)]
288    pub(crate) variable_index: HashMap<Variable, Vec<String>>,
289    /// Index by predicates
290    #[allow(dead_code)]
291    pub(crate) predicate_index: HashMap<String, Vec<String>>,
292    /// Index by query characteristics
293    pub(crate) characteristic_index: HashMap<QueryCharacteristic, Vec<String>>,
294}
295
296/// Query characteristics for view indexing
297#[derive(Debug, Clone, Hash, PartialEq, Eq)]
298pub enum QueryCharacteristic {
299    HasJoin,
300    HasFilter,
301    HasAggregation,
302    HasUnion,
303    PatternCount(usize),
304    VariableCount(usize),
305}
306
307/// Rule for query rewriting
308#[derive(Debug, Clone)]
309pub struct RewriteRule {
310    /// Name of the rule
311    pub name: String,
312    /// Pattern to match
313    pub pattern_matcher: PatternMatcher,
314    /// Rewrite transformation
315    pub transformation: RewriteTransformation,
316    /// Cost threshold for applying the rule
317    pub cost_threshold: f64,
318    /// Priority of the rule
319    pub priority: u8,
320}
321
322/// Pattern matcher for rewrite rules
323#[derive(Debug, Clone)]
324pub enum PatternMatcher {
325    /// Exact algebra match
326    ExactMatch(Algebra),
327    /// Structural pattern match
328    StructuralMatch(AlgebraPattern),
329    /// Semantic equivalence match
330    SemanticMatch(SemanticPattern),
331    /// Custom matcher function
332    Custom(String), // Function name for custom matching
333}
334
335/// Structural pattern for matching algebra expressions
336#[derive(Debug, Clone)]
337pub struct AlgebraPattern {
338    /// Pattern type
339    pub pattern_type: AlgebraPatternType,
340    /// Sub-patterns
341    pub sub_patterns: Vec<AlgebraPattern>,
342    /// Variable bindings
343    pub bindings: HashMap<String, Variable>,
344}
345
346/// Types of algebra patterns
347#[derive(Debug, Clone)]
348pub enum AlgebraPatternType {
349    BGP,
350    Join,
351    Union,
352    Filter,
353    Any,
354}
355
356/// Semantic pattern for advanced matching
357#[derive(Debug, Clone)]
358pub struct SemanticPattern {
359    /// Semantic equivalence rules
360    pub equivalence_rules: Vec<String>,
361    /// Containment relationships
362    pub containment_rules: Vec<String>,
363}
364
365/// Transformation for query rewriting
366#[derive(Debug, Clone)]
367pub enum RewriteTransformation {
368    /// Replace with view access
369    ReplaceWithView(String),
370    /// Partial replacement
371    PartialReplace(Box<PartialReplacement>),
372    /// Join with view
373    JoinWithView(JoinTransformation),
374    /// Union with view
375    UnionWithView(UnionTransformation),
376}
377
378/// Partial replacement transformation
379#[derive(Debug, Clone)]
380pub struct PartialReplacement {
381    /// View to use for partial replacement
382    pub view_id: String,
383    /// Remaining query parts
384    pub remaining_query: Algebra,
385    /// How to combine view results with remaining query
386    pub combination_strategy: CombinationStrategy,
387}
388
389/// Strategy for combining view results with remaining query
390#[derive(Debug, Clone)]
391pub enum CombinationStrategy {
392    Join(Vec<Variable>),
393    Union,
394    Filter(Expression),
395}
396
397/// Join transformation with a view
398#[derive(Debug, Clone)]
399pub struct JoinTransformation {
400    /// View to join with
401    pub view_id: String,
402    /// Join variables
403    pub join_variables: Vec<Variable>,
404    /// Join type
405    pub join_type: JoinType,
406}
407
408/// Types of joins for view transformations
409#[derive(Debug, Clone)]
410pub enum JoinType {
411    Inner,
412    Left,
413    Right,
414    Full,
415}
416
417/// Union transformation with a view
418#[derive(Debug, Clone)]
419pub struct UnionTransformation {
420    /// View to union with
421    pub view_id: String,
422    /// Whether to apply DISTINCT
423    pub distinct: bool,
424}
425
426/// Maintenance scheduler for materialized views
427pub struct MaintenanceScheduler {
428    pub(crate) scheduled_tasks: Arc<RwLock<VecDeque<MaintenanceTask>>>,
429    #[allow(dead_code)]
430    pub(crate) active_tasks: Arc<RwLock<HashMap<String, ActiveTask>>>,
431    #[allow(dead_code)]
432    pub(crate) config: SchedulerConfig,
433}
434
435/// Configuration for the maintenance scheduler
436#[derive(Debug, Clone)]
437pub struct SchedulerConfig {
438    /// Maximum concurrent maintenance tasks
439    pub max_concurrent_tasks: usize,
440    /// Default maintenance interval
441    pub default_interval: Duration,
442    /// Priority threshold for immediate scheduling
443    pub priority_threshold: u8,
444    /// Resource limits for maintenance
445    pub resource_limits: ResourceLimits,
446}
447
448/// Resource limits for maintenance operations
449#[derive(Debug, Clone)]
450pub struct ResourceLimits {
451    /// Maximum CPU usage percentage
452    pub max_cpu_usage: f64,
453    /// Maximum memory usage for maintenance
454    pub max_memory_usage: usize,
455    /// Maximum I/O bandwidth
456    pub max_io_bandwidth: usize,
457}
458
459impl Default for ResourceLimits {
460    fn default() -> Self {
461        Self {
462            max_cpu_usage: 50.0,
463            max_memory_usage: 1024 * 1024 * 512, // 512MB
464            max_io_bandwidth: 1024 * 1024 * 100, // 100MB/s
465        }
466    }
467}
468
469impl Default for SchedulerConfig {
470    fn default() -> Self {
471        Self {
472            max_concurrent_tasks: 4,
473            default_interval: Duration::from_secs(3600), // 1 hour
474            priority_threshold: 8,
475            resource_limits: ResourceLimits::default(),
476        }
477    }
478}
479
480/// Maintenance task for a view
481#[derive(Debug, Clone)]
482pub struct MaintenanceTask {
483    /// View to maintain
484    pub view_id: String,
485    /// Type of maintenance
486    pub task_type: MaintenanceTaskType,
487    /// Priority (higher = more urgent)
488    pub priority: u8,
489    /// Scheduled execution time
490    pub scheduled_time: SystemTime,
491    /// Estimated execution time
492    pub estimated_duration: Duration,
493    /// Resource requirements
494    pub resource_requirements: ResourceRequirements,
495}
496
497/// Types of maintenance tasks
498#[derive(Debug, Clone)]
499pub enum MaintenanceTaskType {
500    /// Full refresh of the view
501    FullRefresh,
502    /// Incremental update
503    IncrementalUpdate,
504    /// Recompute statistics
505    StatisticsUpdate,
506    /// Optimize view storage
507    StorageOptimization,
508    /// Validate view integrity
509    IntegrityCheck,
510}
511
512/// Resource requirements for a maintenance task
513#[derive(Debug, Clone)]
514pub struct ResourceRequirements {
515    /// Estimated CPU usage
516    pub cpu_usage: f64,
517    /// Estimated memory usage
518    pub memory_usage: usize,
519    /// Estimated I/O operations
520    pub io_operations: usize,
521    /// Network bandwidth requirements
522    pub network_bandwidth: usize,
523}
524
525/// Active maintenance task
526#[derive(Debug)]
527pub struct ActiveTask {
528    /// Task information
529    pub task: MaintenanceTask,
530    /// Start time
531    pub start_time: Instant,
532    /// Current progress (0.0 to 1.0)
533    pub progress: f64,
534    /// Cancellation flag
535    pub cancelled: bool,
536}
537
538/// Usage statistics for views
539#[derive(Debug, Default)]
540pub struct ViewUsageStatistics {
541    /// Access count per view
542    pub(crate) access_counts: HashMap<String, usize>,
543    /// Total query time saved per view
544    pub(crate) time_saved: HashMap<String, Duration>,
545    /// Hit rate per view
546    pub(crate) hit_rates: HashMap<String, f64>,
547    /// Cost benefit per view
548    pub(crate) cost_benefits: HashMap<String, f64>,
549    /// Usage patterns over time
550    pub(crate) usage_history: HashMap<String, VecDeque<UsageRecord>>,
551}
552
553/// Record of view usage
554#[derive(Debug, Clone)]
555pub struct UsageRecord {
556    /// Timestamp of usage
557    pub timestamp: SystemTime,
558    /// Query that used the view
559    pub query_hash: u64,
560    /// Time saved by using the view
561    pub time_saved: Duration,
562    /// Cost benefit achieved
563    pub cost_benefit: f64,
564}
565
566/// Engine for recommending new materialized views
567pub struct ViewRecommendationEngine {
568    #[allow(dead_code)]
569    pub(crate) query_patterns: Arc<RwLock<QueryPatternAnalyzer>>,
570    #[allow(dead_code)]
571    pub(crate) cost_analyzer: CostAnalyzer,
572    #[allow(dead_code)]
573    pub(crate) benefit_estimator: BenefitEstimator,
574    #[allow(dead_code)]
575    pub(crate) recommendation_cache: Arc<RwLock<HashMap<String, ViewRecommendation>>>,
576}
577
578/// Analyzer for query patterns
579#[derive(Debug)]
580pub struct QueryPatternAnalyzer {
581    /// Observed query patterns
582    #[allow(dead_code)]
583    pub(crate) patterns: HashMap<String, QueryPattern>,
584    /// Pattern frequency
585    #[allow(dead_code)]
586    pub(crate) pattern_frequency: HashMap<String, usize>,
587    /// Pattern cost statistics
588    #[allow(dead_code)]
589    pub(crate) pattern_costs: HashMap<String, CostStatistics>,
590}
591
592/// Observed query pattern
593#[derive(Debug, Clone)]
594pub struct QueryPattern {
595    /// Pattern signature
596    pub signature: String,
597    /// Algebra structure
598    pub algebra_structure: Algebra,
599    /// Common sub-patterns
600    pub sub_patterns: Vec<SubPattern>,
601    /// Variable usage patterns
602    pub variable_patterns: VariablePattern,
603    /// Join patterns
604    pub join_patterns: Vec<JoinPattern>,
605}
606
607/// Sub-pattern within a query
608#[derive(Debug, Clone)]
609pub struct SubPattern {
610    /// Pattern identifier
611    pub id: String,
612    /// Algebra expression
613    pub algebra: Algebra,
614    /// Frequency of occurrence
615    pub frequency: usize,
616    /// Estimated cost
617    pub estimated_cost: f64,
618}
619
620/// Variable usage pattern
621#[derive(Debug, Clone)]
622pub struct VariablePattern {
623    /// Variables used in the pattern
624    pub variables: HashSet<Variable>,
625    /// Variable binding patterns
626    pub binding_patterns: HashMap<Variable, BindingPattern>,
627    /// Variable selectivity
628    pub variable_selectivity: HashMap<Variable, f64>,
629}
630
631/// Binding pattern for a variable
632#[derive(Debug, Clone)]
633pub enum BindingPattern {
634    /// Always bound to constants
635    Constant(Vec<String>),
636    /// Bound through joins
637    Join(Vec<Variable>),
638    /// Bound through filters
639    Filter(Vec<Expression>),
640    /// Mixed binding pattern
641    Mixed,
642}
643
644/// Join pattern in queries
645#[derive(Debug, Clone)]
646pub struct JoinPattern {
647    /// Left side pattern
648    pub left_pattern: TriplePattern,
649    /// Right side pattern
650    pub right_pattern: TriplePattern,
651    /// Join variables
652    pub join_variables: Vec<Variable>,
653    /// Join selectivity
654    pub selectivity: f64,
655    /// Join cost
656    pub cost: f64,
657}
658
659/// Cost statistics for query patterns
660#[derive(Debug, Clone, Default)]
661pub struct CostStatistics {
662    /// Average execution cost
663    pub average_cost: f64,
664    /// Minimum execution cost
665    pub min_cost: f64,
666    /// Maximum execution cost
667    pub max_cost: f64,
668    /// Standard deviation
669    pub std_deviation: f64,
670    /// Number of samples
671    pub sample_count: usize,
672}
673
674/// Cost analyzer for view recommendations
675pub struct CostAnalyzer {
676    #[allow(dead_code)]
677    pub(crate) historical_costs: HashMap<String, Vec<f64>>,
678    #[allow(dead_code)]
679    pub(crate) cost_models: HashMap<String, CostModel>,
680}
681
682/// Benefit estimator for materialized views
683pub struct BenefitEstimator {
684    /// Historical benefit data
685    #[allow(dead_code)]
686    pub(crate) benefit_history: HashMap<String, Vec<f64>>,
687    /// Benefit prediction models
688    #[allow(dead_code)]
689    pub(crate) prediction_models: HashMap<String, BenefitModel>,
690}
691
692/// Model for predicting view benefits
693#[derive(Debug, Clone)]
694pub struct BenefitModel {
695    /// Model type
696    pub model_type: BenefitModelType,
697    /// Model parameters
698    pub parameters: HashMap<String, f64>,
699    /// Accuracy metrics
700    pub accuracy: f64,
701}
702
703/// Types of benefit prediction models
704#[derive(Debug, Clone)]
705pub enum BenefitModelType {
706    Linear,
707    Polynomial,
708    ExponentialDecay,
709    MachineLearning(String), // ML model type
710}
711
712/// Recommendation for a new materialized view
713#[derive(Debug, Clone)]
714pub struct ViewRecommendation {
715    /// Proposed view definition
716    pub view_definition: Algebra,
717    /// Estimated benefit
718    pub estimated_benefit: f64,
719    /// Confidence in the recommendation
720    pub confidence: f64,
721    /// Estimated creation cost
722    pub creation_cost: f64,
723    /// Estimated maintenance cost
724    pub maintenance_cost: f64,
725    /// Recommended maintenance strategy
726    pub maintenance_strategy: MaintenanceStrategy,
727    /// Supporting query patterns
728    pub supporting_patterns: Vec<String>,
729    /// Justification for the recommendation
730    pub justification: String,
731}
732
733/// Statistics for view usage
734#[derive(Debug, Clone)]
735pub struct ViewUsageStats {
736    pub access_count: usize,
737    pub total_time_saved: Duration,
738    pub hit_rate: f64,
739    pub cost_benefit: f64,
740}
oxirs_arq/materialized_views_types.rs

oxirs_arq/
materialized_views_types.rs
