add doc for cost model migrators

Author: xx01cyx

optd-persistent/src/migrator/catalog/m20241029_000001_attribute_constraint_junction.rs

@@ -1,10 +1,9 @@
-/*
-// The constrained attributes (columns) if a constraint is a table constraint (including foreign keys, but not constraint triggers)
-Table attribute_constraint_junction {
-  attribute_id integer [ref: > attribute.id]
-  constraint_id integer [ref: > constraint.id]
-}
-*/
+//! An entity representing the relationship between [`attribute`] and [`constraint`].
+//!
+//! If a constraint is a table constraint (including foreign keys, but not constraint triggers),
+//! the attributes that are constrained on are stored in the [`attribute_constraint_junction`].
+//!
+//! One constraint might be associated with multiple attributes, for example, a composite primary key.
 
 use crate::migrator::catalog::{attribute::Attribute, constraint::Constraint};
 use sea_orm_migration::{prelude::*, schema::*};

optd-persistent/src/migrator/catalog/m20241029_000001_attribute_foreign_constraint_junction.rs

@@ -1,3 +1,14 @@
+//! An entity representing the relationship between [`attribute`] and [`constraint`].
+//!
+//! If a constraint is a foreign key constraint, the attributes that are referenced by the foreign
+//! key are stored in the [`attribute_foreign_constraint_junction`]. Note that this is different from
+//! the [`attribute_constraint_junction`] table, which stores the attributes that are constrained on.
+//! In the case of a foreign key constraint, this refers to the attributes that are referecing from the
+//! foreign key.
+//!
+//! One foreign key constraint might be associated with multiple attributes, for example, a composite
+//! foreign key.
+
 use crate::migrator::catalog::{attribute::Attribute, constraint::Constraint};
 use sea_orm_migration::{prelude::*, schema::*};
 

optd-persistent/src/migrator/catalog/m20241029_000001_index.rs

@@ -1,18 +1,3 @@
-/*
-Table index {
-  id integer PK
-  name varchar
-  table_id integer [ref: > table_metadata.id]
-  number_of_attributes integer
-  is_unique boolean
-  nulls_not_distinct boolean // Only valid for unique index, if true, then null value is equal, if false, null value is distinct
-  is_primary boolean
-  is_clustered boolean // If true, the table was last clustered on this index
-  is_exclusion boolean // More fields might be added in the future for expressiveness on exclusion constraint.
-  data json // Stores the attribute ids. The reason for not creating an additional junction table is the same as with the attribute_stats table.
-}
- */
-
 use crate::migrator::catalog::table_metadata::TableMetadata;
 use sea_orm_migration::{prelude::*, schema::*};
 

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

@@ -1,9 +1,8 @@
-/*
-Table statistic_attribute_junction {
-  statistic_id integer [ref: > statistic.id]
-  attribute_id integer [ref: > attribute.id]
-}
- */
+//! An entity representing the relationship between [`statistic`] and [`attribute`].
+//!
+//! One [`statistic`] can be associated with multiple [`attribute`]s, which denotes a joint
+//! statistic for the attributes. On the other hand, one [`attribute`] can be associated with
+//! multiple [`statistic`]s, since the attribute can be used in multiple statistics.
 
 use crate::migrator::catalog::attribute::Attribute;
 use crate::migrator::cost_model::statistic::Statistic;