Skip to main content

uqa_sql/semantics/projection/
stars.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Borrowed wildcard observation owns SQL namespace validation and admitted layout scratch.
8
9use crate::{RowSchema, SQLError, ScalarExpr};
10use uqa_core::memory::ProductionControl;
11
12/// Generate a reference to one bound logical position. Ambiguous names retain an ordinal reference; uniquely addressable names preserve their original qualifier.
13pub fn bound_projection_expression_with_control(
14    schema: &RowSchema,
15    position: usize,
16    control: &ProductionControl<'_>,
17) -> Result<crate::plan::OwnedScalarExpr, SQLError> {
18    if let Some(identity) = schema.identity(position) {
19        let unique = identity.qualifier().map_or_else(
20            || schema.unqualified_position(identity.column()) == Some(position),
21            |qualifier| schema.qualified_position(qualifier, identity.column()) == Some(position),
22        );
23        if unique {
24            return Ok(crate::plan::OwnedScalarExpr::column(
25                control.copy_text(identity.column())?,
26                identity
27                    .qualifier()
28                    .map(|name| control.copy_text(name))
29                    .transpose()?,
30                control,
31            )?);
32        }
33    }
34    Ok(ScalarExpr::Position(position).copy_for_rewrite(control)?)
35}
36
37/// Expand a qualified ROW star while retaining each generated scalar independently from the admitted result buffer.
38pub(crate) fn row_star_fields_with_control(
39    expression: &ScalarExpr,
40    schema: &RowSchema,
41    control: &ProductionControl<'_>,
42) -> Result<Option<uqa_core::memory::Produced<Vec<crate::plan::OwnedScalarExpr>>>, SQLError> {
43    control.check()?;
44    if !matches!(expression, ScalarExpr::QualifiedStar(_)) {
45        return Ok(None);
46    }
47    let mut fields = uqa_core::memory::ProductionVec::new(*control);
48    visit_bound_projection_star_fields(
49        expression,
50        schema,
51        schema,
52        control,
53        &mut |column, position, qualifier| {
54            let expression = match position {
55                Some(position) => {
56                    bound_projection_expression_with_control(schema, position, control)?
57                }
58                None => crate::plan::OwnedScalarExpr::column(
59                    control.copy_text(column)?,
60                    Some(control.copy_text(qualifier.expect("hidden qualified field"))?),
61                    control,
62                )?,
63            };
64            fields.push_produced(control.finish(expression, control.empty_reservation())?)?;
65            Ok(())
66        },
67    )?;
68    Ok(Some(fields.finish()?))
69}
70
71pub type ProjectionFieldVisitor<'a> =
72    dyn FnMut(&str, Option<usize>, Option<&str>) -> Result<(), SQLError> + 'a;
73
74/// Visit each visible field of a bound wildcard. Bare stars use the local FROM output; qualified stars preserve the selected enclosing namespace, LATERAL validation and physical field order. A non-wildcard returns false without invoking the consumer.
75pub fn visit_bound_projection_star_fields(
76    expression: &ScalarExpr,
77    schema: &RowSchema,
78    expression_schema: &RowSchema,
79    control: &ProductionControl<'_>,
80    observe: &mut ProjectionFieldVisitor<'_>,
81) -> Result<bool, SQLError> {
82    visit_bound_projection_star_metadata(
83        expression,
84        schema,
85        expression_schema,
86        control,
87        &mut |field| observe(field.name, field.logical, field.qualifier),
88    )
89}
90
91pub struct ProjectionStarMetadata<'a> {
92    pub name: &'a str,
93    pub logical: Option<usize>,
94    pub qualifier: Option<&'a str>,
95    pub ty: Option<&'a crate::ColumnType>,
96    pub collation: Option<u32>,
97    pub(crate) record: Option<&'a crate::schema::RecordMetadata>,
98}
99
100pub fn visit_bound_projection_star_metadata<'a>(
101    expression: &'a ScalarExpr,
102    schema: &'a RowSchema,
103    expression_schema: &'a RowSchema,
104    control: &ProductionControl<'_>,
105    observe: &mut dyn FnMut(ProjectionStarMetadata<'a>) -> Result<(), SQLError>,
106) -> Result<bool, SQLError> {
107    control.check()?;
108    match expression {
109        ScalarExpr::Star => {
110            for (position, column) in schema.columns().iter().enumerate() {
111                control.check()?;
112                if super::visible_projection_source_position(schema, position) {
113                    observe(ProjectionStarMetadata {
114                        name: schema.public_name(position).unwrap_or(column),
115                        logical: Some(position),
116                        qualifier: None,
117                        ty: schema.column_type(position),
118                        collation: schema.column_collation(position),
119                        record: schema.record_metadata(position),
120                    })?;
121                }
122            }
123        }
124        ScalarExpr::QualifiedStar(qualifier) => {
125            let schema = expression_schema;
126            schema.require_lateral_qualifier(qualifier)?;
127            let mut found = false;
128            schema.visit_qualified_star_metadata(
129                qualifier,
130                control,
131                |name, logical, ty, collation, record| {
132                    found = true;
133                    if logical.is_none_or(|position| {
134                        super::visible_projection_source_position(schema, position)
135                    }) {
136                        observe(ProjectionStarMetadata {
137                            name,
138                            logical,
139                            qualifier: Some(qualifier),
140                            ty,
141                            collation,
142                            record,
143                        })?;
144                    }
145                    Ok(())
146                },
147            )?;
148            if !found && !schema.has_qualifier(qualifier) {
149                return Err(schema
150                    .unavailable_qualifier_error(qualifier)
151                    .unwrap_or_else(|| SQLError::UnknownTable(qualifier.to_string())));
152            }
153        }
154        _ => return Ok(false),
155    }
156    control.check()?;
157    Ok(true)
158}