laminar_sql/
lib.rs

1//! # `LaminarDB` SQL
2//!
3//! SQL interface for `LaminarDB` with streaming extensions.
4//!
5//! This crate provides:
6//! - SQL parsing with streaming extensions (windows, watermarks, EMIT)
7//! - Query planning and optimization via `DataFusion`
8//! - Streaming-aware physical operators
9//! - SQL-to-operator translation
10//!
11//! ## Streaming SQL Extensions
12//!
13//! ```sql
14//! -- Tumbling window with EMIT
15//! SELECT
16//!   window_start,
17//!   COUNT(*) as event_count
18//! FROM events
19//! GROUP BY TUMBLE(event_time, INTERVAL '5' MINUTE)
20//! EMIT AFTER WATERMARK;
21//!
22//! -- Stream-to-stream join
23//! SELECT *
24//! FROM orders o
25//! JOIN order_items i
26//!   ON o.order_id = i.order_id
27//!   AND i.event_time BETWEEN o.event_time AND o.event_time + INTERVAL '1' HOUR;
28//! ```
29
30#![deny(missing_docs)]
31#![warn(clippy::all, clippy::pedantic)]
32#![allow(clippy::module_name_repetitions)]
33#![allow(clippy::doc_markdown)]
34#![allow(clippy::uninlined_format_args)]
35
36pub mod datafusion;
37pub mod error;
38pub mod parser;
39pub mod planner;
40pub mod translator;
41
42// Re-export key types
43pub use parser::{parse_streaming_sql, StreamingStatement};
44pub use planner::StreamingPlanner;
45pub use translator::{OrderOperatorConfig, WindowOperatorConfig, WindowType};
46
47// Re-export types
48pub use datafusion::execute::execute_streaming_sql;
49pub use datafusion::{
50    register_streaming_functions, register_streaming_functions_with_watermark, DdlResult,
51    QueryResult, StreamingSqlResult,
52};
53
54/// Result type for SQL operations
55pub type Result<T> = std::result::Result<T, Error>;
56
57/// SQL-specific errors
58#[derive(Debug, thiserror::Error)]
59pub enum Error {
60    /// SQL parsing error
61    ParseError(#[from] parser::ParseError),
62
63    /// Planning error
64    PlanningError(#[from] planner::PlanningError),
65
66    /// `DataFusion` error (translated to user-friendly messages on display)
67    DataFusionError(#[from] datafusion_common::DataFusionError),
68
69    /// Unsupported SQL feature
70    UnsupportedFeature(String),
71}
72
73impl std::fmt::Display for Error {
74    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75        match self {
76            Self::ParseError(e) => write!(f, "SQL parse error: {e}"),
77            Self::PlanningError(e) => write!(f, "Planning error: {e}"),
78            Self::DataFusionError(e) => {
79                let translated = error::translate_datafusion_error(&e.to_string());
80                write!(f, "{translated}")
81            }
82            Self::UnsupportedFeature(msg) => {
83                write!(f, "Unsupported feature: {msg}")
84            }
85        }
86    }
87}
laminar_sql/lib.rs

laminar_sql/
lib.rs
