Skip to main content

uqa_sql/expr/
value_catalog.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Borrowed catalog identities and comparison support for SQL value consumers.
8
9use super::enums::{EnumTypeComparisonStates, EnumTypeLabels};
10use super::Result;
11use std::sync::Arc;
12use uqa_core::{
13    memory::{Produced, ProductionControl},
14    EnumValue, Value,
15};
16
17mod records;
18pub use records::SQLRecordFields;
19mod record_view;
20pub use record_view::SQLRecordView;
21mod types;
22pub(crate) use types::field_type_with_control;
23pub(crate) use types::type_by_oid_with_control;
24
25pub(crate) struct ValueCompositeCatalog<'a>(pub(crate) Option<&'a dyn SQLValueCatalog>);
26
27impl super::composites::CompositeTypeCatalog for ValueCompositeCatalog<'_> {
28    fn composite_type(
29        &self,
30        oid: u32,
31    ) -> Result<Option<Arc<super::composites::CompositeTypeDescriptor>>> {
32        self.0
33            .ok_or_else(|| {
34                crate::SQLError::Internal("composite operator lookup has no catalog".into())
35            })?
36            .value_composite_type(oid)
37    }
38}
39
40/// Type metadata and enum support used to observe already admitted SQL values. Implementations borrow one statement catalog generation and never invoke type input.
41pub trait SQLValueCatalog {
42    /// The selected endpoint layout of a range or multirange in this statement generation. Observation does not execute input, domain checks or a canonical support function.
43    fn value_range_type(
44        &self,
45        _oid: u32,
46    ) -> Result<Option<Arc<super::range::RangeValueDescriptor>>> {
47        Ok(None)
48    }
49
50    /// Compare admitted bounds with the range's captured operator class and collation. Invocation state belongs to the support-function owner; this operation must not perform endpoint input or range canonicalization.
51    fn compare_range_bounds(
52        &self,
53        _range_oid: u32,
54        _left: &Value,
55        _right: &Value,
56        _control: &ProductionControl<'_>,
57    ) -> Result<std::cmp::Ordering> {
58        Err(super::SQLError::Internal(
59            "selected range comparison support is unavailable".into(),
60        ))
61    }
62
63    /// Return an admitted exact equality key for one finite bound under the same selected operation. Keys must coincide exactly when `compare_range_bounds` returns Equal; an ordinary hash is not an exact key. Execution owns this encoding and any selected normalization.
64    fn range_bound_equality_key(
65        &self,
66        _range_oid: u32,
67        _value: &Value,
68        _control: &ProductionControl<'_>,
69    ) -> Result<Produced<Vec<u8>>> {
70        Err(super::SQLError::Internal(
71            "selected range equality-key support is unavailable".into(),
72        ))
73    }
74
75    /// The declared type for a physical OID, including domains, arrays and composites.
76    fn value_type_by_oid(&self, _oid: u32) -> Result<Option<crate::ColumnType>> {
77        Ok(None)
78    }
79
80    /// Whether an admitted physical OID names any current catalog type, including pseudo-types without a value carrier. This lookup does not check input privileges or execute type input.
81    fn value_type_exists(&self, oid: u32) -> Result<bool> {
82        Ok(self.value_type_by_oid(oid)?.is_some())
83    }
84
85    /// Current SQL spelling of an admitted catalog OID alias; `None` retains numeric output.
86    fn value_regtype_output(&self, _ty: &crate::ColumnType, _oid: i64) -> Result<Option<String>> {
87        Ok(None)
88    }
89
90    /// The current descriptor of an admitted composite value.
91    fn value_composite_type(
92        &self,
93        _oid: u32,
94    ) -> Result<Option<Arc<super::composites::CompositeTypeDescriptor>>> {
95        Ok(None)
96    }
97
98    /// The session's comparison support functions, shared by declared type across nested array and record calls. Pure catalog readers do not own runtime state.
99    fn enum_type_comparison_states(&self) -> Option<&EnumTypeComparisonStates> {
100        None
101    }
102
103    /// The labels of one enum type in the statement's catalog generation, or `None` when the catalog has no such type.
104    fn enum_type_labels(&self, type_oid: u32) -> Result<Option<Arc<EnumTypeLabels>>>;
105
106    /// Resolve an already admitted physical label OID across enum types. Output uses the label's actual identity even if a retained tuple now declares another enum type; it does not repeat input safety checks.
107    fn enum_value_by_oid(&self, _label_oid: u32) -> Result<Option<EnumValue>> {
108        Ok(None)
109    }
110
111    /// The actual enum type and zero-based label position of an admitted physical OID in this generation. Positions have declaration/key order and avoid copying label keys for comparison.
112    fn enum_label_position(&self, _label_oid: u32) -> Result<Option<(u32, usize)>> {
113        Ok(None)
114    }
115
116    /// Whether the current transaction added this label to a type that it did not create. `PostgreSQL` rejects such a label until the transaction commits.
117    fn enum_label_uncommitted(&self, label_oid: u32) -> bool;
118
119    /// `format_type_be` of the type, which qualifies a type hidden by the search path.
120    fn enum_type_name(&self, type_oid: u32) -> Result<Option<String>>;
121
122    /// Whether the statement catalog defines any enum type; binding skips enum literal validation otherwise.
123    fn has_enum_types(&self) -> bool;
124}
125
126/// Adapt a scalar context without requiring embedders that only provide domain or composite metadata to implement enum support.
127pub struct EngineValueCatalog<'a>(pub &'a dyn super::EngineHook);
128
129impl SQLValueCatalog for EngineValueCatalog<'_> {
130    fn compare_range_bounds(
131        &self,
132        range_oid: u32,
133        left: &Value,
134        right: &Value,
135        control: &ProductionControl<'_>,
136    ) -> Result<std::cmp::Ordering> {
137        self.0
138            .enum_labels()
139            .ok_or_else(|| {
140                super::SQLError::Internal("selected range comparison support is unavailable".into())
141            })?
142            .compare_range_bounds(range_oid, left, right, control)
143    }
144
145    fn range_bound_equality_key(
146        &self,
147        range_oid: u32,
148        value: &Value,
149        control: &ProductionControl<'_>,
150    ) -> Result<Produced<Vec<u8>>> {
151        self.0
152            .enum_labels()
153            .ok_or_else(|| {
154                super::SQLError::Internal(
155                    "selected range equality-key support is unavailable".into(),
156                )
157            })?
158            .range_bound_equality_key(range_oid, value, control)
159    }
160
161    fn value_range_type(
162        &self,
163        oid: u32,
164    ) -> Result<Option<Arc<super::range::RangeValueDescriptor>>> {
165        self.0
166            .enum_labels()
167            .map(|catalog| catalog.value_range_type(oid))
168            .transpose()
169            .map(Option::flatten)
170    }
171
172    fn value_regtype_output(&self, ty: &crate::ColumnType, oid: i64) -> Result<Option<String>> {
173        self.0
174            .resolve_regtype_output(ty, oid)
175            .map_err(crate::SQLError::Internal)
176    }
177
178    fn value_type_by_oid(&self, oid: u32) -> Result<Option<crate::ColumnType>> {
179        self.0
180            .resolve_type_oid(oid)
181            .map_err(crate::SQLError::Internal)
182    }
183
184    fn value_type_exists(&self, oid: u32) -> Result<bool> {
185        self.0
186            .type_oid_exists(oid)
187            .map_err(crate::SQLError::Internal)
188    }
189
190    fn value_composite_type(
191        &self,
192        oid: u32,
193    ) -> Result<Option<Arc<super::composites::CompositeTypeDescriptor>>> {
194        self.0
195            .composite_types()
196            .map(|catalog| catalog.composite_type(oid))
197            .transpose()
198            .map(Option::flatten)
199    }
200
201    fn enum_type_comparison_states(&self) -> Option<&EnumTypeComparisonStates> {
202        self.0.enum_labels()?.enum_type_comparison_states()
203    }
204
205    fn enum_type_labels(&self, oid: u32) -> Result<Option<Arc<EnumTypeLabels>>> {
206        self.0
207            .enum_labels()
208            .map(|catalog| catalog.enum_type_labels(oid))
209            .transpose()
210            .map(Option::flatten)
211    }
212
213    fn enum_value_by_oid(&self, oid: u32) -> Result<Option<EnumValue>> {
214        self.0
215            .enum_labels()
216            .map(|catalog| catalog.enum_value_by_oid(oid))
217            .transpose()
218            .map(Option::flatten)
219    }
220
221    fn enum_label_position(&self, oid: u32) -> Result<Option<(u32, usize)>> {
222        self.0
223            .enum_labels()
224            .map(|catalog| catalog.enum_label_position(oid))
225            .transpose()
226            .map(Option::flatten)
227    }
228
229    fn enum_label_uncommitted(&self, oid: u32) -> bool {
230        self.0
231            .enum_labels()
232            .is_some_and(|catalog| catalog.enum_label_uncommitted(oid))
233    }
234
235    fn enum_type_name(&self, oid: u32) -> Result<Option<String>> {
236        self.0
237            .enum_labels()
238            .map(|catalog| catalog.enum_type_name(oid))
239            .transpose()
240            .map(Option::flatten)
241    }
242
243    fn has_enum_types(&self) -> bool {
244        self.0
245            .enum_labels()
246            .is_some_and(SQLValueCatalog::has_enum_types)
247    }
248}