uqa_sql/catalog/stored_ast/

mod.rs

//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Traversal and identity binding for durable SQL syntax trees.

use crate::{
    ast::{Expr, FrameBound, FromClause, SelectStmt, Statement},
    SQLError,
};
use std::collections::BTreeSet;
use uqa_core::RelationIdentity;
mod expressions;
mod literals;
mod merge;
mod routines;
mod sites;
mod sources;
mod types;
pub use expressions::*;
pub use literals::read_unknown_stored_literal;
pub use merge::visit_stored_statement_merges;
pub use routines::*;
pub use sites::*;
pub use sources::*;
pub use types::*;

pub type MergeCallback<'a> = &'a mut dyn FnMut(&mut crate::ast::MergeStmt) -> Result<(), SQLError>;

pub type ExpressionCallback<'a> = &'a mut dyn FnMut(&mut Expr) -> Result<(), SQLError>;
pub type ProjectionCallback<'a> =
    &'a mut dyn FnMut(&mut crate::ast::Projection) -> Result<(), SQLError>;
pub type SourceCallback<'a> = &'a mut dyn FnMut(&mut FromClause) -> Result<(), SQLError>;

pub struct StoredAstVisitor<'a, R, F> {
    pub source: Option<SourceCallback<'a>>,
    pub merge: Option<MergeCallback<'a>>,
    pub expression: Option<ExpressionCallback<'a>>,
    /// Called for each item of a select list or `RETURNING` list before its expression is visited.
    pub projection: Option<ProjectionCallback<'a>>,
    pub ty: Option<&'a mut dyn FnMut(&mut String)>,
    pub relation: &'a mut R,
    pub routine: &'a mut F,
}

impl<R, F> StoredAstVisitor<'_, R, F>
where
    R: FnMut(&mut String) -> Result<(), SQLError>,
    F: FnMut(&mut String, Option<&mut Option<crate::ast::FunctionBinding>>) -> Result<(), SQLError>,
{
    pub fn bind_statement(&mut self, statement: &mut Statement) -> Result<(), SQLError> {
        let ctes = BTreeSet::new();
        match statement {
            Statement::Select(query) => self.bind_select(query, &ctes),
            Statement::Insert(insert) => self.bind_insert(insert, &ctes),
            Statement::Update(update) => self.bind_update(update, &ctes),
            Statement::Delete(delete) => self.bind_delete(delete, &ctes),
            Statement::Notify { .. } => Ok(()),
            Statement::Values { rows } => {
                for expression in rows.iter_mut().flatten() {
                    self.bind_expr(expression, &ctes)?;
                }
                Ok(())
            }
            Statement::Merge(merge) => self.bind_merge(merge, &ctes),
            _ => Err(SQLError::Internal(
                "catalog-owned statement has an unsupported dependency shape".into(),
            )),
        }
    }

    fn bind_insert(
        &mut self,
        insert: &mut crate::ast::InsertStmt,
        inherited: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        (self.relation)(&mut insert.table)?;
        let visible = self.bind_ctes(&mut insert.with, inherited)?;
        if let Some(source) = insert.select_source.as_deref_mut() {
            self.bind_select(source, &visible)?;
        }
        for expression in insert
            .columns
            .iter_mut()
            .flat_map(crate::ast::AssignmentTarget::expressions_mut)
            .chain(insert.rows.iter_mut().flatten())
        {
            self.bind_expr(expression, &visible)?;
        }
        if let Some(conflict) = &mut insert.on_conflict {
            for expression in &mut conflict.expressions {
                self.bind_expr(expression, &visible)?;
            }
            if let Some(predicate) = conflict.predicate.as_deref_mut() {
                self.bind_expr(predicate, &visible)?;
            }
            if let crate::ast::OnConflictAction::Update {
                assignments,
                r#where,
            } = &mut conflict.action
            {
                for expression in assignments.iter_mut().flat_map(|(target, value)| {
                    target.expressions_mut().chain(std::iter::once(value))
                }) {
                    self.bind_expr(expression, &visible)?;
                }
                if let Some(expression) = r#where {
                    self.bind_expr(expression, &visible)?;
                }
            }
        }
        for projection in &mut insert.returning {
            self.bind_projection(projection, &visible)?;
        }
        Ok(())
    }

    fn bind_update(
        &mut self,
        update: &mut crate::ast::UpdateStmt,
        inherited: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        (self.relation)(&mut update.table)?;
        let visible = self.bind_ctes(&mut update.with, inherited)?;
        if let Some(source) = &mut update.from {
            self.bind_from(source, &visible)?;
        }
        for expression in update
            .assignments
            .iter_mut()
            .flat_map(|(target, value)| target.expressions_mut().chain(std::iter::once(value)))
        {
            self.bind_expr(expression, &visible)?;
        }
        if let Some(expression) = &mut update.r#where {
            self.bind_expr(expression, &visible)?;
        }
        for projection in &mut update.returning {
            self.bind_projection(projection, &visible)?;
        }
        Ok(())
    }

    fn bind_delete(
        &mut self,
        delete: &mut crate::ast::DeleteStmt,
        inherited: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        (self.relation)(&mut delete.table)?;
        let visible = self.bind_ctes(&mut delete.with, inherited)?;
        if let Some(source) = &mut delete.using {
            self.bind_from(source, &visible)?;
        }
        if let Some(expression) = &mut delete.r#where {
            self.bind_expr(expression, &visible)?;
        }
        for projection in &mut delete.returning {
            self.bind_projection(projection, &visible)?;
        }
        Ok(())
    }

    fn bind_ctes(
        &mut self,
        ctes: &mut [crate::ast::CTE],
        inherited: &BTreeSet<String>,
    ) -> Result<BTreeSet<String>, SQLError> {
        let mut visible = inherited.clone();
        let recursive = ctes.iter().any(|cte| cte.recursive).then(|| {
            ctes.iter()
                .map(|cte| cte.name.clone())
                .collect::<BTreeSet<_>>()
        });
        for cte in ctes {
            let body_scope = recursive.as_ref().map_or_else(
                || visible.clone(),
                |recursive| inherited.union(recursive).cloned().collect(),
            );
            match &mut cte.body {
                crate::ast::CteBody::Query(query) => self.bind_select(query, &body_scope)?,
                crate::ast::CteBody::Insert(plan) => self.bind_insert(plan, &body_scope)?,
                crate::ast::CteBody::Update(plan) => self.bind_update(plan, &body_scope)?,
                crate::ast::CteBody::Delete(plan) => self.bind_delete(plan, &body_scope)?,
                crate::ast::CteBody::Merge(plan) => self.bind_merge(plan, &body_scope)?,
            }
            if let Some(cycle) = &mut cte.cycle {
                self.bind_expr(&mut cycle.mark_value, &body_scope)?;
                self.bind_expr(&mut cycle.mark_default, &body_scope)?;
            }
            visible.insert(cte.name.clone());
        }
        Ok(visible)
    }

    fn bind_select(
        &mut self,
        select: &mut SelectStmt,
        inherited: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        let visible = self.bind_ctes(&mut select.with, inherited)?;
        if let Some(set) = select.set_op.as_mut().filter(|set| set.left.is_some()) {
            self.bind_set_operation(set, &visible)?;
            let left = set
                .left
                .as_deref()
                .expect("explicit set-operation left input");
            // These fields mirror the left input for AST compatibility; they are not another syntax occurrence.
            select.projections.clone_from(&left.projections);
            select.values.clone_from(&left.values);
            select.from.clone_from(&left.from);
            select.r#where.clone_from(&left.r#where);
            select.group_by.clone_from(&left.group_by);
            select.order_by.clone_from(&left.order_by);
            select.limit.clone_from(&left.limit);
            select.with_ties = left.with_ties;
            select.offset.clone_from(&left.offset);
            return Ok(());
        }
        if let Some(source) = &mut select.from {
            self.bind_from(source, &visible)?;
        }
        for projection in &mut select.projections {
            self.bind_projection(projection, &visible)?;
        }
        for expression in select.values.iter_mut().flatten() {
            self.bind_expr(expression, &visible)?;
        }
        if let Some(expression) = &mut select.r#where {
            self.bind_expr(expression, &visible)?;
        }
        for expression in &mut select.group_by {
            self.bind_expr(expression, &visible)?;
        }
        for expression in select.grouping_sets.iter_mut().flatten() {
            self.bind_expr(expression, &visible)?;
        }
        if let Some(expression) = &mut select.having {
            self.bind_expr(expression, &visible)?;
        }
        for order in &mut select.order_by {
            self.bind_expr(&mut order.expr, &visible)?;
        }
        if let Some(expression) = &mut select.limit {
            self.bind_expr(expression, &visible)?;
        }
        if let Some(expression) = &mut select.offset {
            self.bind_expr(expression, &visible)?;
        }
        for expression in &mut select.distinct_on {
            self.bind_expr(expression, &visible)?;
        }
        for window in &mut select.windows {
            for expression in window.spec.expressions_mut() {
                self.bind_expr(expression, &visible)?;
            }
        }
        if let Some(set) = &mut select.set_op {
            self.bind_set_operation(set, &visible)?;
        }
        Ok(())
    }

    fn bind_set_operation(
        &mut self,
        set: &mut crate::ast::SetOp,
        visible: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        if let Some(left) = &mut set.left {
            self.bind_select(left, visible)?;
        }
        self.bind_select(&mut set.right, visible)?;
        for order in &mut set.combined_order_by {
            self.bind_expr(&mut order.expr, visible)?;
        }
        if let Some(expression) = &mut set.combined_limit {
            self.bind_expr(expression, visible)?;
        }
        if let Some(expression) = &mut set.combined_offset {
            self.bind_expr(expression, visible)?;
        }
        Ok(())
    }

    fn bind_from(
        &mut self,
        source: &mut FromClause,
        visible_ctes: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        if let FromClause::Table { name, .. } = source {
            let is_cte = RelationIdentity::parse_reference(name).is_ok_and(|(schema, relation)| {
                schema.is_none() && visible_ctes.contains(&relation)
            });
            if is_cte {
                return Ok(());
            }
        }
        if let Some(visit) = self.source.as_mut() {
            visit(source)?;
        }
        match source {
            FromClause::Table { name, .. } => {
                (self.relation)(name)?;
            }
            FromClause::Join {
                left, right, on, ..
            } => {
                self.bind_from(left, visible_ctes)?;
                self.bind_from(right, visible_ctes)?;
                if let Some(expression) = on {
                    self.bind_expr(expression, visible_ctes)?;
                }
            }
            FromClause::Values { rows, .. } => {
                for expression in rows.iter_mut().flatten() {
                    self.bind_expr(expression, visible_ctes)?;
                }
            }
            FromClause::Function {
                name,
                binding,
                relations,
                args,
                ..
            } => {
                (self.routine)(name, Some(binding))?;
                if let Some(relations) = relations {
                    (self.relation)(&mut relations.left)?;
                    (self.relation)(&mut relations.right)?;
                }
                for expression in args {
                    self.bind_expr(expression, visible_ctes)?;
                }
            }
            FromClause::FunctionGroup { functions, .. } => {
                for function in functions {
                    (self.routine)(&mut function.name, Some(&mut function.binding))?;
                    if let Some(relations) = &mut function.relations {
                        (self.relation)(&mut relations.left)?;
                        (self.relation)(&mut relations.right)?;
                    }
                    for expression in &mut function.args {
                        self.bind_expr(expression, visible_ctes)?;
                    }
                }
            }
            FromClause::Subquery { body, .. } => self.bind_select(body, visible_ctes)?,
        }
        Ok(())
    }

    fn bind_expression_type(&mut self, expression: &mut Expr) -> Result<(), SQLError> {
        if let Some(visit) = self.expression.as_mut() {
            visit(expression)?;
        }
        if let (
            Some(visit),
            Expr::Cast { ty, .. }
            | Expr::TypedLiteral { ty, .. }
            | Expr::CompositeRow {
                binding: crate::ast::CompositeRowBinding { ty, .. },
                ..
            },
        ) = (self.ty.as_mut(), expression)
        {
            visit(ty);
        }
        Ok(())
    }

    /// Bind a window call's arguments, `FILTER`, keys and frame offsets.
    fn bind_window_call(
        &mut self,
        args: &mut [Expr],
        filter: Option<&mut Expr>,
        spec: &mut crate::ast::WindowSpec,
        visible_ctes: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        for argument in args {
            self.bind_expr(argument, visible_ctes)?;
        }
        if let Some(filter) = filter {
            self.bind_expr(filter, visible_ctes)?;
        }
        for partition in &mut spec.partition_by {
            self.bind_expr(partition, visible_ctes)?;
        }
        for order in &mut spec.order_by {
            self.bind_expr(&mut order.expr, visible_ctes)?;
        }
        if let Some(frame) = &mut spec.frame {
            for bound in [&mut frame.start, &mut frame.end] {
                if let FrameBound::Preceding(inner) | FrameBound::Following(inner) = bound {
                    self.bind_expr(inner, visible_ctes)?;
                }
            }
        }
        Ok(())
    }

    fn bind_projection(
        &mut self,
        projection: &mut crate::ast::Projection,
        visible_ctes: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        if let Some(visit) = self.projection.as_mut() {
            visit(projection)?;
        }
        self.bind_expr(&mut projection.expr, visible_ctes)
    }

    pub fn bind_expr(
        &mut self,
        expression: &mut Expr,
        visible_ctes: &BTreeSet<String>,
    ) -> Result<(), SQLError> {
        self.bind_expression_type(expression)?;
        match expression {
            Expr::Func {
                name,
                binding,
                args,
                order_by,
                filter,
                ..
            } => {
                for argument in args {
                    self.bind_expr(argument, visible_ctes)?;
                }
                for order in order_by {
                    self.bind_expr(&mut order.expr, visible_ctes)?;
                }
                if let Some(filter) = filter {
                    self.bind_expr(filter, visible_ctes)?;
                }
                (self.routine)(name, Some(binding))?;
            }
            Expr::Array(items)
            | Expr::Row(items)
            | Expr::CompositeRow { items, .. }
            | Expr::And(items)
            | Expr::Or(items) => {
                for item in items {
                    self.bind_expr(item, visible_ctes)?;
                }
            }
            Expr::Binary { lhs, rhs, .. } => {
                self.bind_expr(lhs, visible_ctes)?;
                self.bind_expr(rhs, visible_ctes)?;
            }
            Expr::UnaryMinus(inner)
            | Expr::Not(inner)
            | Expr::IsNull { expr: inner, .. }
            | Expr::Cast { expr: inner, .. } => self.bind_expr(inner, visible_ctes)?,
            Expr::Between { expr, low, high } => {
                self.bind_expr(expr, visible_ctes)?;
                self.bind_expr(low, visible_ctes)?;
                self.bind_expr(high, visible_ctes)?;
            }
            Expr::InList { expr, list, .. } => {
                self.bind_expr(expr, visible_ctes)?;
                for item in list {
                    self.bind_expr(item, visible_ctes)?;
                }
            }
            Expr::WindowCall {
                name,
                args,
                spec,
                filter,
                ..
            } => {
                self.bind_window_call(args, filter.as_deref_mut(), spec, visible_ctes)?;
                (self.routine)(name, None)?;
            }
            Expr::Case {
                base,
                when,
                else_branch,
            } => {
                if let Some(base) = base {
                    self.bind_expr(base, visible_ctes)?;
                }
                for (condition, result) in when {
                    self.bind_expr(condition, visible_ctes)?;
                    self.bind_expr(result, visible_ctes)?;
                }
                if let Some(branch) = else_branch {
                    self.bind_expr(branch, visible_ctes)?;
                }
            }
            Expr::ScalarSubquery(body) | Expr::Exists { body, .. } => {
                self.bind_select(body, visible_ctes)?;
            }
            Expr::InSubquery { expr, body, .. } => {
                self.bind_expr(expr, visible_ctes)?;
                self.bind_select(body, visible_ctes)?;
            }
            Expr::Star
            | Expr::QualifiedStar(_)
            | Expr::Default
            | Expr::Column(_)
            | Expr::QualifiedColumn { .. }
            | Expr::InternalColumn(_)
            | Expr::Literal(_)
            | Expr::TypedLiteral { .. }
            | Expr::Param(_) => {}
        }
        Ok(())
    }
}