Skip to main content

uqa_sql/catalog/collations/
expression.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Collation-clause identity and type validation shared by expression analysis and catalog encoding.
8
9use crate::ast::{Expr, FunctionDispatch};
10use crate::{ColumnType, FunctionTypeResolver, SQLError, ScalarExpr};
11use uqa_core::{memory::ProductionControl, Value};
12
13pub struct Clause<'a, T> {
14    pub argument: &'a T,
15    pub name: &'a str,
16    pub oid: Option<u32>,
17}
18
19impl<T> Clause<'_, T> {
20    /// Executable SQL retains a selected identity instead of resolving its former spelling again.
21    pub fn executable_name(&self) -> Result<std::borrow::Cow<'_, str>, SQLError> {
22        let Some(oid) = self.oid else {
23            return Ok(std::borrow::Cow::Borrowed(self.name));
24        };
25        let name = super::builtin_collation_name(i64::from(oid))
26            .ok_or_else(|| SQLError::Internal("unknown collation identity".into()))?;
27        Ok(std::borrow::Cow::Owned(format!(
28            "pg_catalog.{}",
29            crate::expr::quote_ident(name)
30        )))
31    }
32}
33
34/// Retained constants may carry an indeterminate collatable result, but cannot attach a collation to a noncollatable or unresolved type.
35pub(crate) fn validate_literal_collation(
36    ty: Option<&ColumnType>,
37    oid: Option<u32>,
38) -> Result<(), SQLError> {
39    if oid.is_some_and(|oid| oid != 0)
40        && ty.is_none_or(|ty| !crate::schema::composites::type_is_collatable(ty))
41    {
42        return Err(SQLError::Internal(
43            "constant collation does not match its declared type".into(),
44        ));
45    }
46    Ok(())
47}
48
49pub fn scalar_clause(expression: &ScalarExpr) -> Result<Option<Clause<'_, ScalarExpr>>, SQLError> {
50    let ScalarExpr::Func {
51        binding: Some(binding),
52        args,
53        ..
54    } = expression
55    else {
56        return Ok(None);
57    };
58    let Some(FunctionDispatch::Collate { oid }) = binding.dispatch else {
59        return Ok(None);
60    };
61    let [argument, ScalarExpr::Literal(Value::Str(name))] = args.as_slice() else {
62        return Err(SQLError::Internal("invalid COLLATE expression".into()));
63    };
64    Ok(Some(Clause {
65        argument,
66        name,
67        oid,
68    }))
69}
70
71pub fn ast_clause(expression: &Expr) -> Result<Option<Clause<'_, Expr>>, SQLError> {
72    let Expr::Func {
73        binding: Some(binding),
74        args,
75        ..
76    } = expression
77    else {
78        return Ok(None);
79    };
80    let Some(FunctionDispatch::Collate { oid }) = binding.dispatch else {
81        return Ok(None);
82    };
83    let [argument, Expr::Literal(Value::Str(name))] = args.as_slice() else {
84        return Err(SQLError::Internal("invalid COLLATE expression".into()));
85    };
86    Ok(Some(Clause {
87        argument,
88        name,
89        oid,
90    }))
91}
92
93pub(crate) fn discard_scalar_clause(expression: &mut ScalarExpr) -> Result<bool, SQLError> {
94    if scalar_clause(expression)?.is_none() {
95        return Ok(false);
96    }
97    let ScalarExpr::Func { args, .. } =
98        std::mem::replace(expression, ScalarExpr::Literal(Value::Null))
99    else {
100        unreachable!("validated collation clause");
101    };
102    *expression = args
103        .into_iter()
104        .next()
105        .expect("validated collation argument");
106    Ok(true)
107}
108
109pub(crate) fn discard_ast_clause(expression: &mut Expr) -> Result<bool, SQLError> {
110    if ast_clause(expression)?.is_none() {
111        return Ok(false);
112    }
113    let Expr::Func { args, .. } = std::mem::replace(expression, Expr::Literal(Value::Null)) else {
114        unreachable!("validated collation clause");
115    };
116    *expression = args
117        .into_iter()
118        .next()
119        .expect("validated collation argument");
120    Ok(true)
121}
122
123pub fn select(
124    name: &str,
125    selected: Option<u32>,
126    ty: Option<&ColumnType>,
127    catalog: Option<&dyn FunctionTypeResolver>,
128) -> Result<u32, SQLError> {
129    select_with_control(
130        name,
131        selected,
132        ty,
133        catalog,
134        &ProductionControl::uncontrolled(),
135    )
136}
137
138pub(crate) fn select_with_control(
139    name: &str,
140    selected: Option<u32>,
141    ty: Option<&ColumnType>,
142    catalog: Option<&dyn FunctionTypeResolver>,
143    control: &ProductionControl<'_>,
144) -> Result<u32, SQLError> {
145    control.check()?;
146    if let Some(ty) = ty.filter(|ty| !crate::schema::composites::type_is_collatable(ty)) {
147        let ty = ty.without_type_modifiers_with_control(control)?;
148        let name = match catalog {
149            Some(catalog) => catalog.format_type_name_with_control(&ty, control)?,
150            None => ty.display_name_with_control(control)?,
151        };
152        return Err(diagnostic(
153            control,
154            "42804",
155            format_args!("collations are not supported by type {}", name.as_str()),
156        )?);
157    }
158    if let Some(oid) = selected {
159        return valid_oid(oid);
160    }
161    if let Some(oid) = catalog
162        .map(|catalog| catalog.resolve_collation_name_with_control(name, control))
163        .transpose()?
164        .flatten()
165    {
166        return valid_oid(oid);
167    }
168    builtin_name(name, control)
169}
170
171fn valid_oid(oid: u32) -> Result<u32, SQLError> {
172    if oid == 0 {
173        Err(SQLError::Internal("invalid collation identity".into()))
174    } else {
175        Ok(oid)
176    }
177}
178
179/// Catalog-free analysis has the predefined namespace and collation identities.
180fn builtin_name(name: &str, control: &ProductionControl<'_>) -> Result<u32, SQLError> {
181    let names = crate::compiler::parse_regobject_name_with_control(name, control)?
182        .ok_or_else(|| SQLError::Internal("malformed COLLATE name".into()))?;
183    let (schema, local) = match names.as_slice() {
184        [local] => (None, local),
185        [schema, local] => (Some(schema.as_str()), local),
186        [database, schema, local] if database == "uqa" => (Some(schema.as_str()), local),
187        [_, _, _] => {
188            return Err(diagnostic(
189                control,
190                "0A000",
191                format_args!(
192                    "cross-database references are not implemented: {}",
193                    QualifiedName(&names)
194                ),
195            )?)
196        }
197        _ => {
198            return Err(diagnostic(
199                control,
200                "42601",
201                format_args!(
202                    "improper qualified name (too many dotted names): {}",
203                    QualifiedName(&names)
204                ),
205            )?)
206        }
207    };
208    if let Some(schema) = schema.filter(|schema| !matches!(*schema, "pg_catalog" | "public")) {
209        return Err(diagnostic(
210            control,
211            "3F000",
212            format_args!("schema \"{schema}\" does not exist"),
213        )?);
214    }
215    if schema.is_none_or(|schema| schema == "pg_catalog") {
216        if let Some(oid) = super::builtin_collation_oid(local) {
217            return u32::try_from(oid)
218                .map_err(|_| SQLError::Internal("invalid collation identity".into()));
219        }
220    }
221    Err(diagnostic(
222        control,
223        "42704",
224        format_args!(
225            "collation \"{}\" for encoding \"UTF8\" does not exist",
226            QualifiedName(&names)
227        ),
228    )?)
229}
230
231struct QualifiedName<'a>(&'a [String]);
232
233impl std::fmt::Display for QualifiedName<'_> {
234    fn fmt(&self, output: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
235        for (position, component) in self.0.iter().enumerate() {
236            if position > 0 {
237                output.write_str(".")?;
238            }
239            output.write_str(component)?;
240        }
241        Ok(())
242    }
243}
244
245fn diagnostic(
246    control: &ProductionControl<'_>,
247    sqlstate: &str,
248    message: std::fmt::Arguments<'_>,
249) -> Result<SQLError, SQLError> {
250    // Error payloads leave this producer through the existing unreserved SQLError boundary after admitted construction.
251    let (message, _memory) = control.format(message)?.into_parts();
252    Ok(SQLError::Routine {
253        sqlstate: sqlstate.into(),
254        message,
255    })
256}
257
258#[cfg(test)]
259mod tests;