densa_arrow/lib.rs
1//! Apache Arrow tables in densa's data grid.
2//!
3//! [`ArrowTable`] holds Arrow [`RecordBatch`](arrow_array::RecordBatch)es (from Parquet,
4//! DataFusion, DuckDB, a Flight stream or your own code) and formats their values into
5//! grid cells; [`ArrowTable::view`] turns it into a `densa_grid::GridSource` scrolled to
6//! a row, which `GridPainter` draws. Arrays are shared with the batches, never copied, so a
7//! table of millions of rows costs no more to show than its visible rows, and drawing a
8//! frame allocates nothing.
9//!
10//! For live data, [`LiveModel`] makes a `densa_data::LiveTable` the model of the grid widget
11//! (`densa_widgets::DataGrid`): sorted by a click, filtered by the app, its selection kept on
12//! a row as the row moves. [`LiveGrid`] paints a view of one with `GridPainter` directly,
13//! and [`LiveSeries`] reads two of its numeric columns as a `densa_chart` series (a price
14//! over time), so a chart follows the same live data.
15//!
16//! For tables too large to hold (a query engine's result over billions of rows), a
17//! [`PagedModel`] is the grid widget's model: your [`PageSource`] gives rows a page at a
18//! time, on a thread of the model's own, and the grid fetches only the pages it shows, in
19//! the order a click on a column title asks for.
20//!
21//! ```
22//! use std::sync::Arc;
23//! use arrow_array::{ArrayRef, Float64Array, RecordBatch, StringArray};
24//! use densa_arrow::ArrowTable;
25//! use densa_grid::{CellText, GridSource, Palette};
26//!
27//! let batch = RecordBatch::try_from_iter([
28//! ("sensor", Arc::new(StringArray::from(vec!["a-1", "b-2"])) as ArrayRef),
29//! ("celsius", Arc::new(Float64Array::from(vec![21.5, 80.25])) as ArrayRef),
30//! ])?;
31//! let mut table = ArrowTable::from_batches([batch])?;
32//! table.set_decimals(1, Some(1))?;
33//!
34//! let columns = table.columns(); // for `GridPainter::new`
35//! let view = table.view(0, &Palette::new()); // each frame: `painter.paint(&view, &mut canvas)`
36//! let mut text = CellText::new();
37//! view.cell(1, 1, &mut text);
38//! assert_eq!(text.as_str(), "80.2");
39//! # Ok::<(), Box<dyn std::error::Error>>(())
40//! ```
41
42//! The API takes and returns [`arrow_array`] and [`arrow_schema`] types, re-exported here so
43//! applications use the same Arrow version: a major Arrow upgrade is a breaking release of
44//! this crate.
45
46pub use arrow_array;
47pub use arrow_schema;
48
49mod calendar;
50mod live;
51mod model;
52mod paged;
53mod reader;
54mod series;
55mod table;
56
57pub use live::{LiveGrid, LiveGridView};
58pub use model::LiveModel;
59pub use paged::{FetchError, PageError, PageOptions, PageQuery, PageSource, PagedModel, SortKey};
60pub use series::{LiveSeries, SeriesError, SeriesPoints};
61pub use table::{ArrowGrid, ArrowTable, CellState, TableError};