Add an EXPLAIN option to show the Equivalences Analysis

Author: ggevay

src/repr/src/explain.rs

@@ -170,6 +170,10 @@ pub struct ExplainConfig {
     pub cardinality: bool,
     /// Show the `ColumnNames` Analysis.
     pub column_names: bool,
+    /// Show the `Equivalences` Analysis.
+    pub equivalences: bool,
+    // TODO: add an option to show the `Monotonic` Analysis. This is non-trivial, because this
+    // Analysis needs the set of monotonic GlobalIds, which are cumbersome to pass around.
 
     // Other display options:
     /// Render implemented MIR `Join` nodes in a way which reflects the implementation.
@@ -222,6 +226,7 @@ impl Default for ExplainConfig {
             subtree_size: false,
             timing: false,
             types: false,
+            equivalences: false,
             features: Default::default(),
         }
     }
@@ -236,6 +241,7 @@ impl ExplainConfig {
             || self.keys
             || self.cardinality
             || self.column_names
+            || self.equivalences
     }
 }
 
@@ -629,6 +635,7 @@ pub struct Analyses {
     pub keys: Option<Vec<Vec<usize>>>,
     pub cardinality: Option<String>,
     pub column_names: Option<Vec<String>>,
+    pub equivalences: Option<String>,
 }
 
 #[derive(Debug, Clone)]
@@ -716,6 +723,11 @@ impl<'a> Display for HumanizedAnalyses<'a> {
             builder.field("column_names", &column_names);
         }
 
+        if self.config.equivalences {
+            let equivs = self.analyses.equivalences.as_ref().expect("equivalences");
+            builder.field("equivs", equivs);
+        }
+
         builder.finish()
     }
 }
@@ -938,6 +950,7 @@ mod tests {
             raw_plans: false,
             raw_syntax: false,
             subtree_size: false,
+            equivalences: false,
             timing: true,
             types: false,
             features: Default::default(),

src/sql-lexer/src/keywords.txt

@@ -151,6 +151,7 @@ End
 Endpoint
 Enforced
 Envelope
+Equivalences
 Error
 Errors
 Escape

src/sql-parser/src/ast/defs/statement.rs

@@ -3883,6 +3883,7 @@ pub enum ExplainPlanOptionName {
     SubtreeSize,
     Timing,
     Types,
+    Equivalences,
     ReoptimizeImportedViews,
     EnableNewOuterJoinLowering,
     EnableEagerDeltaJoins,
@@ -3917,6 +3918,7 @@ impl WithOptionName for ExplainPlanOptionName {
             | Self::SubtreeSize
             | Self::Timing
             | Self::Types
+            | Self::Equivalences
             | Self::ReoptimizeImportedViews
             | Self::EnableNewOuterJoinLowering
             | Self::EnableEagerDeltaJoins

src/sql/src/plan/statement/dml.rs

@@ -364,6 +364,7 @@ generate_extracted_config!(
     (SubtreeSize, bool, Default(false)),
     (Timing, bool, Default(false)),
     (Types, bool, Default(false)),
+    (Equivalences, bool, Default(false)),
     (ReoptimizeImportedViews, Option<bool>, Default(None)),
     (EnableNewOuterJoinLowering, Option<bool>, Default(None)),
     (EnableEagerDeltaJoins, Option<bool>, Default(None)),
@@ -406,6 +407,7 @@ impl TryFrom<ExplainPlanOptionExtracted> for ExplainConfig {
             raw_syntax: v.raw_syntax,
             redacted: v.redacted,
             subtree_size: v.subtree_size,
+            equivalences: v.equivalences,
             timing: v.timing,
             types: v.types,
             // The ones that are initialized with `Default::default()` are not wired up to EXPLAIN.

src/transform/src/analysis.rs

@@ -1205,6 +1205,8 @@ mod explain {
     use mz_ore::stack::RecursionLimitError;
     use mz_repr::explain::{Analyses, AnnotatedPlan};
 
+    use crate::analysis::equivalences::Equivalences;
+
     // Analyses should have shortened paths when exported.
     use super::DerivedBuilder;
 
@@ -1234,6 +1236,9 @@ mod explain {
             if context.config.column_names || context.config.humanized_exprs {
                 builder.require(super::ColumnNames);
             }
+            if context.config.equivalences {
+                builder.require(Equivalences);
+            }
             builder
         }
     }
@@ -1333,6 +1338,19 @@ mod explain {
                     analyses.column_names = Some(value);
                 }
             }
+
+            if config.equivalences {
+                for (expr, equivs) in std::iter::zip(
+                    subtree_refs.iter(),
+                    derived.results::<Equivalences>().unwrap().into_iter(),
+                ) {
+                    let analyses = annotations.entry(expr).or_default();
+                    analyses.equivalences = Some(match equivs.as_ref() {
+                        Some(equivs) => equivs.to_string(),
+                        None => "<empty collection>".to_string(),
+                    });
+                }
+            }
         }
 
         Ok(AnnotatedPlan { plan, annotations })

src/transform/src/analysis/equivalences.rs

@@ -16,8 +16,10 @@
 //! equivalences classes, each a list of equivalent expressions.
 
 use std::collections::BTreeMap;
+use std::fmt::Formatter;
 
 use mz_expr::{Id, MirRelationExpr, MirScalarExpr};
+use mz_ore::str::{bracketed, separated};
 use mz_repr::{ColumnType, Datum};
 
 use crate::analysis::{Analysis, Lattice};
@@ -318,7 +320,7 @@ pub struct EquivalenceClasses {
     /// The first element should be the "canonical" simplest element, that any other element
     /// can be replaced by.
     /// These classes are unified whenever possible, to minimize the number of classes.
-    /// They are only guaranteed to form an equivalence relation after a call to `minimimize`,
+    /// They are only guaranteed to form an equivalence relation after a call to `minimize`,
     /// which refreshes both `self.classes` and `self.remap`.
     pub classes: Vec<Vec<MirScalarExpr>>,
 
@@ -334,6 +336,17 @@ pub struct EquivalenceClasses {
     remap: BTreeMap<MirScalarExpr, MirScalarExpr>,
 }
 
+impl std::fmt::Display for EquivalenceClasses {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        // Only show `classes`.
+        let classes = self
+            .classes
+            .iter()
+            .map(|class| format!("{}", bracketed("[", "]", separated(", ", class))));
+        write!(f, "{}", bracketed("[", "]", separated(", ", classes)))
+    }
+}
+
 impl EquivalenceClasses {
     /// Comparator function for the complexity of scalar expressions. Simpler expressions are
     /// smaller. Can be used when we need to decide which of several equivalent expressions to use.

src/transform/tests/test_runner.rs

@@ -141,6 +141,7 @@ mod tests {
                     raw_plans: false,
                     raw_syntax: false,
                     subtree_size: false,
+                    equivalences: false,
                     timing: false,
                     types: format_contains("types"),
                     ..ExplainConfig::default()

test/sqllogictest/explain/optimized_plan_as_text.slt

@@ -1577,3 +1577,42 @@ Source materialize.public.t4
 Target cluster: no_replicas
 
 EOF
+
+statement ok
+CREATE TABLE t5(
+    x int,
+    y int NOT NULL,
+    z int
+);
+
+statement ok
+CREATE TABLE t6(
+    a int NOT NULL,
+    b int
+);
+
+# WITH(EQUIVALENCES)
+query T multiline
+EXPLAIN WITH(EQUIVALENCES)
+SELECT *
+FROM t5, t6
+WHERE x = a AND b IN (8,9);
+----
+Explained Query:
+  Project (#0..=#2, #0, #4) // { equivs: "[[#0, #3], [false, (#0) IS NULL, (#1) IS NULL], [true, ((#4 = 8) OR (#4 = 9))]]" }
+    Join on=(#0 = #3) type=differential // { equivs: "[[#0, #3], [false, (#0) IS NULL, (#1) IS NULL], [true, ((#4 = 8) OR (#4 = 9))]]" }
+      ArrangeBy keys=[[#0]] // { equivs: "[[false, (#0) IS NULL, (#1) IS NULL]]" }
+        Filter (#0) IS NOT NULL // { equivs: "[[false, (#0) IS NULL, (#1) IS NULL]]" }
+          ReadStorage materialize.public.t5 // { equivs: "[[false, (#1) IS NULL]]" }
+      ArrangeBy keys=[[#0]] // { equivs: "[[false, (#0) IS NULL], [true, ((#1 = 8) OR (#1 = 9))]]" }
+        Filter ((#1 = 8) OR (#1 = 9)) // { equivs: "[[false, (#0) IS NULL], [true, ((#1 = 8) OR (#1 = 9))]]" }
+          ReadStorage materialize.public.t6 // { equivs: "[[false, (#0) IS NULL]]" }
+
+Source materialize.public.t5
+  filter=((#0) IS NOT NULL)
+Source materialize.public.t6
+  filter=(((#1 = 8) OR (#1 = 9)))
+
+Target cluster: no_replicas
+
+EOF