vortex_array/display/mod.rs
1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4mod extractor;
5mod extractors;
6mod tree_display;
7
8use std::fmt::Display;
9use std::iter::repeat_n;
10
11pub use extractor::IndentedFormatter;
12pub use extractor::TreeContext;
13pub use extractor::TreeExtractor;
14pub use extractors::BufferExtractor;
15pub use extractors::EncodingSummaryExtractor;
16pub use extractors::MetadataExtractor;
17pub use extractors::NbytesExtractor;
18pub use extractors::StatsExtractor;
19use itertools::Itertools as _;
20pub use tree_display::TreeDisplay;
21
22use crate::ArrayRef;
23use crate::ExecutionCtx;
24
25/// Describe how to convert an array to a string.
26///
27/// See also:
28/// [Array::display_as](../trait.Array.html#method.display_as)
29/// and [DisplayArrayAs].
30pub enum DisplayOptions {
31 /// Only the top-level encoding id and limited metadata: `vortex.primitive(i16, len=5)`.
32 ///
33 /// ```
34 /// # use vortex_session::VortexSession;
35 /// # use vortex_array::VortexSessionExecute;
36 /// # let ctx = VortexSession::empty().create_execution_ctx();
37 /// # use vortex_array::display::DisplayOptions;
38 /// # use vortex_array::IntoArray;
39 /// # use vortex_buffer::buffer;
40 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
41 /// assert_eq!(
42 /// format!("{}", array.display_as(DisplayOptions::MetadataOnly, &ctx)),
43 /// "vortex.primitive(i16, len=5)",
44 /// );
45 /// ```
46 MetadataOnly,
47 /// Only the logical values of the array: `[0i16, 1i16, 2i16, 3i16, 4i16]`.
48 ///
49 /// ```
50 /// # use vortex_session::VortexSession;
51 /// # use vortex_array::VortexSessionExecute;
52 /// # let ctx = VortexSession::empty().create_execution_ctx();
53 /// # use vortex_array::display::DisplayOptions;
54 /// # use vortex_array::IntoArray;
55 /// # use vortex_buffer::buffer;
56 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
57 /// assert_eq!(
58 /// format!("{}", array.display_as(DisplayOptions::default(), &ctx)),
59 /// "[0i16, 1i16, 2i16, 3i16, 4i16]",
60 /// );
61 /// assert_eq!(
62 /// format!("{}", array.display_as(DisplayOptions::default(), &ctx)),
63 /// format!("{}", array.display_values(&ctx)),
64 /// );
65 /// ```
66 CommaSeparatedScalars { omit_comma_after_space: bool },
67 /// The tree of encodings without any concrete values.
68 ///
69 /// With buffers, metadata, and stats:
70 ///
71 /// ```
72 /// # use vortex_session::VortexSession;
73 /// # use vortex_array::VortexSessionExecute;
74 /// # let ctx = VortexSession::empty().create_execution_ctx();
75 /// # use vortex_array::display::DisplayOptions;
76 /// # use vortex_array::IntoArray;
77 /// # use vortex_buffer::buffer;
78 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
79 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
80 /// metadata: ptype: i16
81 /// buffer: values host 10 B (align=2) (100.00%)
82 /// ";
83 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: true }, &ctx)), expected);
84 ///
85 /// # use vortex_array::arrays::StructArray;
86 /// let array = StructArray::from_fields(&[
87 /// ("x", buffer![1, 2].into_array()),
88 /// ("y", buffer![3, 4].into_array()),
89 /// ]).unwrap().into_array();
90 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
91 /// metadata:\x20
92 /// x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
93 /// metadata: ptype: i32
94 /// buffer: values host 8 B (align=4) (100.00%)
95 /// y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
96 /// metadata: ptype: i32
97 /// buffer: values host 8 B (align=4) (100.00%)
98 /// ";
99 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: true }, &ctx)), expected);
100 /// ```
101 ///
102 /// With metadata and stats but no buffers:
103 ///
104 /// ```
105 /// # use vortex_session::VortexSession;
106 /// # use vortex_array::VortexSessionExecute;
107 /// # let ctx = VortexSession::empty().create_execution_ctx();
108 /// # use vortex_array::display::DisplayOptions;
109 /// # use vortex_array::IntoArray;
110 /// # use vortex_buffer::buffer;
111 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
112 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
113 /// metadata: ptype: i16
114 /// ";
115 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: true }, &ctx)), expected);
116 ///
117 /// # use vortex_array::arrays::StructArray;
118 /// let array = StructArray::from_fields(&[
119 /// ("x", buffer![1, 2].into_array()),
120 /// ("y", buffer![3, 4].into_array()),
121 /// ]).unwrap().into_array();
122 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
123 /// metadata:\x20
124 /// x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
125 /// metadata: ptype: i32
126 /// y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
127 /// metadata: ptype: i32
128 /// ";
129 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: true }, &ctx)), expected);
130 /// ```
131 ///
132 /// With metadata and buffers but no stats:
133 ///
134 /// ```
135 /// # use vortex_session::VortexSession;
136 /// # use vortex_array::VortexSessionExecute;
137 /// # let ctx = VortexSession::empty().create_execution_ctx();
138 /// # use vortex_array::display::DisplayOptions;
139 /// # use vortex_array::IntoArray;
140 /// # use vortex_buffer::buffer;
141 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
142 /// let expected = "root: vortex.primitive(i16, len=5)
143 /// metadata: ptype: i16
144 /// buffer: values host 10 B (align=2)
145 /// ";
146 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: false }, &ctx)), expected);
147 ///
148 /// # use vortex_array::arrays::StructArray;
149 /// let array = StructArray::from_fields(&[
150 /// ("x", buffer![1, 2].into_array()),
151 /// ("y", buffer![3, 4].into_array()),
152 /// ]).unwrap().into_array();
153 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
154 /// metadata:\x20
155 /// x: vortex.primitive(i32, len=2)
156 /// metadata: ptype: i32
157 /// buffer: values host 8 B (align=4)
158 /// y: vortex.primitive(i32, len=2)
159 /// metadata: ptype: i32
160 /// buffer: values host 8 B (align=4)
161 /// ";
162 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: false }, &ctx)), expected);
163 /// ```
164 ///
165 /// With buffers and stats but no metadata:
166 ///
167 /// ```
168 /// # use vortex_session::VortexSession;
169 /// # use vortex_array::VortexSessionExecute;
170 /// # let ctx = VortexSession::empty().create_execution_ctx();
171 /// # use vortex_array::display::DisplayOptions;
172 /// # use vortex_array::IntoArray;
173 /// # use vortex_buffer::buffer;
174 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
175 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
176 /// buffer: values host 10 B (align=2) (100.00%)
177 /// ";
178 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: true }, &ctx)), expected);
179 ///
180 /// # use vortex_array::arrays::StructArray;
181 /// let array = StructArray::from_fields(&[
182 /// ("x", buffer![1, 2].into_array()),
183 /// ("y", buffer![3, 4].into_array()),
184 /// ]).unwrap().into_array();
185 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
186 /// x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
187 /// buffer: values host 8 B (align=4) (100.00%)
188 /// y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
189 /// buffer: values host 8 B (align=4) (100.00%)
190 /// ";
191 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: true }, &ctx)), expected);
192 /// ```
193 ///
194 /// With just buffers:
195 ///
196 /// ```
197 /// # use vortex_session::VortexSession;
198 /// # use vortex_array::VortexSessionExecute;
199 /// # let ctx = VortexSession::empty().create_execution_ctx();
200 /// # use vortex_array::display::DisplayOptions;
201 /// # use vortex_array::IntoArray;
202 /// # use vortex_buffer::buffer;
203 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
204 /// let expected = "root: vortex.primitive(i16, len=5)
205 /// buffer: values host 10 B (align=2)
206 /// ";
207 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: false }, &ctx)), expected);
208 ///
209 /// # use vortex_array::arrays::StructArray;
210 /// let array = StructArray::from_fields(&[
211 /// ("x", buffer![1, 2].into_array()),
212 /// ("y", buffer![3, 4].into_array()),
213 /// ]).unwrap().into_array();
214 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
215 /// x: vortex.primitive(i32, len=2)
216 /// buffer: values host 8 B (align=4)
217 /// y: vortex.primitive(i32, len=2)
218 /// buffer: values host 8 B (align=4)
219 /// ";
220 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: false }, &ctx)), expected);
221 /// ```
222 ///
223 /// With just metadata:
224 ///
225 /// ```
226 /// # use vortex_session::VortexSession;
227 /// # use vortex_array::VortexSessionExecute;
228 /// # let ctx = VortexSession::empty().create_execution_ctx();
229 /// # use vortex_array::display::DisplayOptions;
230 /// # use vortex_array::IntoArray;
231 /// # use vortex_buffer::buffer;
232 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
233 /// let expected = "root: vortex.primitive(i16, len=5)
234 /// metadata: ptype: i16
235 /// ";
236 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: false }, &ctx)), expected);
237 ///
238 /// # use vortex_array::arrays::StructArray;
239 /// let array = StructArray::from_fields(&[
240 /// ("x", buffer![1, 2].into_array()),
241 /// ("y", buffer![3, 4].into_array()),
242 /// ]).unwrap().into_array();
243 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
244 /// metadata:\x20
245 /// x: vortex.primitive(i32, len=2)
246 /// metadata: ptype: i32
247 /// y: vortex.primitive(i32, len=2)
248 /// metadata: ptype: i32
249 /// ";
250 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: false }, &ctx)), expected);
251 /// ```
252 ///
253 /// With just stats:
254 ///
255 /// ```
256 /// # use vortex_session::VortexSession;
257 /// # use vortex_array::VortexSessionExecute;
258 /// # let ctx = VortexSession::empty().create_execution_ctx();
259 /// # use vortex_array::display::DisplayOptions;
260 /// # use vortex_array::IntoArray;
261 /// # use vortex_buffer::buffer;
262 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
263 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
264 /// ";
265 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: true }, &ctx)), expected);
266 ///
267 /// # use vortex_array::arrays::StructArray;
268 /// let array = StructArray::from_fields(&[
269 /// ("x", buffer![1, 2].into_array()),
270 /// ("y", buffer![3, 4].into_array()),
271 /// ]).unwrap().into_array();
272 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
273 /// x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
274 /// y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
275 /// ";
276 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: true }, &ctx)), expected);
277 /// ```
278 ///
279 /// With neither buffers, metadata, stats, nor values:
280 ///
281 /// ```
282 /// # use vortex_session::VortexSession;
283 /// # use vortex_array::VortexSessionExecute;
284 /// # let ctx = VortexSession::empty().create_execution_ctx();
285 /// # use vortex_array::display::DisplayOptions;
286 /// # use vortex_array::IntoArray;
287 /// # use vortex_buffer::buffer;
288 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
289 /// let expected = "root: vortex.primitive(i16, len=5)\n";
290 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: false }, &ctx)), expected);
291 ///
292 /// # use vortex_array::arrays::StructArray;
293 /// let array = StructArray::from_fields(&[
294 /// ("x", buffer![1, 2].into_array()),
295 /// ("y", buffer![3, 4].into_array()),
296 /// ]).unwrap().into_array();
297 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
298 /// x: vortex.primitive(i32, len=2)
299 /// y: vortex.primitive(i32, len=2)
300 /// ";
301 /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: false }, &ctx)), expected);
302 /// ```
303 TreeDisplay {
304 buffers: bool,
305 metadata: bool,
306 stats: bool,
307 },
308 /// Display values in a formatted table with columns.
309 ///
310 /// For struct arrays, displays a column for each field in the struct.
311 /// For regular arrays, displays a single column with values.
312 ///
313 /// ```
314 /// # use vortex_session::VortexSession;
315 /// # use vortex_array::VortexSessionExecute;
316 /// # let ctx = VortexSession::empty().create_execution_ctx();
317 /// # use vortex_array::display::DisplayOptions;
318 /// # use vortex_array::arrays::StructArray;
319 /// # use vortex_array::IntoArray;
320 /// # use vortex_buffer::buffer;
321 /// let s = StructArray::from_fields(&[
322 /// ("x", buffer![1, 2].into_array()),
323 /// ("y", buffer![3, 4].into_array()),
324 /// ]).unwrap().into_array();
325 /// let expected = "
326 /// ┌──────┬──────┐
327 /// │ x │ y │
328 /// ├──────┼──────┤
329 /// │ 1i32 │ 3i32 │
330 /// ├──────┼──────┤
331 /// │ 2i32 │ 4i32 │
332 /// └──────┴──────┘".trim();
333 /// assert_eq!(format!("{}", s.display_as(DisplayOptions::TableDisplay, &ctx)), expected);
334 /// ```
335 #[cfg(feature = "table-display")]
336 TableDisplay,
337}
338
339impl Default for DisplayOptions {
340 fn default() -> Self {
341 Self::CommaSeparatedScalars {
342 omit_comma_after_space: false,
343 }
344 }
345}
346
347/// A shim used to display an array as specified in the options.
348///
349/// Values are read with a clone of the execution context, made each time the array is formatted.
350///
351/// See also:
352/// [Array::display_as](../trait.Array.html#method.display_as)
353/// and [DisplayOptions].
354pub struct DisplayArrayAs<'a> {
355 array: &'a ArrayRef,
356 options: DisplayOptions,
357 ctx: &'a ExecutionCtx,
358}
359
360impl<'a> DisplayArrayAs<'a> {
361 /// Display `array` as specified by `options`, reading values with `ctx`.
362 pub fn new(array: &'a ArrayRef, options: DisplayOptions, ctx: &'a ExecutionCtx) -> Self {
363 Self {
364 array,
365 options,
366 ctx,
367 }
368 }
369}
370
371impl Display for DisplayArrayAs<'_> {
372 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
373 self.array.fmt_as(f, &self.options, &mut self.ctx.clone())
374 }
375}
376
377/// Display the encoding and limited metadata of this array.
378///
379/// # Examples
380/// ```
381/// # use vortex_array::IntoArray;
382/// # use vortex_buffer::buffer;
383/// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
384/// assert_eq!(
385/// format!("{}", array),
386/// "vortex.primitive(i16, len=5)",
387/// );
388/// ```
389impl Display for ArrayRef {
390 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
391 EncodingSummaryExtractor::write(self, f)
392 }
393}
394
395const DISPLAY_LIMIT: usize = 16;
396impl ArrayRef {
397 /// Display logical values of the array
398 ///
399 /// For example, an `i16` typed array containing the first five non-negative integers is displayed
400 /// as: `[0i16, 1i16, 2i16, 3i16, 4i16]`.
401 ///
402 /// # Examples
403 ///
404 /// ```
405 /// # use vortex_session::VortexSession;
406 /// # use vortex_array::VortexSessionExecute;
407 /// # let ctx = VortexSession::empty().create_execution_ctx();
408 /// # use vortex_array::IntoArray;
409 /// # use vortex_buffer::buffer;
410 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
411 /// assert_eq!(
412 /// format!("{}", array.display_values(&ctx)),
413 /// "[0i16, 1i16, 2i16, 3i16, 4i16]",
414 /// )
415 /// ```
416 ///
417 /// See also:
418 /// [Array::display_as](..//trait.Array.html#method.display_as),
419 /// [DisplayArrayAs], and [DisplayOptions].
420 pub fn display_values<'a>(&'a self, ctx: &'a ExecutionCtx) -> DisplayArrayAs<'a> {
421 DisplayArrayAs::new(
422 self,
423 DisplayOptions::CommaSeparatedScalars {
424 omit_comma_after_space: false,
425 },
426 ctx,
427 )
428 }
429
430 /// Display the array as specified by the options, reading values with `ctx`.
431 ///
432 /// See [DisplayOptions] for examples.
433 pub fn display_as<'a>(
434 &'a self,
435 options: DisplayOptions,
436 ctx: &'a ExecutionCtx,
437 ) -> DisplayArrayAs<'a> {
438 DisplayArrayAs::new(self, options, ctx)
439 }
440
441 /// Display the tree of array encodings and lengths without metadata, buffers, or stats.
442 ///
443 /// # Examples
444 /// ```
445 /// # use vortex_array::display::DisplayOptions;
446 /// # use vortex_array::IntoArray;
447 /// # use vortex_buffer::buffer;
448 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
449 /// let expected = "root: vortex.primitive(i16, len=5)\n";
450 /// assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);
451 ///
452 /// # use vortex_array::arrays::StructArray;
453 /// let array = StructArray::from_fields(&[
454 /// ("x", buffer![1, 2].into_array()),
455 /// ("y", buffer![3, 4].into_array()),
456 /// ]).unwrap().into_array();
457 /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
458 /// x: vortex.primitive(i32, len=2)
459 /// y: vortex.primitive(i32, len=2)
460 /// ";
461 /// assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);
462 /// ```
463 pub fn display_tree_encodings_only(&self) -> TreeDisplay {
464 self.tree_display_builder().with(EncodingSummaryExtractor)
465 }
466
467 /// Display the tree of encodings of this array as an indented lists.
468 ///
469 /// While some metadata (such as length, bytes and validity-rate) are included, the logical
470 /// values of the array are not displayed. To view the logical values see
471 /// [Array::display_as](../trait.Array.html#method.display_as)
472 /// and [DisplayOptions].
473 ///
474 /// # Examples
475 /// ```
476 /// # use vortex_array::display::DisplayOptions;
477 /// # use vortex_array::IntoArray;
478 /// # use vortex_buffer::buffer;
479 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
480 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
481 /// metadata: ptype: i16
482 /// buffer: values host 10 B (align=2) (100.00%)
483 /// ";
484 /// assert_eq!(format!("{}", array.display_tree()), expected);
485 /// ```
486 pub fn display_tree(&self) -> TreeDisplay {
487 TreeDisplay::default_display(self.clone())
488 }
489
490 /// Create a tree display with all built-in extractors (nbytes, stats, metadata, buffers).
491 ///
492 /// This is the default, fully-detailed tree display. Use
493 /// `tree_display_builder()` for a blank slate.
494 ///
495 /// # Examples
496 /// ```
497 /// # use vortex_array::IntoArray;
498 /// # use vortex_buffer::buffer;
499 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
500 /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
501 /// metadata: ptype: i16
502 /// buffer: values host 10 B (align=2) (100.00%)
503 /// ";
504 /// assert_eq!(array.tree_display().to_string(), expected);
505 /// ```
506 pub fn tree_display(&self) -> TreeDisplay {
507 TreeDisplay::default_display(self.clone())
508 }
509
510 /// Create a composable tree display builder with no extractors.
511 ///
512 /// With no extractors, only the node names are shown.
513 /// Add extractors with [`.with()`][TreeDisplay::with] to include additional information.
514 /// Most builders should start with [`EncodingSummaryExtractor`] to include encoding headers.
515 ///
516 /// # Examples
517 /// ```
518 /// # use vortex_array::IntoArray;
519 /// # use vortex_buffer::buffer;
520 /// use vortex_array::display::{EncodingSummaryExtractor, NbytesExtractor, MetadataExtractor, BufferExtractor};
521 ///
522 /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
523 ///
524 /// // Encodings only
525 /// let encodings = array.tree_display_builder()
526 /// .with(EncodingSummaryExtractor)
527 /// .to_string();
528 /// assert_eq!(encodings, "root: vortex.primitive(i16, len=5)\n");
529 ///
530 /// // With encoding + nbytes
531 /// let with_nbytes = array.tree_display_builder()
532 /// .with(EncodingSummaryExtractor)
533 /// .with(NbytesExtractor)
534 /// .to_string();
535 /// assert_eq!(with_nbytes, "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)\n");
536 ///
537 /// // With encoding, metadata, and buffers
538 /// let detailed = array.tree_display_builder()
539 /// .with(EncodingSummaryExtractor)
540 /// .with(MetadataExtractor)
541 /// .with(BufferExtractor { show_percent: false })
542 /// .to_string();
543 /// let expected = "root: vortex.primitive(i16, len=5)\n metadata: ptype: i16\n buffer: values host 10 B (align=2)\n";
544 /// assert_eq!(detailed, expected);
545 /// ```
546 pub fn tree_display_builder(&self) -> TreeDisplay {
547 TreeDisplay::new(self.clone())
548 }
549
550 /// Display the array as a formatted table.
551 ///
552 /// For struct arrays, displays a column for each field in the struct.
553 /// For regular arrays, displays a single column with values.
554 ///
555 /// # Examples
556 /// ```
557 /// # use vortex_session::VortexSession;
558 /// # use vortex_array::VortexSessionExecute;
559 /// # let ctx = VortexSession::empty().create_execution_ctx();
560 /// # #[cfg(feature = "table-display")]
561 /// # {
562 /// # use vortex_array::arrays::StructArray;
563 /// # use vortex_array::IntoArray;
564 /// # use vortex_buffer::buffer;
565 /// let s = StructArray::from_fields(&[
566 /// ("x", buffer![1, 2].into_array()),
567 /// ("y", buffer![3, 4].into_array()),
568 /// ]).unwrap().into_array();
569 /// let expected = "
570 /// ┌──────┬──────┐
571 /// │ x │ y │
572 /// ├──────┼──────┤
573 /// │ 1i32 │ 3i32 │
574 /// ├──────┼──────┤
575 /// │ 2i32 │ 4i32 │
576 /// └──────┴──────┘".trim();
577 /// assert_eq!(format!("{}", s.display_table(&ctx)), expected);
578 /// # }
579 /// ```
580 #[cfg(feature = "table-display")]
581 pub fn display_table<'a>(&'a self, ctx: &'a ExecutionCtx) -> DisplayArrayAs<'a> {
582 DisplayArrayAs::new(self, DisplayOptions::TableDisplay, ctx)
583 }
584
585 fn fmt_as(
586 &self,
587 f: &mut std::fmt::Formatter,
588 options: &DisplayOptions,
589 ctx: &mut ExecutionCtx,
590 ) -> std::fmt::Result {
591 match options {
592 DisplayOptions::MetadataOnly => EncodingSummaryExtractor::write(self, f),
593 DisplayOptions::CommaSeparatedScalars {
594 omit_comma_after_space,
595 } => {
596 let opening_brace = if f.alternate() { "[\n" } else { "[" };
597 let closing_brace = if f.alternate() { "\n]" } else { "]" };
598
599 let sep = if *omit_comma_after_space { "," } else { ", " };
600 let sep = if f.alternate() { ",\n" } else { sep };
601 let limit = self.len().min(f.precision().unwrap_or(DISPLAY_LIMIT));
602 let is_truncated = self.len() > limit;
603
604 let mut fmt_scalar = |i| {
605 self.execute_scalar(i, ctx)
606 .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string())
607 };
608 let head = (0..limit.saturating_sub(3))
609 .map(&mut fmt_scalar)
610 .collect::<Vec<_>>();
611 let tail = (self.len().saturating_sub(3)..self.len())
612 .map(&mut fmt_scalar)
613 .collect::<Vec<_>>();
614 write!(
615 f,
616 "{opening_brace}{}{closing_brace}",
617 head.into_iter()
618 .chain(repeat_n("...".to_string(), is_truncated as usize))
619 .chain(tail)
620 .format(sep)
621 )
622 }
623 DisplayOptions::TreeDisplay {
624 buffers,
625 metadata,
626 stats,
627 } => {
628 let extractors: [(bool, Box<dyn TreeExtractor<ArrayRef, TreeContext>>); 5] = [
629 (true, Box::new(EncodingSummaryExtractor)),
630 (*stats, Box::new(NbytesExtractor)),
631 (*stats, Box::new(StatsExtractor)),
632 (*metadata, Box::new(MetadataExtractor)),
633 (
634 *buffers,
635 Box::new(BufferExtractor {
636 show_percent: *stats,
637 }),
638 ),
639 ];
640 let mut display = TreeDisplay::new(self.clone());
641 for (enabled, extractor) in extractors {
642 if enabled {
643 display = display.with_boxed(extractor);
644 }
645 }
646 write!(f, "{display}")
647 }
648 #[cfg(feature = "table-display")]
649 DisplayOptions::TableDisplay => {
650 use vortex_mask::Mask;
651
652 use crate::arrays::StructArray;
653 use crate::arrays::struct_::StructArrayExt;
654 use crate::dtype::DType;
655
656 let mut builder = tabled::builder::Builder::default();
657
658 // Special logic for struct arrays.
659 let DType::Struct(sf, _) = self.dtype() else {
660 // For non-struct arrays, simply display a single column table without header.
661 for row_idx in 0..self.len() {
662 let value = self
663 .execute_scalar(row_idx, ctx)
664 .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string());
665 builder.push_record([value]);
666 }
667
668 let mut table = builder.build();
669 table.with(tabled::settings::Style::modern());
670
671 return write!(f, "{table}");
672 };
673
674 let struct_ = match self.clone().execute::<StructArray>(ctx) {
675 Ok(struct_) => struct_,
676 Err(e) => return write!(f, "<error: {e}>"),
677 };
678 builder.push_record(sf.names().iter().map(|name| name.to_string()));
679
680 // Resolve validity to a mask once instead of probing it per row.
681 let validity = self
682 .validity()
683 .and_then(|v| v.execute_mask(self.len(), ctx))
684 .unwrap_or_else(|_| Mask::new_false(self.len()));
685
686 for row_idx in 0..self.len() {
687 if !validity.value(row_idx) {
688 let null_row = vec!["null".to_string(); sf.names().len()];
689 builder.push_record(null_row);
690 } else {
691 let mut row = Vec::with_capacity(struct_.struct_fields().nfields());
692 for field_array in StructArrayExt::iter_unmasked_fields(&struct_) {
693 let value = field_array
694 .execute_scalar(row_idx, ctx)
695 .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string());
696 row.push(value);
697 }
698 builder.push_record(row);
699 }
700 }
701
702 let mut table = builder.build();
703 table.with(tabled::settings::Style::modern());
704
705 // Center headers
706 for col_idx in 0..sf.names().len() {
707 table.modify((0, col_idx), tabled::settings::Alignment::center());
708 }
709
710 for row_idx in 0..self.len() {
711 if !validity.value(row_idx) {
712 table.modify(
713 (1 + row_idx, 0),
714 tabled::settings::Span::column(sf.names().len() as isize),
715 );
716 table.modify((1 + row_idx, 0), tabled::settings::Alignment::center());
717 }
718 }
719
720 write!(f, "{table}")
721 }
722 }
723 }
724}
725
726#[cfg(test)]
727mod test {
728 use std::sync::LazyLock;
729
730 use vortex_buffer::Buffer;
731 use vortex_buffer::buffer;
732 use vortex_session::VortexSession;
733
734 use crate::IntoArray as _;
735 use crate::VortexSessionExecute;
736 use crate::arrays::BoolArray;
737 use crate::arrays::ListArray;
738 use crate::arrays::PrimitiveArray;
739 use crate::arrays::StructArray;
740 use crate::display::DISPLAY_LIMIT;
741 use crate::dtype::FieldNames;
742 use crate::validity::Validity;
743
744 static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
745
746 #[test]
747 fn test_primitive() {
748 let ctx = SESSION.create_execution_ctx();
749 let x = Buffer::<u32>::empty().into_array();
750 assert_eq!(x.display_values(&ctx).to_string(), "[]");
751
752 let x = buffer![1].into_array();
753 assert_eq!(x.display_values(&ctx).to_string(), "[1i32]");
754
755 let x = buffer![1, 2, 3, 4].into_array();
756 assert_eq!(
757 x.display_values(&ctx).to_string(),
758 "[1i32, 2i32, 3i32, 4i32]"
759 );
760
761 let x =
762 PrimitiveArray::from_iter(0i32..i32::try_from(DISPLAY_LIMIT).unwrap() + 1).into_array();
763 assert_eq!(
764 x.display_values(&ctx).to_string(),
765 "[0i32, 1i32, 2i32, 3i32, 4i32, 5i32, 6i32, 7i32, 8i32, 9i32, 10i32, 11i32, 12i32, ..., 14i32, 15i32, 16i32]"
766 );
767 }
768
769 #[test]
770 fn test_empty_struct() {
771 let ctx = SESSION.create_execution_ctx();
772 let s = StructArray::try_new(
773 FieldNames::empty(),
774 vec![],
775 3,
776 Validity::Array(BoolArray::from_iter([true, false, true]).into_array()),
777 )
778 .unwrap()
779 .into_array();
780 assert_eq!(s.display_values(&ctx).to_string(), "[{}, null, {}]");
781 }
782
783 #[test]
784 fn test_simple_struct() {
785 let ctx = SESSION.create_execution_ctx();
786 let s = StructArray::from_fields(&[
787 ("x", buffer![1, 2, 3, 4].into_array()),
788 ("y", buffer![-1, -2, -3, -4].into_array()),
789 ])
790 .unwrap()
791 .into_array();
792 assert_eq!(
793 s.display_values(&ctx).to_string(),
794 "[{x: 1i32, y: -1i32}, {x: 2i32, y: -2i32}, {x: 3i32, y: -3i32}, {x: 4i32, y: -4i32}]"
795 );
796 }
797
798 #[test]
799 fn test_list() {
800 let mut ctx = SESSION.create_execution_ctx();
801 let x = ListArray::try_new(
802 buffer![1, 2, 3, 4].into_array(),
803 buffer![0, 0, 1, 1, 2, 4].into_array(),
804 Validity::Array(BoolArray::from_iter([true, true, false, true, true]).into_array()),
805 &mut ctx,
806 )
807 .unwrap()
808 .into_array();
809 assert_eq!(
810 x.display_values(&ctx).to_string(),
811 "[[], [1i32], null, [2i32], [3i32, 4i32]]"
812 );
813 }
814
815 #[test]
816 fn test_display_tree_nullable_primitive_validity_child() {
817 let array =
818 PrimitiveArray::from_option_iter([Some(1i64), Some(2), None, Some(3)]).into_array();
819 let expected = "root: vortex.primitive(i64?, len=4) nbytes=33 B (100.00%)\n metadata: ptype: i64\n buffer: values host 32 B (align=8) (96.97%)\n validity: vortex.bool(bool, len=4) nbytes=1 B (3.03%)\n metadata: offset: 0\n buffer: bits host 1 B (align=1) (100.00%)\n";
820 assert_eq!(format!("{}", array.display_tree()), expected);
821 }
822
823 #[test]
824 fn test_table_display_primitive() {
825 let ctx = SESSION.create_execution_ctx();
826 use crate::display::DisplayOptions;
827
828 let array = buffer![1, 2, 3, 4].into_array();
829 let table_display = array.display_as(DisplayOptions::TableDisplay, &ctx);
830 assert_eq!(
831 table_display.to_string(),
832 r"
833┌──────┐
834│ 1i32 │
835├──────┤
836│ 2i32 │
837├──────┤
838│ 3i32 │
839├──────┤
840│ 4i32 │
841└──────┘"
842 .trim()
843 );
844 }
845
846 #[test]
847 fn test_table_display() {
848 let ctx = SESSION.create_execution_ctx();
849 use crate::display::DisplayOptions;
850
851 let array =
852 PrimitiveArray::from_option_iter(vec![Some(-1), Some(-2), Some(-3), None]).into_array();
853
854 let struct_ = StructArray::try_from_iter_with_validity(
855 [("x", buffer![1, 2, 3, 4].into_array()), ("y", array)],
856 Validity::Array(BoolArray::from_iter([true, false, true, true]).into_array()),
857 )
858 .unwrap()
859 .into_array();
860
861 let table_display = struct_.display_as(DisplayOptions::TableDisplay, &ctx);
862 assert_eq!(
863 table_display.to_string(),
864 r"
865┌──────┬───────┐
866│ x │ y │
867├──────┼───────┤
868│ 1i32 │ -1i32 │
869├──────┼───────┤
870│ null │
871├──────┼───────┤
872│ 3i32 │ -3i32 │
873├──────┼───────┤
874│ 4i32 │ null │
875└──────┴───────┘"
876 .trim()
877 );
878 }
879}