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;
19
20/// Type metadata and enum support used to observe already admitted SQL values. Implementations borrow one statement catalog generation and never invoke type input.
21pub trait SQLValueCatalog {
22    /// 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.
23    fn value_range_type(
24        &self,
25        _oid: u32,
26    ) -> Result<Option<Arc<super::range::RangeValueDescriptor>>> {
27        Ok(None)
28    }
29
30    /// 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.
31    fn compare_range_bounds(
32        &self,
33        _range_oid: u32,
34        _left: &Value,
35        _right: &Value,
36        _control: &ProductionControl<'_>,
37    ) -> Result<std::cmp::Ordering> {
38        Err(super::SQLError::Internal(
39            "selected range comparison support is unavailable".into(),
40        ))
41    }
42
43    /// 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.
44    fn range_bound_equality_key(
45        &self,
46        _range_oid: u32,
47        _value: &Value,
48        _control: &ProductionControl<'_>,
49    ) -> Result<Produced<Vec<u8>>> {
50        Err(super::SQLError::Internal(
51            "selected range equality-key support is unavailable".into(),
52        ))
53    }
54
55    /// The declared type for a physical OID, including domains, arrays and composites.
56    fn value_type_by_oid(&self, _oid: u32) -> Result<Option<crate::ColumnType>> {
57        Ok(None)
58    }
59
60    /// 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.
61    fn value_type_exists(&self, oid: u32) -> Result<bool> {
62        Ok(self.value_type_by_oid(oid)?.is_some())
63    }
64
65    /// Current SQL spelling of an admitted catalog OID alias; `None` retains numeric output.
66    fn value_regtype_output(&self, _ty: &crate::ColumnType, _oid: i64) -> Result<Option<String>> {
67        Ok(None)
68    }
69
70    /// The current descriptor of an admitted composite value.
71    fn value_composite_type(
72        &self,
73        _oid: u32,
74    ) -> Result<Option<Arc<super::composites::CompositeTypeDescriptor>>> {
75        Ok(None)
76    }
77
78    /// The session's comparison support functions, shared by declared type across nested array and record calls. Pure catalog readers do not own runtime state.
79    fn enum_type_comparison_states(&self) -> Option<&EnumTypeComparisonStates> {
80        None
81    }
82
83    /// The labels of one enum type in the statement's catalog generation, or `None` when the catalog has no such type.
84    fn enum_type_labels(&self, type_oid: u32) -> Result<Option<Arc<EnumTypeLabels>>>;
85
86    /// 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.
87    fn enum_value_by_oid(&self, _label_oid: u32) -> Result<Option<EnumValue>> {
88        Ok(None)
89    }
90
91    /// 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.
92    fn enum_label_position(&self, _label_oid: u32) -> Result<Option<(u32, usize)>> {
93        Ok(None)
94    }
95
96    /// Whether the current transaction added this label to a type that it did not create. `PostgreSQL` rejects such a label until the transaction commits.
97    fn enum_label_uncommitted(&self, label_oid: u32) -> bool;
98
99    /// `format_type_be` of the type, which qualifies a type hidden by the search path.
100    fn enum_type_name(&self, type_oid: u32) -> Result<Option<String>>;
101
102    /// Whether the statement catalog defines any enum type; binding skips enum literal validation otherwise.
103    fn has_enum_types(&self) -> bool;
104}
105
106/// Adapt a scalar context without requiring embedders that only provide domain or composite metadata to implement enum support.
107pub struct EngineValueCatalog<'a>(pub &'a dyn super::EngineHook);
108
109impl SQLValueCatalog for EngineValueCatalog<'_> {
110    fn compare_range_bounds(
111        &self,
112        range_oid: u32,
113        left: &Value,
114        right: &Value,
115        control: &ProductionControl<'_>,
116    ) -> Result<std::cmp::Ordering> {
117        self.0
118            .enum_labels()
119            .ok_or_else(|| {
120                super::SQLError::Internal("selected range comparison support is unavailable".into())
121            })?
122            .compare_range_bounds(range_oid, left, right, control)
123    }
124
125    fn range_bound_equality_key(
126        &self,
127        range_oid: u32,
128        value: &Value,
129        control: &ProductionControl<'_>,
130    ) -> Result<Produced<Vec<u8>>> {
131        self.0
132            .enum_labels()
133            .ok_or_else(|| {
134                super::SQLError::Internal(
135                    "selected range equality-key support is unavailable".into(),
136                )
137            })?
138            .range_bound_equality_key(range_oid, value, control)
139    }
140
141    fn value_range_type(
142        &self,
143        oid: u32,
144    ) -> Result<Option<Arc<super::range::RangeValueDescriptor>>> {
145        self.0
146            .enum_labels()
147            .map(|catalog| catalog.value_range_type(oid))
148            .transpose()
149            .map(Option::flatten)
150    }
151
152    fn value_regtype_output(&self, ty: &crate::ColumnType, oid: i64) -> Result<Option<String>> {
153        self.0
154            .resolve_regtype_output(ty, oid)
155            .map_err(crate::SQLError::Internal)
156    }
157
158    fn value_type_by_oid(&self, oid: u32) -> Result<Option<crate::ColumnType>> {
159        self.0
160            .resolve_type_oid(oid)
161            .map_err(crate::SQLError::Internal)
162    }
163
164    fn value_type_exists(&self, oid: u32) -> Result<bool> {
165        self.0
166            .type_oid_exists(oid)
167            .map_err(crate::SQLError::Internal)
168    }
169
170    fn value_composite_type(
171        &self,
172        oid: u32,
173    ) -> Result<Option<Arc<super::composites::CompositeTypeDescriptor>>> {
174        self.0
175            .composite_types()
176            .map(|catalog| catalog.composite_type(oid))
177            .transpose()
178            .map(Option::flatten)
179    }
180
181    fn enum_type_comparison_states(&self) -> Option<&EnumTypeComparisonStates> {
182        self.0.enum_labels()?.enum_type_comparison_states()
183    }
184
185    fn enum_type_labels(&self, oid: u32) -> Result<Option<Arc<EnumTypeLabels>>> {
186        self.0
187            .enum_labels()
188            .map(|catalog| catalog.enum_type_labels(oid))
189            .transpose()
190            .map(Option::flatten)
191    }
192
193    fn enum_value_by_oid(&self, oid: u32) -> Result<Option<EnumValue>> {
194        self.0
195            .enum_labels()
196            .map(|catalog| catalog.enum_value_by_oid(oid))
197            .transpose()
198            .map(Option::flatten)
199    }
200
201    fn enum_label_position(&self, oid: u32) -> Result<Option<(u32, usize)>> {
202        self.0
203            .enum_labels()
204            .map(|catalog| catalog.enum_label_position(oid))
205            .transpose()
206            .map(Option::flatten)
207    }
208
209    fn enum_label_uncommitted(&self, oid: u32) -> bool {
210        self.0
211            .enum_labels()
212            .is_some_and(|catalog| catalog.enum_label_uncommitted(oid))
213    }
214
215    fn enum_type_name(&self, oid: u32) -> Result<Option<String>> {
216        self.0
217            .enum_labels()
218            .map(|catalog| catalog.enum_type_name(oid))
219            .transpose()
220            .map(Option::flatten)
221    }
222
223    fn has_enum_types(&self) -> bool {
224        self.0
225            .enum_labels()
226            .is_some_and(SQLValueCatalog::has_enum_types)
227    }
228}