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::disallowed_types)] // cold path: SQL parsing and query planning only
34#![allow(clippy::doc_markdown)]
35#![allow(clippy::uninlined_format_args)]
36
37pub mod datafusion;
38pub mod error;
39pub mod parser;
40pub mod planner;
41pub mod translator;
42
43// Re-export key types
44pub use parser::{parse_streaming_sql, StreamingStatement};
45pub use planner::streaming_optimizer::{StreamingPhysicalValidator, StreamingValidatorMode};
46pub use planner::StreamingPlanner;
47pub use translator::{OrderOperatorConfig, WindowOperatorConfig, WindowType};
48
49// Re-export types
50pub use datafusion::execute::execute_streaming_sql;
51pub use datafusion::{
52    base_session_config, create_session_context, create_streaming_context_with_validator,
53    register_streaming_functions, register_streaming_functions_with_watermark, DdlResult,
54    QueryResult, StreamingSqlResult, WatermarkDynamicFilter,
55};
56
57/// Result type for SQL operations
58pub type Result<T> = std::result::Result<T, Error>;
59
60/// SQL-specific errors
61#[derive(Debug, thiserror::Error)]
62pub enum Error {
63    /// SQL parsing error
64    ParseError(#[from] parser::ParseError),
65
66    /// Planning error
67    PlanningError(#[from] planner::PlanningError),
68
69    /// `DataFusion` error (translated to user-friendly messages on display)
70    DataFusionError(#[from] datafusion_common::DataFusionError),
71
72    /// Unsupported SQL feature
73    UnsupportedFeature(String),
74}
75
76impl std::fmt::Display for Error {
77    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
78        match self {
79            Self::ParseError(e) => write!(f, "SQL parse error: {e}"),
80            Self::PlanningError(e) => write!(f, "Planning error: {e}"),
81            Self::DataFusionError(e) => {
82                let translated = error::translate_datafusion_error(&e.to_string());
83                write!(f, "{translated}")
84            }
85            Self::UnsupportedFeature(msg) => {
86                write!(f, "Unsupported feature: {msg}")
87            }
88        }
89    }
90}
laminar_sql/lib.rs

laminar_sql/
lib.rs
