Skip to main content

uqa_sql/expr/binary/
btree.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Selected B-tree inputs share admitted carriers without repeating input conversion.
8
9use crate::{
10    catalog::{index::operator_classes, type_metadata},
11    expr::{composites, datums, SQLValueCatalog},
12    ColumnType, SQLError,
13};
14use uqa_core::{memory::ProductionControl, ArrayValue, Value};
15
16/// A borrowed input in the selected class's equality domain. Arrays retain their shape even when the original carrier is an atomic catalog vector. Image records keep a distinct observation contract.
17pub enum BTreeInput<'a> {
18    Value(&'a Value, &'a ColumnType),
19    Array(&'a ArrayValue),
20    RecordImage(&'a Value),
21}
22
23/// Observe one already admitted bound under its selected class. The callback cannot outlive physical decoding or a required carrier projection; unchanged values and vector arrays are borrowed. Collation and support invocation remain the consuming operation's responsibility.
24pub fn with_btree_input<R>(
25    binding: operator_classes::BoundBTreeOperatorClass<'_>,
26    value: &Value,
27    catalog: Option<&dyn SQLValueCatalog>,
28    control: &ProductionControl<'_>,
29    observe: impl FnOnce(BTreeInput<'_>) -> Result<R, SQLError>,
30) -> Result<R, SQLError> {
31    control.check()?;
32    let observe = |input: BTreeInput<'_>| {
33        let result = observe(input)?;
34        control.check()?;
35        Ok(result)
36    };
37    let class = binding.class();
38    if operator_classes::builtin_btree_operator_class(class.oid) != Some(class) {
39        return Err(invalid());
40    }
41    let mut source = binding.declared_type();
42    while let ColumnType::Domain { base, .. } = source {
43        control.check()?;
44        source = base;
45    }
46    if matches!(value, Value::Null) {
47        return observe(BTreeInput::Value(value, source));
48    }
49    // Domain coercion is binary: selected support receives the base Datum, including when its input type is polymorphic and has no concrete catalog OID.
50    let domain_input;
51    let value = if let Value::Datum(datum) = value {
52        if matches!(binding.declared_type(), ColumnType::Domain { .. }) {
53            let oid = u32::try_from(type_metadata::pg_type_oid(source)).map_err(|_| invalid())?;
54            domain_input = Value::Datum(datum.field(oid, datum.offset()));
55            &domain_input
56        } else {
57            value
58        }
59    } else {
60        value
61    };
62    if class.comparison_kind() == operator_classes::BuiltinBTreeComparison::RecordImage {
63        return observe(BTreeInput::RecordImage(value));
64    }
65    if type_metadata::routine_pseudo_type_name(i64::from(class.input_type_oid)) == Some("anyarray")
66    {
67        return with_array(value, catalog, control, observe);
68    }
69    let Some(target) = type_metadata::builtin_scalar_type(class.input_type_oid) else {
70        return observe(BTreeInput::Value(value, source));
71    };
72    if matches!(target, ColumnType::Record) {
73        return observe(BTreeInput::Value(value, source));
74    }
75    if let Value::Datum(datum) = value {
76        let selected = Value::Datum(datum.field(class.input_type_oid, datum.offset()));
77        return observe(BTreeInput::Value(&selected, target));
78    }
79    if matches!(target, ColumnType::Bpchar) {
80        if let Value::Str(text) = value {
81            let (text, memory) = control.copy_text(text)?.into_parts();
82            let selected = control.finish(Value::FixedChar(text), memory)?;
83            return observe(BTreeInput::Value(&selected, target));
84        }
85    }
86    if type_metadata::pg_type_by_value(target) {
87        if let Some(selected) = composites::datum::reinterpret(value, source, target) {
88            return observe(BTreeInput::Value(&selected, target));
89        }
90    }
91    observe(BTreeInput::Value(value, target))
92}
93
94/// Invoke the selected native B-tree comparison over admitted inputs. This shares scalar, array and record owners; it does not execute input, domain checks or range canonicalization. Pattern support explicitly ignores the invoking collation, while ordinary record fields retain their own descriptors.
95pub fn compare_btree_inputs_with_catalog_and_control(
96    binding: operator_classes::BoundBTreeOperatorClass<'_>,
97    left: &Value,
98    right: &Value,
99    collation: u32,
100    catalog: Option<&dyn SQLValueCatalog>,
101    control: &ProductionControl<'_>,
102) -> Result<std::cmp::Ordering, SQLError> {
103    compare_btree_inputs_with_invocation_state(
104        binding, left, right, collation, catalog, None, control,
105    )
106}
107
108/// The selected support function's private state is distinct from the shared type support used by nested array and record fields. Its caller retains this state for the support function's lifetime.
109pub fn compare_btree_inputs_with_invocation_state(
110    binding: operator_classes::BoundBTreeOperatorClass<'_>,
111    left: &Value,
112    right: &Value,
113    collation: u32,
114    catalog: Option<&dyn SQLValueCatalog>,
115    state: Option<&crate::expr::enums::EnumComparisonState>,
116    control: &ProductionControl<'_>,
117) -> Result<std::cmp::Ordering, SQLError> {
118    control.check()?;
119    match (matches!(left, Value::Null), matches!(right, Value::Null)) {
120        (true, true) => return Ok(std::cmp::Ordering::Equal),
121        (true, false) => return Ok(std::cmp::Ordering::Greater),
122        (false, true) => return Ok(std::cmp::Ordering::Less),
123        (false, false) => {}
124    }
125    let collation =
126        if binding.class().comparison_kind() == operator_classes::BuiltinBTreeComparison::Pattern {
127            crate::catalog::collations::C_COLLATION_OID
128        } else {
129            collation
130        };
131    with_btree_input(binding, left, catalog, control, |left| {
132        with_btree_input(binding, right, catalog, control, |right| {
133            match (left, right) {
134                (BTreeInput::Value(left, ty), BTreeInput::Value(right, _)) => {
135                    if type_metadata::routine_pseudo_type_name(i64::from(
136                        binding.class().input_type_oid,
137                    )) == Some("anyenum")
138                    {
139                        if let Some(order) = crate::expr::enums::comparison_order(
140                            left, right, catalog, state, false,
141                        )? {
142                            return Ok(order);
143                        }
144                    }
145                    if let Some(order) = super::selected::selected_range_order(
146                        left,
147                        right,
148                        Some(ty),
149                        control,
150                        catalog,
151                    )? {
152                        return Ok(order);
153                    }
154                    super::compare_typed_values_with_catalog_and_collation(
155                        left, right, collation, control, catalog,
156                    )
157                }
158                (BTreeInput::Array(left), BTreeInput::Array(right)) => {
159                    super::comparison::compare_arrays(
160                        left,
161                        right,
162                        control,
163                        catalog,
164                        super::comparison::EnumKeyOrder::Declaration,
165                        collation,
166                    )
167                }
168                (BTreeInput::RecordImage(left), BTreeInput::RecordImage(right)) => {
169                    super::compare_record_images_with_catalog(left, right, catalog, control)
170                }
171                _ => Err(invalid()),
172            }
173        })
174    })
175}
176
177fn with_array<R>(
178    value: &Value,
179    catalog: Option<&dyn SQLValueCatalog>,
180    control: &ProductionControl<'_>,
181    observe: impl FnOnce(BTreeInput<'_>) -> Result<R, SQLError>,
182) -> Result<R, SQLError> {
183    let decoded = if let Value::Datum(datum) = value {
184        Some(datums::read_array_input_with_catalog_and_control(
185            datum, catalog, control,
186        )?)
187    } else {
188        None
189    };
190    let array = match decoded.as_deref().unwrap_or(value) {
191        Value::Array(array) => array,
192        Value::LegacyVector(vector) => vector.as_array(),
193        _ => return Err(invalid()),
194    };
195    observe(BTreeInput::Array(array))
196}
197
198fn invalid() -> SQLError {
199    SQLError::Internal("selected B-tree input lost its admitted class or carrier".into())
200}
201
202#[cfg(test)]
203mod tests;