add expression representation and refactor memo

This commit adds the `src/expression` module which contains a very
simple representation of Cascades expressions.

The `Memo` trait interface and implemenation has also changed, where
it now correctly detects exact match duplicates, and it does not track
fingerprints for physical expressions (only logical).

TODO: Add the duplicate detection to the other methods that need them.
TODO: Add more tests.
TODO: Figure out how to test in CI.

Author: connortsui20

.gitignore

@@ -10,4 +10,4 @@ target/
 
 # We will check in all code-generated entity files, as newer versions of `sea-orm-cli` might
 # conflict with previous versions.
-# **/entities
+# **/entities

optd-mvp/src/entities/physical_expression.rs

@@ -8,7 +8,6 @@ pub struct Model {
     #[sea_orm(primary_key)]
     pub id: i32,
     pub group_id: i32,
-    pub fingerprint: i64,
     pub kind: i16,
     pub data: Json,
 }

optd-mvp/src/expression/logical_expression.rs

@@ -0,0 +1,121 @@
+//! Definition of logical expressions / relations in the Cascades query optimization framework.
+//!
+//! FIXME: All fields are placeholders, and group IDs are just represented as i32 for now.
+//!
+//! TODO figure out if each relation should be in a different submodule.
+
+use crate::entities::*;
+use serde::{Deserialize, Serialize};
+use std::hash::{DefaultHasher, Hash, Hasher};
+
+#[derive(Clone, Debug)]
+pub enum LogicalExpression {
+    Scan(Scan),
+    Filter(Filter),
+    Join(Join),
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct Scan {
+    table_schema: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct Filter {
+    child: i32,
+    expression: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct Join {
+    left: i32,
+    right: i32,
+    expression: String,
+}
+
+/// TODO Use a macro instead.
+impl From<logical_expression::Model> for LogicalExpression {
+    fn from(value: logical_expression::Model) -> Self {
+        match value.kind {
+            0 => Self::Scan(
+                serde_json::from_value(value.data)
+                    .expect("unable to deserialize data into a logical `Scan`"),
+            ),
+            1 => Self::Filter(
+                serde_json::from_value(value.data)
+                    .expect("Unable to deserialize data into a logical `Filter`"),
+            ),
+            2 => Self::Join(
+                serde_json::from_value(value.data)
+                    .expect("Unable to deserialize data into a logical `Join`"),
+            ),
+            _ => panic!(),
+        }
+    }
+}
+
+/// TODO Use a macro instead.
+impl From<LogicalExpression> for logical_expression::Model {
+    fn from(value: LogicalExpression) -> logical_expression::Model {
+        fn create_logical_expression(
+            kind: i16,
+            data: serde_json::Value,
+        ) -> logical_expression::Model {
+            let mut hasher = DefaultHasher::new();
+            kind.hash(&mut hasher);
+            data.hash(&mut hasher);
+            let fingerprint = hasher.finish() as i64;
+
+            logical_expression::Model {
+                id: -1,
+                group_id: -1,
+                fingerprint,
+                kind,
+                data,
+            }
+        }
+
+        match value {
+            LogicalExpression::Scan(scan) => create_logical_expression(
+                0,
+                serde_json::to_value(scan).expect("unable to serialize logical `Scan`"),
+            ),
+            LogicalExpression::Filter(filter) => create_logical_expression(
+                1,
+                serde_json::to_value(filter).expect("unable to serialize logical `Filter`"),
+            ),
+            LogicalExpression::Join(join) => create_logical_expression(
+                2,
+                serde_json::to_value(join).expect("unable to serialize logical `Join`"),
+            ),
+        }
+    }
+}
+
+#[cfg(test)]
+pub use build::*;
+
+#[cfg(test)]
+mod build {
+    use super::*;
+    use crate::expression::Expression;
+
+    pub fn scan(table_schema: String) -> Expression {
+        Expression::Logical(LogicalExpression::Scan(Scan { table_schema }))
+    }
+
+    pub fn filter(child_group: i32, expression: String) -> Expression {
+        Expression::Logical(LogicalExpression::Filter(Filter {
+            child: child_group,
+            expression,
+        }))
+    }
+
+    pub fn join(left_group: i32, right_group: i32, expression: String) -> Expression {
+        Expression::Logical(LogicalExpression::Join(Join {
+            left: left_group,
+            right: right_group,
+            expression,
+        }))
+    }
+}

optd-mvp/src/expression/mod.rs

@@ -0,0 +1,62 @@
+//! In-memory representation of Cascades logical and physical expression / operators / relations.
+//!
+//! TODO more docs.
+
+mod logical_expression;
+pub use logical_expression::*;
+
+mod physical_expression;
+pub use physical_expression::*;
+
+/// The representation of a Cascades expression.
+///
+/// TODO more docs.
+#[derive(Clone, Debug)]
+pub enum Expression {
+    Logical(LogicalExpression),
+    Physical(PhysicalExpression),
+}
+
+/// Converts the database / JSON representation of a logical expression into an in-memory one.
+impl From<crate::entities::logical_expression::Model> for Expression {
+    fn from(value: crate::entities::logical_expression::Model) -> Self {
+        Self::Logical(value.into())
+    }
+}
+
+/// Converts the in-memory representation of a logical expression into the database / JSON version.
+///
+/// # Panics
+///
+/// This will panic if the [`Expression`] is [`Expression::Physical`].
+impl From<Expression> for crate::entities::logical_expression::Model {
+    fn from(value: Expression) -> Self {
+        let Expression::Logical(expr) = value else {
+            panic!("Attempted to convert an in-memory physical expression into a logical database / JSON expression");
+        };
+
+        expr.into()
+    }
+}
+
+/// Converts the database / JSON representation of a physical expression into an in-memory one.
+impl From<crate::entities::physical_expression::Model> for Expression {
+    fn from(value: crate::entities::physical_expression::Model) -> Self {
+        Self::Physical(value.into())
+    }
+}
+
+/// Converts the in-memory representation of a physical expression into the database / JSON version.
+///
+/// # Panics
+///
+/// This will panic if the [`Expression`] is [`Expression::Physical`].
+impl From<Expression> for crate::entities::physical_expression::Model {
+    fn from(value: Expression) -> Self {
+        let Expression::Physical(expr) = value else {
+            panic!("Attempted to convert an in-memory logical expression into a physical database / JSON expression");
+        };
+
+        expr.into()
+    }
+}

optd-mvp/src/expression/physical_expression.rs

@@ -0,0 +1,114 @@
+//! Definition of physical expressions / operators in the Cascades query optimization framework.
+//!
+//! FIXME: All fields are placeholders, and group IDs are just represented as i32 for now.
+//!
+//! TODO figure out if each operator should be in a different submodule.
+
+use crate::entities::*;
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Debug)]
+pub enum PhysicalExpression {
+    TableScan(TableScan),
+    Filter(PhysicalFilter),
+    HashJoin(HashJoin),
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct TableScan {
+    table_schema: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct PhysicalFilter {
+    child: i32,
+    expression: String,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct HashJoin {
+    left: i32,
+    right: i32,
+    expression: String,
+}
+
+/// TODO Use a macro instead.
+impl From<physical_expression::Model> for PhysicalExpression {
+    fn from(value: physical_expression::Model) -> Self {
+        match value.kind {
+            0 => Self::TableScan(
+                serde_json::from_value(value.data)
+                    .expect("unable to deserialize data into a physical `TableScan`"),
+            ),
+            1 => Self::Filter(
+                serde_json::from_value(value.data)
+                    .expect("Unable to deserialize data into a physical `Filter`"),
+            ),
+            2 => Self::HashJoin(
+                serde_json::from_value(value.data)
+                    .expect("Unable to deserialize data into a physical `HashJoin`"),
+            ),
+            _ => panic!(),
+        }
+    }
+}
+
+/// TODO Use a macro instead.
+impl From<PhysicalExpression> for physical_expression::Model {
+    fn from(value: PhysicalExpression) -> physical_expression::Model {
+        fn create_physical_expression(
+            kind: i16,
+            data: serde_json::Value,
+        ) -> physical_expression::Model {
+            physical_expression::Model {
+                id: -1,
+                group_id: -1,
+                kind,
+                data,
+            }
+        }
+
+        match value {
+            PhysicalExpression::TableScan(scan) => create_physical_expression(
+                0,
+                serde_json::to_value(scan).expect("unable to serialize physical `TableScan`"),
+            ),
+            PhysicalExpression::Filter(filter) => create_physical_expression(
+                1,
+                serde_json::to_value(filter).expect("unable to serialize physical `Filter`"),
+            ),
+            PhysicalExpression::HashJoin(join) => create_physical_expression(
+                2,
+                serde_json::to_value(join).expect("unable to serialize physical `HashJoin`"),
+            ),
+        }
+    }
+}
+
+#[cfg(test)]
+pub use build::*;
+
+#[cfg(test)]
+mod build {
+    use super::*;
+    use crate::expression::Expression;
+
+    pub fn table_scan(table_schema: String) -> Expression {
+        Expression::Physical(PhysicalExpression::TableScan(TableScan { table_schema }))
+    }
+
+    pub fn filter(child_group: i32, expression: String) -> Expression {
+        Expression::Physical(PhysicalExpression::Filter(PhysicalFilter {
+            child: child_group,
+            expression,
+        }))
+    }
+
+    pub fn hash_join(left_group: i32, right_group: i32, expression: String) -> Expression {
+        Expression::Physical(PhysicalExpression::HashJoin(HashJoin {
+            left: left_group,
+            right: right_group,
+            expression,
+        }))
+    }
+}

optd-mvp/src/lib.rs

@@ -10,6 +10,8 @@ mod entities;
 mod memo;
 use memo::MemoError;
 
+mod expression;
+
 /// The filename of the SQLite database for migration.
 pub const DATABASE_FILENAME: &str = "sqlite.db";
 /// The URL of the SQLite database for migration.

optd-mvp/src/memo/interface.rs

@@ -1,3 +1,6 @@
+//! This module defines the [`Memo`] trait, which defines shared behavior of all memo table that can
+//! be used for query optimization in the Cascades framework.
+
 use crate::OptimizerResult;
 use thiserror::Error;
 
@@ -75,6 +78,11 @@ pub trait Memo {
         group_id: Self::GroupId,
     ) -> OptimizerResult<Vec<Self::PhysicalExpressionId>>;
 
+    /// Checks if a given logical expression is unique.
+    ///
+    /// TODO more docs.
+    async fn is_unique_logical_expression(&self) -> OptimizerResult<bool>;
+
     /// Updates / replaces a group's best physical plan (winner). Optionally returns the previous
     /// winner's physical expression ID.
     ///
@@ -85,39 +93,45 @@ pub trait Memo {
         physical_expression_id: Self::PhysicalExpressionId,
     ) -> OptimizerResult<Option<Self::PhysicalExpressionId>>;
 
-    /// Adds a logical expression to an existing group via its [`Self::GroupId`]. This function
+    /// Adds a physical expression to an existing group via its [`Self::GroupId`]. This function
     /// assumes that insertion of this expression would not create any duplicates.
     ///
     /// The caller is required to pass in a slice of `GroupId` that represent the child groups of
     /// the input expression.
     ///
-    /// The caller is also required to set the `group_id` field of the input `logical_expression`
+    /// The caller is also required to set the `group_id` field of the input `physical_expression`
     /// to be equal to `group_id`, otherwise this function will return a
     /// [`MemoError::InvalidExpression`] error.
     ///
     /// If the group does not exist, returns a [`MemoError::UnknownGroup`] error.
-    async fn add_logical_expression_to_group(
+    ///
+    /// FIXME: This needs to have a mechanism of reporting that a duplicate expression was found in
+    /// another group.
+    async fn add_physical_expression_to_group(
         &self,
         group_id: Self::GroupId,
-        logical_expression: Self::LogicalExpression,
+        physical_expression: Self::PhysicalExpression,
         children: &[Self::GroupId],
     ) -> OptimizerResult<()>;
 
-    /// Adds a physical expression to an existing group via its [`Self::GroupId`]. This function
+    /// Adds a logical expression to an existing group via its [`Self::GroupId`]. This function
     /// assumes that insertion of this expression would not create any duplicates.
     ///
     /// The caller is required to pass in a slice of `GroupId` that represent the child groups of
     /// the input expression.
     ///
-    /// The caller is also required to set the `group_id` field of the input `physical_expression`
+    /// The caller is also required to set the `group_id` field of the input `logical_expression`
     /// to be equal to `group_id`, otherwise this function will return a
     /// [`MemoError::InvalidExpression`] error.
     ///
     /// If the group does not exist, returns a [`MemoError::UnknownGroup`] error.
-    async fn add_physical_expression_to_group(
+    ///
+    /// FIXME: This needs to have a mechanism of reporting that a duplicate expression was found in
+    /// another group.
+    async fn add_logical_expression_to_group(
         &self,
         group_id: Self::GroupId,
-        physical_expression: Self::PhysicalExpression,
+        logical_expression: Self::LogicalExpression,
         children: &[Self::GroupId],
     ) -> OptimizerResult<()>;