Skip to main content

uqa_execution/schema/
keys.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Verify newly declared keys and generated replacement rows against visible physical data.
8use super::hierarchy::HierarchyCatalog;
9use super::{columns::rows::RewriteRows, indexes::IndexBuildKeys};
10use crate::mutation::constraints::context::ConstraintContext;
11use uqa_core::Value;
12use uqa_sql::SQLError;
13pub struct KeyValidationContext<'a> {
14    pub catalog: &'a dyn HierarchyCatalog,
15    pub constraints: ConstraintContext<'a>,
16}
17fn ddl_storage_error(action: &str, error: uqa_storage::StorageBackendError) -> SQLError {
18    uqa_sql::catalog::errors::storage_error(action, &error)
19}
20/// Check the key constraints of `table` across the rows a rewrite produced, as rebuilding their indexes does: a NULL in a primary key column reports the column's NOT NULL violation, and a repeated key `could not create unique index` with the repeated key.
21pub fn validate_key_constraint_rows(
22    context: &KeyValidationContext<'_>,
23    table: &str,
24    rows: &mut RewriteRows,
25) -> Result<(), SQLError> {
26    rows.spill()?;
27    for constraint in context
28        .catalog
29        .try_key_constraints(table)
30        .map_err(|error| ddl_storage_error("table rewrite", error))?
31    {
32        if constraint.without_overlaps {
33            continue;
34        }
35        let mut keys = IndexBuildKeys::new(
36            constraint.columns.len(),
37            context.constraints.memory.work_mem_bytes()?,
38        );
39        for position in 0..rows.len() {
40            let document = rows.get(position)?.document;
41            let values = constraint
42                .columns
43                .iter()
44                .map(|column| document.get(column).cloned().unwrap_or(Value::Null))
45                .collect::<Vec<_>>();
46            if constraint.kind == uqa_sql::ast::TableKeyConstraintKind::PrimaryKey {
47                if let Some(column) = constraint
48                    .columns
49                    .iter()
50                    .zip(&values)
51                    .find_map(|(column, value)| matches!(value, Value::Null).then_some(column))
52                {
53                    return Err(null_key_column(table, column));
54                }
55            }
56            if constraint.kind == uqa_sql::ast::TableKeyConstraintKind::Unique
57                && values.iter().any(|value| matches!(value, Value::Null))
58                && !constraint.nulls_not_distinct
59            {
60                continue;
61            }
62            keys.push(values)?;
63        }
64        if let Some(values) = keys.first_duplicate(
65            true,
66            constraint.nulls_not_distinct,
67            Some(context.constraints.values),
68        )? {
69            return Err(duplicated_key(context, table, &constraint, &values)?);
70        }
71    }
72    Ok(())
73}
74
75/// Check the `WITHOUT OVERLAPS` keys of `table` across its stored rows, once a rewrite has written them; their overlap is not an equality of key values.
76pub fn validate_temporal_key_rows(
77    context: &KeyValidationContext<'_>,
78    table: &str,
79) -> Result<(), SQLError> {
80    for constraint in context
81        .catalog
82        .try_key_constraints(table)
83        .map_err(|error| ddl_storage_error("table rewrite", error))?
84    {
85        if constraint.without_overlaps {
86            validate_key_index_rows(context, table, &constraint)?;
87        }
88    }
89    Ok(())
90}
91
92/// The error of a key constraint whose index finds a repeated key.
93fn duplicated_key(
94    context: &KeyValidationContext<'_>,
95    table: &str,
96    constraint: &uqa_sql::ast::TableKeyConstraint,
97    values: &[Value],
98) -> Result<SQLError, SQLError> {
99    Ok(super::indexes::unique_build::duplicated_index_key(
100        index_name(constraint)?,
101        crate::mutation::constraints::enforced_key_description(
102            context.constraints,
103            table,
104            &constraint.clone().into(),
105            values,
106        )?,
107    ))
108}
109
110fn index_name(constraint: &uqa_sql::ast::TableKeyConstraint) -> Result<&str, SQLError> {
111    constraint
112        .name
113        .as_deref()
114        .ok_or_else(|| SQLError::Internal("key validation requires its reserved index name".into()))
115}
116
117/// Check the rows of `table` as building a key's index does: a repeated key fails as `could not create unique index` with the index's name, and a `WITHOUT OVERLAPS` key fails on overlapping periods. A key value with a NULL never repeats unless the key treats NULLs as not distinct.
118pub fn validate_key_index_rows(
119    context: &KeyValidationContext<'_>,
120    table: &str,
121    constraint: &uqa_sql::ast::TableKeyConstraint,
122) -> Result<(), SQLError> {
123    if constraint.without_overlaps {
124        for doc_id in context.constraints.reads.live_table_doc_ids(table)? {
125            let Some(document) = context.constraints.reads.get_document(table, doc_id)? else {
126                continue;
127            };
128            if crate::mutation::constraints::without_overlaps_conflict(
129                context.constraints,
130                table,
131                constraint,
132                &document,
133                Some(doc_id),
134            )? {
135                return Err(SQLError::Routine {
136                    sqlstate: "23P01".into(),
137                    message: format!(
138                        "could not create constraint because relation \"{table}\" contains overlapping key values"
139                    ),
140                });
141            }
142        }
143        return Ok(());
144    }
145    let columns = context
146        .catalog
147        .try_describe_table(table)
148        .map_err(|error| ddl_storage_error("unique index build", error))?
149        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
150    let key_types = constraint
151        .columns
152        .iter()
153        .map(|name| {
154            columns
155                .iter()
156                .find(|column| column.name == *name)
157                .map(|column| column.ty.clone())
158                .ok_or_else(|| SQLError::UnknownColumn(name.clone()))
159        })
160        .collect::<Result<Vec<_>, _>>()?;
161    let keys = constraint
162        .columns
163        .iter()
164        .cloned()
165        .map(uqa_sql::ast::IndexKey::Column)
166        .collect::<Vec<_>>();
167    super::indexes::unique_build::validate_unique_index_build(
168        super::indexes::unique_build::UniqueBuildContext::of(&context.constraints),
169        &super::indexes::unique_build::UniqueIndexBuild {
170            table,
171            name: index_name(constraint)?,
172            keys: &keys,
173            key_types: &key_types,
174            predicate: None,
175            nulls_not_distinct: constraint.nulls_not_distinct,
176        },
177    )
178}
179
180/// Check the NOT NULL constraints that a primary key gives its columns, after its index is built, as `PostgreSQL` verifies new NOT NULL constraints once the table's other changes are done: the first row holding a NULL in a key column fails on the first such column of the table.
181pub fn validate_primary_key_rows(
182    context: &KeyValidationContext<'_>,
183    table: &str,
184    constraint: &uqa_sql::ast::TableKeyConstraint,
185) -> Result<(), SQLError> {
186    if constraint.kind != uqa_sql::ast::TableKeyConstraintKind::PrimaryKey {
187        return Ok(());
188    }
189    let columns = context
190        .catalog
191        .try_describe_table(table)
192        .map_err(|error| ddl_storage_error("ALTER TABLE ADD CONSTRAINT", error))?
193        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?
194        .into_iter()
195        .map(|column| column.name)
196        .filter(|column| constraint.columns.contains(column))
197        .collect::<Vec<_>>();
198    for doc_id in context.constraints.reads.live_table_doc_ids(table)? {
199        let Some(document) = context.constraints.reads.get_document(table, doc_id)? else {
200            continue;
201        };
202        if let Some(column) = columns.iter().find(|column| {
203            matches!(
204                document.get(column.as_str()).unwrap_or(&Value::Null),
205                Value::Null
206            )
207        }) {
208            return Err(null_key_column(table, column));
209        }
210    }
211    Ok(())
212}
213
214/// `column "a" of relation "t" contains null values`, for a NOT NULL constraint that a row violates.
215fn null_key_column(table: &str, column: &str) -> SQLError {
216    let relation = uqa_core::RelationIdentity::from_legacy_name(table)
217        .map_or_else(|_| table.to_string(), |identity| identity.name);
218    SQLError::Routine {
219        sqlstate: "23502".into(),
220        message: format!("column \"{column}\" of relation \"{relation}\" contains null values"),
221    }
222}