rig_ballista/
lib.rs

1//! # rig-ballista
2//!
3//! Apache Ballista + DataFusion + Iceberg companion crate for
4//! [`rig-compose`](https://crates.io/crates/rig-compose).
5//!
6//! **Status:** the [`catalog::MetadataCatalog`] trait and the
7//! [`catalog::InMemoryMetadataCatalog`] reference implementation ship
8//! today. The Iceberg + Ballista-backed catalog will plug into the
9//! same trait once the upstream toolchain stabilises.
10//!
11//! ## Why a separate crate
12//! - **MSRV isolation.** `iceberg-rust` 0.9 currently requires rustc 1.92;
13//!   pinning that into the rig-compose tree would force every consumer
14//!   onto the same toolchain.
15//! - **Compile-cost isolation.** Ballista pulls in DataFusion, Arrow,
16//!   gRPC, Parquet — none of which the kernel needs.
17//! - **Boundary discipline.** Ballista is a query-engine boundary, not a
18//!   file-format boundary. Keeping it behind a trait keeps the skill/tool
19//!   surface clean.
20//!
21//! ## Pruning seam
22//!
23//! Downstream agents store per-file sketches (HLL, variance, grammar
24//! histograms — whatever their pruner needs) and reach the catalog
25//! through [`catalog::MetadataCatalog`]:
26//!
27//! ```no_run
28//! use rig_ballista::{FileId, FileStats, InMemoryMetadataCatalog, MetadataCatalog};
29//!
30//! #[derive(Clone)]
31//! struct MySketch { distinct: u64, variance: f64 }
32//!
33//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
34//! let cat = InMemoryMetadataCatalog::<MySketch>::new();
35//! cat.insert(FileStats {
36//!     id: FileId::new(),
37//!     partition: "auth-edge".into(),
38//!     sketch: MySketch { distinct: 1024, variance: 0.7 },
39//! });
40//! let files = cat.list_files(None).await?;
41//! let _ = files;
42//! # Ok(()) }
43//! ```
44
45#![doc(html_root_url = "https://docs.rs/rig-ballista/0.1.0")]
46#![deny(missing_docs)]
47
48pub mod catalog;
49
50pub use catalog::{FileId, FileStats, InMemoryMetadataCatalog, MetadataCatalog, StorageError};
51
52/// Placeholder type retained for backward compatibility with the
53/// initial `0.1.0` scaffolding release. Prefer
54/// [`catalog::InMemoryMetadataCatalog`] for new code; this type will
55/// be removed in `0.2`.
56#[deprecated(
57    since = "0.1.1",
58    note = "use `rig_ballista::catalog::InMemoryMetadataCatalog` instead"
59)]
60#[derive(Debug, Default, Clone, Copy)]
61pub struct PlaceholderCatalog;
62
63#[allow(deprecated)]
64impl PlaceholderCatalog {
65    /// Mint a new placeholder. Prefer
66    /// [`catalog::InMemoryMetadataCatalog::new`] for new code.
67    pub const fn new() -> Self {
68        Self
69    }
70}
rig_ballista/lib.rs

rig_ballista/
lib.rs
