Add comment for cost model ORM

Author: lanlou1554

optd-persistent/src/entities/statistic.rs

@@ -12,7 +12,7 @@ pub struct Model {
     pub created_time: DateTimeUtc,
     pub number_of_attributes: i32,
     pub statistic_type: i32,
-    pub data: String,
+    pub description: String,
 }
 
 #[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]

optd-persistent/src/migrator/cost_model/m20241029_000001_event.rs

@@ -1,3 +1,6 @@
+//! Every time we insert/update statistics, we need to insert a new
+//! row into this table to record the event.
+
 use sea_orm_migration::{prelude::*, schema::*};
 
 #[derive(Iden)]

optd-persistent/src/migrator/cost_model/m20241029_000001_physical_expression_to_statistic_junction.rs

@@ -1,3 +1,11 @@
+//! This table stores for a physical expression, which statistics are used, so we
+//! don't need to compute it again. It is especially useful for update_stats, where
+//! we need to invalidate all the costs based on the physical_expression_id, so we
+//! need to use this table to get the physical_expression_id via statistic_id.
+//!
+//! **NOTE:** When we compute the cost for a physical expression, we should also
+//! insert related mappings into this table.
+
 use crate::migrator::cost_model::statistic::Statistic;
 use crate::migrator::memo::physical_expression::PhysicalExpression;
 

optd-persistent/src/migrator/cost_model/m20241029_000001_plan_cost.rs

@@ -1,14 +1,6 @@
-/*
-Table plan_cost {
-  id integer PK
-  physical_expression_id integer [ref: > physical_expression.id]
-  epoch_id integer [ref: > event.epoch_id]
-  cost integer
-  // Whether the cost is valid or not. If the latest cost for an expr is invalid, then we need to recompute the cost.
-  // We need to invalidate the cost when the related stats are updated.
-  is_valid boolean
-}
-*/
+//! When a statistic is updated, then all the related costs should be invalidated. (IsValid is set to false)
+//! This design (using IsValid flag) is based on the assumption that update_stats will not be called very frequently.
+//! It favors the compute_cost performance over the update_stats performance.
 
 use crate::migrator::cost_model::event::Event;
 use crate::migrator::memo::physical_expression::PhysicalExpression;
@@ -21,6 +13,8 @@ pub enum PlanCost {
     PhysicalExpressionId,
     EpochId,
     Cost,
+    // Whether the cost is valid or not. If the latest cost for an expr is invalid, then we need to recompute the cost.
+    // We need to invalidate the cost when the related stats are updated.
     IsValid,
 }
 

optd-persistent/src/migrator/cost_model/m20241029_000001_statistic.rs

@@ -1,3 +1,10 @@
+//! This table stores the statistic infos. One sole statistic only has one row in this table.
+//!
+//! If we want to insert a new statistic, we should first insert one row into this table, then add a new
+//! event, and finally insert the statistic value into the versioned_statistic table.
+//! If we want to update a statistic, we should first find the real statistic id from this table, then
+//! add a new event, and finally insert the statistic value into the versioned_statistic table.
+
 use crate::migrator::catalog::m20241029_000001_table_metadata::TableMetadata;
 use sea_orm_migration::{prelude::*, schema::*};
 
@@ -6,11 +13,18 @@ pub enum Statistic {
     Table,
     Id,
     Name,
+    // null if not a table statistic.
     TableId,
     CreatedTime,
+    // 0 if a table statistic.
     NumberOfAttributes,
+    // TODO(lanlou): Should we make another table to explain the type mapping?
     StatisticType,
-    Data,
+    // Store the sorted attribute ids of this statistic, to support quick lookup (OR we can use junction table to look up)
+    // For example, if we want to store the statistic of attributes [1, 2, 3], we can store it as "1,2,3".
+    // During lookup, we should first sort the attribute ids, and then look up.
+    // OR we can use statistic_to_attribute_junction table to look up.
+    Description,
 }
 
 #[derive(DeriveMigrationName)]
@@ -37,7 +51,7 @@ impl MigrationTrait for Migration {
                     .col(timestamp(Statistic::CreatedTime))
                     .col(integer(Statistic::NumberOfAttributes))
                     .col(integer(Statistic::StatisticType))
-                    .col(string(Statistic::Data))
+                    .col(string(Statistic::Description))
                     .to_owned(),
             )
             .await

optd-persistent/src/migrator/cost_model/m20241029_000001_versioned_statistic.rs

@@ -1,3 +1,7 @@
+//! This table stores the versioned statistics. It includes all the histories of the statistics.
+//!
+//! If a statistic is updated/inserted, please insert one new row into this table.
+
 use crate::migrator::cost_model::{event::Event, statistic::Statistic};
 use sea_orm_migration::{prelude::*, schema::*};
 
@@ -6,6 +10,7 @@ pub enum VersionedStatistic {
     Table,
     Id,
     EpochId,
+    // Real statistic id.
     StatisticId,
     StatisticValue,
 }

schema/all_tables.dbml

@@ -37,7 +37,7 @@ Table statistic {
   created_time timestamp
   number_of_attributes integer // 0 if a table statistic
   statistic_type integer // Should we make another table to explain the type mapping?
-  data varchar // Store the sorted attribute ids of this statistic, to support quick lookup (OR we can use junction table to look up)
+  description varchar // Store the sorted attribute ids of this statistic, to support quick lookup (OR we can use junction table to look up)
 }
 
 Table versioned_statistic {