Skip to main content

uqa_sql/catalog/index/
relationships.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Constraint ownership and index partition ancestry are independent catalog edges.
8
9use super::IndexDefinition;
10use crate::ast::{ColumnDef, Expr, IndexKey, TableKeyConstraint, TableKeyConstraintKind};
11use crate::schema::constraint_metadata::{ConstraintMetadataError, ConstraintMetadataResult};
12
13#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
14#[serde(deny_unknown_fields)]
15pub struct IndexRelationships {
16    #[serde(default, skip_serializing_if = "Option::is_none")]
17    pub owning_constraint: Option<[u8; 16]>,
18    #[serde(default, skip_serializing_if = "Option::is_none")]
19    pub parent_index: Option<[u8; 16]>,
20}
21
22impl IndexRelationships {
23    pub fn is_empty(&self) -> bool {
24        self.owning_constraint.is_none() && self.parent_index.is_none()
25    }
26
27    pub fn validate(&self, index: [u8; 16]) -> ConstraintMetadataResult<()> {
28        if [self.owning_constraint, self.parent_index]
29            .into_iter()
30            .flatten()
31            .any(|target| target == [0; 16] || target == index)
32        {
33            return Err(ConstraintMetadataError::Invalid(
34                "invalid index ownership or parent identity".into(),
35            ));
36        }
37        Ok(())
38    }
39}
40
41pub struct IndexAttachmentShape<'a> {
42    pub method: &'a str,
43    pub keys: &'a [IndexKey],
44    pub definition: &'a IndexDefinition,
45    pub constraint_kind: Option<TableKeyConstraintKind>,
46}
47
48impl IndexDefinition {
49    pub fn for_constraint(
50        constraint: &TableKeyConstraint,
51        columns: &[ColumnDef],
52    ) -> ConstraintMetadataResult<Self> {
53        let owner = constraint.catalog_identity.ok_or_else(|| {
54            ConstraintMetadataError::Invalid("index owner has no constraint identity".into())
55        })?;
56        if !owner.is_valid() {
57            return Err(ConstraintMetadataError::Invalid(
58                "index owner has an invalid identity".into(),
59            ));
60        }
61        let key_types = constraint
62            .columns
63            .iter()
64            .map(|name| {
65                columns
66                    .iter()
67                    .find(|column| column.name == *name)
68                    .map(|column| column.ty.clone())
69                    .ok_or_else(|| {
70                        ConstraintMetadataError::Invalid(format!(
71                            "constraint index references missing column `{name}`"
72                        ))
73                    })
74            })
75            .collect::<ConstraintMetadataResult<_>>()?;
76        Ok(Self {
77            relationships: IndexRelationships {
78                owning_constraint: Some(owner.object_id),
79                parent_index: None,
80            },
81            key_names: crate::schema::indexes::keys::key_names(
82                &crate::schema::indexes::names::constraint_index_attributes(constraint),
83            ),
84            key_types,
85            included_columns: constraint.included_columns.clone(),
86            unique: true,
87            nulls_not_distinct: constraint.nulls_not_distinct,
88            ..Self::default()
89        })
90    }
91}
92
93/// A constraint-owned parent requires a same-kind child constraint; an independent parent can attach either an independent or constraint-owned child index. Object identities, physical namespaces and display names are not index-shape properties.
94pub fn can_attach_index(
95    parent: &IndexAttachmentShape<'_>,
96    child: &IndexAttachmentShape<'_>,
97) -> bool {
98    parent
99        .constraint_kind
100        .is_none_or(|kind| child.constraint_kind == Some(kind))
101        && parent.method.eq_ignore_ascii_case(child.method)
102        && same_index_keys(parent.keys, child.keys)
103        && parent.definition.unique == child.definition.unique
104        && parent.definition.nulls_not_distinct == child.definition.nulls_not_distinct
105        && parent.definition.included_columns == child.definition.included_columns
106        && same_index_predicate(
107            parent.definition.predicate.as_deref(),
108            child.definition.predicate.as_deref(),
109        )
110        && (0..parent.keys.len()).all(|position| {
111            parent
112                .definition
113                .column_order
114                .get(position)
115                .copied()
116                .unwrap_or_default()
117                == child
118                    .definition
119                    .column_order
120                    .get(position)
121                    .copied()
122                    .unwrap_or_default()
123        })
124}
125
126/// Whether two key lists index the same columns and expressions, apart from the input collations their calls record.
127#[must_use]
128pub fn same_index_keys(left: &[IndexKey], right: &[IndexKey]) -> bool {
129    left.len() == right.len()
130        && left.iter().zip(right).all(|pair| match pair {
131            (IndexKey::Column(left), IndexKey::Column(right)) => left == right,
132            (IndexKey::Expression(left), IndexKey::Expression(right)) => {
133                crate::catalog::stored_ast::same_stored_expression(left, right)
134            }
135            _ => false,
136        })
137}
138
139/// Whether two partial-index predicates are the same, apart from the input collations their calls record.
140#[must_use]
141pub fn same_index_predicate(left: Option<&Expr>, right: Option<&Expr>) -> bool {
142    match (left, right) {
143        (None, None) => true,
144        (Some(left), Some(right)) => {
145            crate::catalog::stored_ast::same_stored_expression(left, right)
146        }
147        _ => false,
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154
155    #[test]
156    fn constraint_ownership_controls_attachment_in_only_the_parent_direction() {
157        let definition = IndexDefinition {
158            unique: true,
159            ..IndexDefinition::default()
160        };
161        let keys = [IndexKey::Column("k".into())];
162        let shape = |constraint_kind| IndexAttachmentShape {
163            method: "btree",
164            keys: &keys,
165            definition: &definition,
166            constraint_kind,
167        };
168        use TableKeyConstraintKind::{PrimaryKey, Unique};
169        for parent in [None, Some(PrimaryKey), Some(Unique)] {
170            for child in [None, Some(PrimaryKey), Some(Unique)] {
171                assert_eq!(
172                    can_attach_index(&shape(parent), &shape(child)),
173                    parent.is_none() || parent == child,
174                    "parent {parent:?}, child {child:?}"
175                );
176            }
177        }
178        let other = [IndexKey::Column("other".into())];
179        let mut child = shape(None);
180        child.keys = &other;
181        assert!(!can_attach_index(&shape(None), &child));
182    }
183
184    #[test]
185    fn index_edges_reject_zero_and_self_references_and_remain_independent() {
186        let valid = IndexRelationships {
187            owning_constraint: Some([1; 16]),
188            parent_index: Some([2; 16]),
189        };
190        valid.validate([3; 16]).unwrap();
191        for invalid in [[0; 16], [3; 16]] {
192            for relationships in [
193                IndexRelationships {
194                    owning_constraint: Some(invalid),
195                    ..valid.clone()
196                },
197                IndexRelationships {
198                    parent_index: Some(invalid),
199                    ..valid.clone()
200                },
201            ] {
202                assert!(relationships.validate([3; 16]).is_err());
203            }
204        }
205        let detached = IndexRelationships {
206            parent_index: None,
207            ..valid
208        };
209        assert_eq!(detached.owning_constraint, Some([1; 16]));
210        assert!(!detached.is_empty());
211    }
212}