fv-streams-sql 0.9.0

The SQL front door for FusionVault Streams: a streaming SQL statement parses to a small typed logical plan and lowers to the same topology the TOML frontend produces — one runtime, two front doors. No DataFusion planner, no fork; expressions compile through the value dialect as the steps already do.
Documentation
//! The calls a windowed `SELECT` makes: the window functions (`TUMBLE`, `HOP`, `SESSION`), the
//! aggregates, and the `INTERVAL`s they take.

use super::{AggSpec, Proj, Win};
use crate::expr;
use sqlparser::ast::{
    DateTimeField, DuplicateTreatment, Expr, Function, FunctionArg, FunctionArgExpr, FunctionArguments, SelectItem,
    Value,
};

pub(super) fn is_window_fn(f: &Function) -> bool {
    matches!(f.name.to_string().to_uppercase().as_str(), "TUMBLE" | "HOP" | "SESSION")
}

/// `TUMBLE(ts, INTERVAL <size>)` / `HOP(ts, INTERVAL <slide>, INTERVAL <size>)` /
/// `SESSION(ts, INTERVAL <gap>)` → (event-time column, window).
pub(super) fn parse_window_fn(f: &Function) -> Result<(String, Win), String> {
    let name = f.name.to_string().to_uppercase();
    let args = fn_args(f)?;
    let time_col = |e: &Expr| -> Result<String, String> {
        match e {
            Expr::Identifier(id) => Ok(id.value.clone()),
            Expr::CompoundIdentifier(p) => Ok(p.last().expect("non-empty").value.clone()),
            _ => Err(format!("{name}(…)'s first argument must be the event-time column")),
        }
    };
    // an optional trailing INTERVAL beyond the base arity is the allowed lateness.
    let lateness = |base: usize| -> Result<Option<i64>, String> {
        match args.len() {
            n if n == base => Ok(None),
            n if n == base + 1 => Ok(Some(interval_ms(args[base])?)),
            _ => Err(String::new()), // arity handled by the arm guards below
        }
    };
    match name.as_str() {
        "TUMBLE" if args.len() == 2 || args.len() == 3 => Ok((
            time_col(args[0])?,
            Win::Tumble {
                size_ms: interval_ms(args[1])?,
                lateness_ms: lateness(2)?,
            },
        )),
        "HOP" if args.len() == 3 || args.len() == 4 => Ok((
            time_col(args[0])?,
            Win::Hop {
                slide_ms: interval_ms(args[1])?,
                size_ms: interval_ms(args[2])?,
                lateness_ms: lateness(3)?,
            },
        )),
        "SESSION" if args.len() == 2 || args.len() == 3 => Ok((
            time_col(args[0])?,
            Win::Session {
                gap_ms: interval_ms(args[1])?,
                lateness_ms: lateness(2)?,
            },
        )),
        "TUMBLE" | "SESSION" => Err(format!(
            "{name}(ts, INTERVAL <size> [, INTERVAL <lateness>]) takes 2 or 3 arguments"
        )),
        "HOP" => {
            Err("HOP(ts, INTERVAL <slide>, INTERVAL <size> [, INTERVAL <lateness>]) takes 3 or 4 arguments".into())
        }
        other => Err(format!("unsupported window function `{other}`")),
    }
}

pub(super) fn is_agg_name(name: &str) -> bool {
    matches!(name, "count" | "sum" | "avg" | "min" | "max")
}

/// Classify a windowed `SELECT`'s projections: aggregate calls (→ `aggs`, with any expression
/// arguments hoisted to `pre` computed columns), bare group columns (skipped — GROUP BY captured
/// them), and other computed columns over the window/group/aggregates (→ `post` applyExpression
/// steps after the aggregate, e.g. `day = substring(epochToIso(windowStart), 1, 10)`).
#[allow(clippy::type_complexity)]
pub(super) fn parse_agg_select(projection: &[SelectItem]) -> Result<(Vec<Proj>, Vec<AggSpec>, Vec<Proj>), String> {
    let mut pre: Vec<Proj> = Vec::new();
    let mut aggs = Vec::new();
    let mut post: Vec<Proj> = Vec::new();
    for item in projection {
        let (e, alias) = match item {
            SelectItem::ExprWithAlias { expr, alias } => (expr, Some(alias.value.clone())),
            SelectItem::UnnamedExpr(e) => (e, None),
            SelectItem::Wildcard(_) => return Err("`SELECT *` is not allowed with GROUP BY".into()),
            _ => return Err("unsupported projection in a GROUP BY query".into()),
        };
        match e {
            Expr::Function(f) if is_agg_name(&f.name.to_string().to_lowercase()) => {
                aggs.push(agg_of(f, alias, &mut pre)?);
            }
            // a bare group column — already in the aggregate's output.
            Expr::Identifier(_) | Expr::CompoundIdentifier(_) => {}
            // a computed column over the window/group/aggregates → a post-aggregate applyExpression.
            _ => {
                let out =
                    alias.ok_or("a computed SELECT column in a GROUP BY query needs an alias (`<expr> AS name`)")?;
                post.push(Proj {
                    out,
                    expr: Some(expr::to_dialect(e)?),
                });
            }
        }
    }
    Ok((pre, aggs, post))
}

fn agg_of(f: &Function, alias: Option<String>, pre: &mut Vec<Proj>) -> Result<AggSpec, String> {
    let name = f.name.to_string().to_lowercase();
    let alias = alias.ok_or_else(|| format!("aggregate `{name}(…)` needs an alias (`{name}(…) AS name`)"))?;
    let distinct = matches!(
        &f.args,
        FunctionArguments::List(l) if l.duplicate_treatment == Some(DuplicateTreatment::Distinct)
    );
    let op = match (name.as_str(), distinct) {
        ("count", false) => "count",
        ("count", true) => "countDistinct",
        ("sum", false) => "sum",
        ("avg", false) => "avg",
        ("min", false) => "min",
        ("max", false) => "max",
        (other, true) => return Err(format!("DISTINCT is only supported on `count()`, not `{other}()`")),
        (other, false) => {
            return Err(format!(
                "unsupported aggregate `{other}` — count/sum/avg/min/max/count(DISTINCT …)"
            ))
        }
    };
    let args = fn_args(f)?;
    // count(*) has no column; a bare column feeds the aggregate directly; an EXPRESSION argument
    // (CASE, arithmetic) becomes a synthetic pre-aggregate column (the q15/q16 null-mask shape).
    let column = match args.first() {
        None => String::new(),
        Some(Expr::Identifier(id)) => id.value.clone(),
        Some(Expr::CompoundIdentifier(p)) => p.last().expect("non-empty").value.clone(),
        Some(other) => {
            let synth = format!("_fv_agg{}", pre.len());
            pre.push(Proj {
                out: synth.clone(),
                expr: Some(expr::to_dialect(other)?),
            });
            synth
        }
    };
    Ok(AggSpec {
        call: f.to_string(),
        op: op.to_string(),
        column,
        alias,
    })
}

/// The plain `Expr` arguments of a function call (a `*` wildcard contributes none — `count(*)`).
fn fn_args(f: &Function) -> Result<Vec<&Expr>, String> {
    let list = match &f.args {
        FunctionArguments::List(l) => &l.args,
        FunctionArguments::None => return Ok(Vec::new()),
        FunctionArguments::Subquery(_) => return Err("subquery arguments are not supported".into()),
    };
    let mut out = Vec::new();
    for a in list {
        match a {
            FunctionArg::Unnamed(FunctionArgExpr::Expr(e)) => out.push(e),
            FunctionArg::Unnamed(FunctionArgExpr::Wildcard) => {}
            _ => return Err("unsupported function argument (named / qualified wildcard)".into()),
        }
    }
    Ok(out)
}

/// An `INTERVAL '<n>' <unit>` as milliseconds.
pub(super) fn interval_ms(e: &Expr) -> Result<i64, String> {
    let Expr::Interval(iv) = e else {
        return Err(format!("expected an INTERVAL (e.g. `INTERVAL '10' SECOND`), got `{e}`"));
    };
    let n: i64 = match iv.value.as_ref() {
        Expr::Value(v) => match &v.value {
            Value::SingleQuotedString(s) | Value::Number(s, _) => s
                .trim()
                .parse()
                .map_err(|_| format!("interval value `{s}` is not an integer"))?,
            other => return Err(format!("unsupported interval value `{other}`")),
        },
        other => return Err(format!("unsupported interval value `{other}`")),
    };
    let unit = match &iv.leading_field {
        Some(DateTimeField::Millisecond) => 1,
        Some(DateTimeField::Second) => 1_000,
        Some(DateTimeField::Minute) => 60_000,
        Some(DateTimeField::Hour) => 3_600_000,
        Some(DateTimeField::Day) => 86_400_000,
        other => {
            return Err(format!(
                "unsupported interval unit `{other:?}` — use MILLISECOND / SECOND / MINUTE / HOUR / DAY"
            ))
        }
    };
    Ok(n * unit)
}