Skip to main content

vortex_array/expr/
display.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::fmt;
5use std::fmt::Display;
6use std::fmt::Formatter;
7
8use vortex_utils::tree::TreeDisplayAdapter;
9use vortex_utils::tree::write_branch_tree;
10
11use crate::expr::BoundExpression;
12use crate::expr::Expression;
13use crate::scalar_fn::ChildName;
14
15pub enum DisplayFormat {
16    Compact,
17    Tree,
18}
19
20/// Read-only expression-tree interface used by scalar functions for SQL-style formatting.
21///
22/// Both [`Expression`] and [`BoundExpression`] implement this interface, allowing scalar
23/// functions to format either representation without converting between them.
24pub trait ExprDisplay: Display {
25    /// Return the child at `index`.
26    fn display_child(&self, index: usize) -> &dyn ExprDisplay;
27
28    /// Return the number of children in this node.
29    fn display_children_count(&self) -> usize;
30}
31
32impl ExprDisplay for Expression {
33    fn display_child(&self, index: usize) -> &dyn ExprDisplay {
34        Expression::child(self, index)
35    }
36
37    fn display_children_count(&self) -> usize {
38        self.children().len()
39    }
40}
41
42impl ExprDisplay for BoundExpression {
43    fn display_child(&self, index: usize) -> &dyn ExprDisplay {
44        &self.children()[index]
45    }
46
47    fn display_children_count(&self) -> usize {
48        self.children().len()
49    }
50}
51
52trait DisplayTreeNode: Sized {
53    fn tree_children(&self) -> &[Self];
54
55    fn tree_child_name(&self, index: usize) -> ChildName;
56
57    fn fmt_tree_node(&self, f: &mut Formatter<'_>) -> fmt::Result;
58}
59
60/// Tree-display label for the scope root.
61const ROOT_DISPLAY: &str = "vortex.root()";
62
63impl DisplayTreeNode for Expression {
64    fn tree_children(&self) -> &[Self] {
65        Expression::children(self)
66    }
67
68    fn tree_child_name(&self, index: usize) -> ChildName {
69        match self {
70            Expression::Scalar { scalar_fn, .. } => scalar_fn.signature().child_name(index),
71            Expression::Root => unreachable!("the scope root has no children"),
72            Expression::Variable(_) => unreachable!("a variable has no children"),
73        }
74    }
75
76    fn fmt_tree_node(&self, f: &mut Formatter<'_>) -> fmt::Result {
77        match self {
78            Expression::Scalar { scalar_fn, .. } => Display::fmt(scalar_fn, f),
79            Expression::Root => write!(f, "{ROOT_DISPLAY}"),
80            Expression::Variable(name) => write!(f, "@{name}"),
81        }
82    }
83}
84
85impl DisplayTreeNode for BoundExpression {
86    fn tree_children(&self) -> &[Self] {
87        BoundExpression::children(self)
88    }
89
90    fn tree_child_name(&self, index: usize) -> ChildName {
91        match self {
92            BoundExpression::Scalar { scalar_fn, .. } => scalar_fn.signature().child_name(index),
93            BoundExpression::Root { .. } => unreachable!("the scope root has no children"),
94        }
95    }
96
97    fn fmt_tree_node(&self, f: &mut Formatter<'_>) -> fmt::Result {
98        match self {
99            BoundExpression::Scalar { scalar_fn, .. } => Display::fmt(scalar_fn, f),
100            BoundExpression::Root { .. } => write!(f, "{ROOT_DISPLAY}"),
101        }
102    }
103}
104
105pub struct DisplayTreeExpr<'a, T: ?Sized = Expression>(pub &'a T);
106
107impl<T: DisplayTreeNode> TreeDisplayAdapter for DisplayTreeExpr<'_, T> {
108    type Context = ();
109    type Node = T;
110
111    fn write_node(
112        &self,
113        node: &Self::Node,
114        _context: &Self::Context,
115        formatter: &mut Formatter<'_>,
116    ) -> fmt::Result {
117        node.fmt_tree_node(formatter)
118    }
119
120    fn visit_children(
121        &self,
122        node: &Self::Node,
123        visit: &mut dyn FnMut(&str, &Self::Node, bool) -> fmt::Result,
124    ) -> fmt::Result {
125        let children = node.tree_children();
126        for (index, child) in children.iter().enumerate() {
127            let child_name = node.tree_child_name(index);
128            visit(child_name.as_ref(), child, index + 1 == children.len())?;
129        }
130        Ok(())
131    }
132}
133
134impl<T: DisplayTreeNode> Display for DisplayTreeExpr<'_, T> {
135    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
136        write_branch_tree(self, self.0, &mut (), f)
137    }
138}
139
140#[cfg(test)]
141mod tests {
142    use crate::dtype::DType;
143    use crate::dtype::Nullability;
144    use crate::dtype::PType;
145    use crate::expr::and;
146    use crate::expr::between;
147    use crate::expr::cast;
148    use crate::expr::eq;
149    use crate::expr::get_item;
150    use crate::expr::gt;
151    use crate::expr::lit;
152    use crate::expr::not;
153    use crate::expr::pack;
154    use crate::expr::root;
155    use crate::expr::select;
156    use crate::expr::select_exclude;
157    use crate::scalar_fn::fns::between::BetweenOptions;
158    use crate::scalar_fn::fns::between::StrictComparison;
159
160    #[test]
161    fn test_display_tree_root() {
162        use insta::assert_snapshot;
163        let root_expr = root();
164        assert_snapshot!(root_expr.display_tree().to_string(), @"vortex.root()");
165    }
166
167    #[test]
168    fn test_display_tree_literal() {
169        use insta::assert_snapshot;
170        let lit_expr = lit(42);
171        assert_snapshot!(lit_expr.display_tree().to_string(), @"vortex.literal(42i32)");
172    }
173
174    #[test]
175    fn test_display_tree_get_item() {
176        use insta::assert_snapshot;
177        let get_item_expr = get_item("my_field", root());
178        assert_snapshot!(get_item_expr.display_tree().to_string(), @r"
179        vortex.get_item(my_field)
180        └── input: vortex.root()
181        ");
182    }
183
184    #[test]
185    fn test_display_tree_binary() {
186        use insta::assert_snapshot;
187        let binary_expr = gt(get_item("x", root()), lit(10));
188        assert_snapshot!(binary_expr.display_tree().to_string(), @r"
189        vortex.binary(>)
190        ├── lhs: vortex.get_item(x)
191        │   └── input: vortex.root()
192        └── rhs: vortex.literal(10i32)
193        ");
194    }
195
196    #[test]
197    fn test_display_tree_complex_binary() {
198        use insta::assert_snapshot;
199        let complex_binary = and(
200            eq(get_item("name", root()), lit("alice")),
201            gt(get_item("age", root()), lit(18)),
202        );
203        assert_snapshot!(complex_binary.display_tree().to_string(), @r#"
204        vortex.binary(and)
205        ├── lhs: vortex.binary(=)
206        │   ├── lhs: vortex.get_item(name)
207        │   │   └── input: vortex.root()
208        │   └── rhs: vortex.literal("alice")
209        └── rhs: vortex.binary(>)
210            ├── lhs: vortex.get_item(age)
211            │   └── input: vortex.root()
212            └── rhs: vortex.literal(18i32)
213        "#);
214    }
215
216    #[test]
217    fn test_display_tree_select() {
218        use insta::assert_snapshot;
219        let select_expr = select(["name", "age"], root());
220        assert_snapshot!(select_expr.display_tree().to_string(), @r"
221        vortex.select({name, age})
222        └── child: vortex.root()
223        ");
224    }
225
226    #[test]
227    fn test_display_tree_select_exclude() {
228        use insta::assert_snapshot;
229        let select_exclude_expr = select_exclude(["internal_id", "metadata"], root());
230        assert_snapshot!(select_exclude_expr.display_tree().to_string(), @r"
231        vortex.select(~{internal_id, metadata})
232        └── child: vortex.root()
233        ");
234    }
235
236    #[test]
237    fn test_display_tree_cast() {
238        use insta::assert_snapshot;
239        let cast_expr = cast(
240            get_item("value", root()),
241            DType::Primitive(PType::I64, Nullability::NonNullable),
242        );
243        assert_snapshot!(cast_expr.display_tree().to_string(), @r"
244        vortex.cast(i64)
245        └── input: vortex.get_item(value)
246            └── input: vortex.root()
247        ");
248    }
249
250    #[test]
251    fn test_display_tree_not() {
252        use insta::assert_snapshot;
253        let not_expr = not(eq(get_item("active", root()), lit(true)));
254        assert_snapshot!(not_expr.display_tree().to_string(), @r"
255        vortex.not()
256        └── input: vortex.binary(=)
257            ├── lhs: vortex.get_item(active)
258            │   └── input: vortex.root()
259            └── rhs: vortex.literal(true)
260        ");
261    }
262
263    #[test]
264    fn test_display_tree_between() {
265        use insta::assert_snapshot;
266        let between_expr = between(
267            get_item("score", root()),
268            lit(0),
269            lit(100),
270            BetweenOptions {
271                lower_strict: StrictComparison::NonStrict,
272                upper_strict: StrictComparison::NonStrict,
273            },
274        );
275        assert_snapshot!(between_expr.display_tree().to_string(), @r"
276        vortex.between(lower_strict: <=, upper_strict: <=)
277        ├── array: vortex.get_item(score)
278        │   └── input: vortex.root()
279        ├── lower: vortex.literal(0i32)
280        └── upper: vortex.literal(100i32)
281        ");
282    }
283
284    #[test]
285    fn test_display_tree_nested() {
286        use insta::assert_snapshot;
287        let nested_expr = select(
288            ["result"],
289            cast(
290                between(
291                    get_item("score", root()),
292                    lit(50),
293                    lit(100),
294                    BetweenOptions {
295                        lower_strict: StrictComparison::Strict,
296                        upper_strict: StrictComparison::NonStrict,
297                    },
298                ),
299                DType::Bool(Nullability::NonNullable),
300            ),
301        );
302        assert_snapshot!(nested_expr.display_tree().to_string(), @r"
303        vortex.select({result})
304        └── child: vortex.cast(bool)
305            └── input: vortex.between(lower_strict: <, upper_strict: <=)
306                ├── array: vortex.get_item(score)
307                │   └── input: vortex.root()
308                ├── lower: vortex.literal(50i32)
309                └── upper: vortex.literal(100i32)
310        ");
311    }
312
313    #[test]
314    fn test_display_tree_pack() {
315        use insta::assert_snapshot;
316        let select_from_pack_expr = select(
317            ["fizz", "buzz"],
318            pack(
319                [
320                    ("fizz", root()),
321                    ("bar", lit(5)),
322                    ("buzz", eq(lit(42), get_item("answer", root()))),
323                ],
324                Nullability::Nullable,
325            ),
326        );
327        assert_snapshot!(select_from_pack_expr.display_tree().to_string(), @r"
328        vortex.select({fizz, buzz})
329        └── child: vortex.pack(names: [fizz, bar, buzz], nullability: Nullable)
330            ├── fizz: vortex.root()
331            ├── bar: vortex.literal(5i32)
332            └── buzz: vortex.binary(=)
333                ├── lhs: vortex.literal(42i32)
334                └── rhs: vortex.get_item(answer)
335                    └── input: vortex.root()
336        ");
337    }
338}