Skip to main content

uqa_sql/expr/context/casting/
metadata.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Retain admitted type descriptions without retaining converted values or callbacks.
8
9use super::{
10    cast_value_with_resolution_with_control, cast_with_resolved_types, optional_type_name,
11    resolve_catalog_type_with_control, ColumnType, EngineHook, Produced, ProductionControl,
12    ResolvedCast, Result, Value,
13};
14use std::sync::Arc;
15
16/// An immutable catalog's identity for already bound or schema-qualified type names. A hook must replace this identity when those names can resolve differently; unqualified search-path-dependent names are excluded by the SQL owner.
17#[derive(Clone, Debug, Default)]
18pub struct CatalogCastScope(Arc<()>);
19
20impl CatalogCastScope {
21    fn matches(&self, other: &Self) -> bool {
22        Arc::ptr_eq(&self.0, &other.0)
23    }
24}
25
26#[derive(Debug)]
27pub(super) struct CastTypes {
28    pub(super) target: Option<Produced<ColumnType>>,
29    pub(super) source: Option<Produced<ColumnType>>,
30    pub(super) parsed_target: Option<Produced<ColumnType>>,
31}
32
33impl CastTypes {
34    pub(super) fn resolve(
35        source: Option<&str>,
36        target: &str,
37        engine: Option<&dyn EngineHook>,
38        control: &ProductionControl<'_>,
39    ) -> Result<Self> {
40        control.check()?;
41        let target_type = resolve_catalog_type_with_control(target, engine, control)?;
42        control.check()?;
43        let source = source
44            .map(|source| resolve_catalog_type_with_control(source, engine, control))
45            .transpose()?
46            .flatten();
47        let parsed_target = if target_type.is_some() {
48            None
49        } else {
50            optional_type_name(target, control)?
51        };
52        Ok(Self {
53            target: target_type,
54            source,
55            parsed_target,
56        })
57    }
58}
59
60/// Successfully resolved metadata for one expression's fixed source/target spellings. Owned descriptors retain their original production allowances; values, input routines, domain checks and session settings remain per evaluation.
61#[derive(Debug)]
62pub struct RetainedCatalogCast {
63    scope: CatalogCastScope,
64    types: CastTypes,
65    _memory: Option<uqa_core::memory::MemoryReservation>,
66}
67
68impl RetainedCatalogCast {
69    /// Decline before conversion when the invoking immutable catalog changed. The caller must keep the original expression and its complete type-schema identity, and evaluate the operand before checking this scope.
70    pub fn evaluate(
71        &self,
72        value: &Value,
73        source: Option<&str>,
74        target: &str,
75        engine: Option<&dyn EngineHook>,
76        control: &ProductionControl<'_>,
77    ) -> Option<Result<Produced<Value>>> {
78        let current = engine?.catalog_cast_scope()?;
79        self.scope.matches(current).then(|| {
80            control.check()?;
81            cast_with_resolved_types(
82                value,
83                source,
84                target,
85                engine,
86                control,
87                &self.types,
88                &mut None,
89            )
90        })
91    }
92}
93
94/// The original conversion result and optional immutable metadata, never a cached row value.
95pub struct ScopedCastResult {
96    pub value: Produced<Value>,
97    pub resolved: Option<ResolvedCast>,
98    pub catalog: Option<Box<RetainedCatalogCast>>,
99}
100
101/// Resolve both names at their original boundary and retain the successful descriptors only while an explicit immutable catalog capability remains valid. Hooks without that capability keep live name resolution.
102pub fn cast_value_with_scoped_resolution(
103    value: &Value,
104    source: Option<&str>,
105    target: &str,
106    engine: Option<&dyn EngineHook>,
107    control: &ProductionControl<'_>,
108) -> Result<ScopedCastResult> {
109    control.check()?;
110    // Explicit builtin scalar selections already have the smaller existing execution descriptor.
111    if source
112        .and_then(crate::type_resolution::pg_catalog_builtin_type)
113        .zip(crate::type_resolution::pg_catalog_builtin_type(target))
114        .is_some_and(|(source, target)| ResolvedCast::select(&source, &target).is_some())
115    {
116        let (value, resolved) =
117            cast_value_with_resolution_with_control(value, source, target, engine, control)?;
118        return Ok(ScopedCastResult {
119            value,
120            resolved,
121            catalog: None,
122        });
123    }
124    let scope = engine
125        .and_then(EngineHook::catalog_cast_scope)
126        .filter(|_| fixed_name(target) && source.is_none_or(fixed_name))
127        .cloned();
128    let types = CastTypes::resolve(source, target, engine, control)?;
129    let mut resolved = None;
130    let value = cast_with_resolved_types(
131        value,
132        source,
133        target,
134        engine,
135        control,
136        &types,
137        &mut resolved,
138    )?;
139    // A domain/input callback can change the hook's catalog. Its already evaluated result remains valid, but the earlier names must not be published under the new identity.
140    let scope = scope.filter(|scope| {
141        engine
142            .and_then(EngineHook::catalog_cast_scope)
143            .is_some_and(|current| scope.matches(current))
144    });
145    let catalog = if let Some(scope) = scope {
146        match control.reserve(std::mem::size_of::<RetainedCatalogCast>()) {
147            Ok(memory) => Some(Box::new(RetainedCatalogCast {
148                scope,
149                types,
150                _memory: memory,
151            })),
152            Err(uqa_core::ValueRetentionError::Memory(_)) => None,
153            Err(error) => return Err(error.into()),
154        }
155    } else {
156        None
157    };
158    Ok(ScopedCastResult {
159        value,
160        resolved,
161        catalog,
162    })
163}
164
165fn fixed_name(name: &str) -> bool {
166    crate::ast::UserTypeIdentity::parse(name).is_some()
167        || crate::parse_regtype_name(name)
168            .ok()
169            .flatten()
170            .is_some_and(|name| name.names.len() == 2)
171}
172
173#[cfg(test)]
174mod tests;