Skip to main content

uqa_execution/mutation/
identity.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical document identity selection and sequence allocation services.
8use super::{
9    constraints::context::ConstraintCatalog,
10    errors::{dml_storage_error, identifier_storage_error},
11};
12use uqa_core::{DocId, Value};
13use uqa_sql::SQLError;
14use uqa_storage::document_store::Document;
15mod reservation;
16mod source;
17pub use reservation::reserve_document_id;
18pub use source::IdentitySource;
19use uqa_sql::semantics::key_identity::{is_key_document_id, key_document_id};
20
21pub trait MutationIdentifiers {
22    fn allocate_next_id(&self, table: &str) -> Result<DocId, SQLError>;
23    /// Generate an identity for a row of `table` whose integer primary key names none: one at or above `KEY_IDENTITY_LIMIT`, where no key names an identity.
24    fn allocate_unmapped_id(&self, table: &str) -> Result<DocId, SQLError>;
25    /// Whether the single integer primary key of `table` names its rows' identities: each row whose key lies below `KEY_IDENTITY_LIMIT` has the identity equal to its key, and no other row has an identity below the limit. A table that does not keep this, as one an earlier version wrote can fail to, resolves its keys through the key's index.
26    fn maps_integer_keys(&self, table: &str) -> Result<bool, SQLError>;
27    fn advance_next_id(&self, table: &str, doc_id: DocId) -> uqa_storage::StorageBackendResult<()>;
28    fn persist_next_id(&self, table: &str) -> uqa_storage::StorageBackendResult<()>;
29    /// Whether every identity `allocate_next_id` returns for `table` is one no document of the table ever had. That holds where the table reserves identities in its own durable namespace, whose watermark every write of the table raises. A table that draws from another table's namespace, as a partition does, or keeps only a local counter cannot say.
30    fn generates_unused_identities(&self, table: &str) -> Result<bool, SQLError>;
31}
32/// The single integer primary-key column of `table`, whose values name its rows' identities where the table maps them.
33fn integer_primary_key_column(
34    catalog: &dyn ConstraintCatalog,
35    table: &str,
36) -> Result<Option<String>, SQLError> {
37    Ok(catalog
38        .try_describe_table(table)
39        .map_err(|err| dml_storage_error("UPDATE primary key", err))?
40        .and_then(|columns| {
41            columns
42                .into_iter()
43                .find(|column| column.primary_key && column.ty.is_integer())
44                .map(|column| column.name)
45        }))
46}
47
48/// The identity a row holding `document` takes when it arrives in `table`, as an update moving it to another partition does: the one its integer primary key names, or one the table generates for a key that names none. `None` for a table whose key names no identities, which generates one as it does for any row.
49pub fn arriving_key_identity(
50    catalog: &dyn ConstraintCatalog,
51    identifiers: &dyn MutationIdentifiers,
52    table: &str,
53    document: &Document,
54) -> Result<Option<DocId>, SQLError> {
55    let Some(key) = integer_primary_key_column(catalog, table)? else {
56        return Ok(None);
57    };
58    if !identifiers.maps_integer_keys(table)? {
59        return Ok(None);
60    }
61    Ok(Some(match document.get(&key).and_then(key_document_id) {
62        Some(doc_id) => doc_id,
63        None => identifiers.allocate_unmapped_id(table)?,
64    }))
65}
66
67/// The identity an update moves a row of `table` to when `new_document` replaces it: the one its integer primary key names, or, for a key that names none, one the table generates when the row held an identity a key names. `None` keeps the row where it is. The caller decides once for each row and carries the decision to every later stage of the statement.
68pub fn key_relocation(
69    catalog: &dyn ConstraintCatalog,
70    identifiers: &dyn MutationIdentifiers,
71    table: &str,
72    doc_id: DocId,
73    new_document: &Document,
74) -> Result<Option<DocId>, SQLError> {
75    let Some(key) = integer_primary_key_column(catalog, table)? else {
76        return Ok(None);
77    };
78    if !identifiers.maps_integer_keys(table)? {
79        return Ok(None);
80    }
81    let relocated = match new_document.get(&key).and_then(key_document_id) {
82        Some(named) => named,
83        None if is_key_document_id(doc_id) => identifiers.allocate_unmapped_id(table)?,
84        None => return Ok(None),
85    };
86    Ok((relocated != doc_id).then_some(relocated))
87}
88
89/// The identity an inserted row's identity column supplies, if any: an integer key the table maps, or the `id` of a table without declared columns. The caller generates one otherwise.
90pub fn supplied_document_identity(
91    source: IdentitySource,
92    document: &Document,
93    id_column: &str,
94) -> Result<Option<DocId>, SQLError> {
95    Ok(match source {
96        IdentitySource::Generated => None,
97        IdentitySource::IntegerKey => document.get(id_column).and_then(key_document_id),
98        IdentitySource::Document => document_supplied_id(document, id_column),
99    })
100}
101
102use crate::query::locking::context::QueryRowLockSession;
103use uqa_sql::{
104    assignment::{columns::AssignmentColumnCatalog, AssignmentContext},
105    ast::{AutoIncrement, AutoIncrementKind},
106    semantics::{doc_id_value, partition::PartitionCatalog, returning::document_supplied_id},
107};
108pub trait InsertIdentityCatalog {
109    fn auto_increment_column(&self, table: &str) -> Result<Option<String>, String>;
110    fn auto_increment_columns(&self, table: &str) -> Result<Vec<(String, AutoIncrement)>, String>;
111}
112pub trait IdentitySequences {
113    fn nextval_sql(&self, sequence: &str) -> Result<i64, SQLError>;
114}
115#[derive(Clone, Copy)]
116pub struct InsertIdentityContext<'a> {
117    pub catalog: &'a dyn InsertIdentityCatalog,
118    pub columns: &'a dyn AssignmentColumnCatalog,
119    pub assignment: &'a dyn AssignmentContext,
120    pub identifiers: &'a dyn MutationIdentifiers,
121    pub sequences: &'a dyn IdentitySequences,
122    pub locks: &'a dyn QueryRowLockSession,
123    pub partitions: &'a dyn PartitionCatalog,
124}
125pub fn insert_identity_columns(
126    context: InsertIdentityContext<'_>,
127    table: &str,
128    action: &str,
129) -> Result<(Option<String>, String, IdentitySource), SQLError> {
130    let auto_increment = context
131        .catalog
132        .auto_increment_column(table)
133        .map_err(|err| dml_storage_error(action, err))?;
134    let definitions = context
135        .columns
136        .try_describe_table(table)
137        .map_err(|err| dml_storage_error(action, err))?
138        .ok_or_else(|| SQLError::UnknownTable(table.to_string()))?;
139    let primary_keys = definitions
140        .iter()
141        .filter(|column| column.primary_key)
142        .collect::<Vec<_>>();
143    let (id_column, source) = match primary_keys.as_slice() {
144        [key] if key.ty.is_integer() => (key.name.clone(), IdentitySource::IntegerKey),
145        [key] => (key.name.clone(), IdentitySource::Generated),
146        _ if definitions.is_empty() => ("id".into(), IdentitySource::Document),
147        _ => ("id".into(), IdentitySource::Generated),
148    };
149    // Only a key names a row. A SERIAL or identity column that is not the
150    // table's single primary key is an ordinary column with a sequence
151    // default, and two rows may supply the same value to it, so its value
152    // cannot choose the physical document. The conventional `id` field is a
153    // storage identity only for the legacy schema-less document API. A
154    // declared SQL table without a primary key may contain duplicate ordinary
155    // `id` values, so using that field as the physical document key would
156    // silently replace rows.
157    Ok((auto_increment, id_column, source))
158}
159
160/// Generate missing identity values after statement analysis has validated user-supplied targets. A value already produced by a rewritten DEFAULT is retained, including for GENERATED ALWAYS. OVERRIDING USER VALUE removes supplied identity values before this boundary; the row cannot reconstruct their original provenance.
161pub fn prepare_auto_increment_identity(
162    context: InsertIdentityContext<'_>,
163    table: &str,
164    id_column: &str,
165    source: IdentitySource,
166    auto_id_column: Option<&str>,
167    document: &mut Document,
168    action: &str,
169) -> Result<Option<(DocId, bool)>, SQLError> {
170    let Some(auto_id_column) = auto_id_column else {
171        return Ok(None);
172    };
173    let definitions = context
174        .catalog
175        .auto_increment_columns(table)
176        .map_err(|error| dml_storage_error(action, error))?;
177    for (column, provenance) in &definitions {
178        if !provenance.is_identity() {
179            continue;
180        }
181        if document.contains_key(column) {
182            continue;
183        }
184        let sequence =
185            uqa_sql::assignment::columns::identity_column_sequence(context.columns, table, column)?
186                .ok_or_else(|| SQLError::Routine {
187                    sqlstate: "XX000".into(),
188                    message: "no owned sequence found".into(),
189                })?;
190        let value = context.sequences.nextval_sql(&sequence)?;
191        document.insert(
192            column.clone(),
193            uqa_sql::assignment::columns::coerce_to_column_type(
194                context.assignment,
195                context.columns,
196                table,
197                column,
198                Value::Int(value),
199            )?,
200        );
201    }
202    let provenance = definitions
203        .iter()
204        .find(|(column, _)| column == auto_id_column)
205        .map(|(_, provenance)| provenance)
206        .ok_or_else(|| {
207            SQLError::Internal(format!(
208                "auto-increment column `{table}.{auto_id_column}` disappeared"
209            ))
210        })?;
211    if provenance.kind != AutoIncrementKind::Legacy {
212        return Ok(None);
213    }
214    let owner = uqa_sql::semantics::partition::partition_identity_owner(context.partitions, table)?;
215    context
216        .locks
217        .lock_relation(&owner, crate::row_locks::RelationLockMode::RowExclusive)?;
218    if source == IdentitySource::IntegerKey && auto_id_column == id_column {
219        return prepare_insert_identity(
220            context,
221            &owner,
222            id_column,
223            source,
224            Some(auto_id_column),
225            document,
226            action,
227        )
228        .map(Some);
229    }
230    let generated =
231        prepare_legacy_counter_value(context, &owner, auto_id_column, document, action)?;
232    // A table without a key names its rows by generated identities from the same counter, so a generated counter value names its row too and the counter advances once per row.
233    Ok(generated
234        .filter(|_| !source.accepts_supplied())
235        .map(|value| (value, false)))
236}
237
238/// Draw a missing value of a legacy counter column that is not the row's key from the table counter, which a supplied value advances past, and return the value drawn.
239fn prepare_legacy_counter_value(
240    context: InsertIdentityContext<'_>,
241    owner: &str,
242    column: &str,
243    document: &mut Document,
244    action: &str,
245) -> Result<Option<DocId>, SQLError> {
246    match document.get(column) {
247        None | Some(Value::Null) => {
248            let value = context.identifiers.allocate_next_id(owner)?;
249            document.insert(column.to_string(), doc_id_value(value)?);
250            Ok(Some(value))
251        }
252        Some(Value::Int(value)) => {
253            if let Ok(value) = DocId::try_from(*value) {
254                context
255                    .identifiers
256                    .advance_next_id(owner, value)
257                    .map_err(|error| identifier_storage_error(action, &error))?;
258            }
259            Ok(None)
260        }
261        Some(_) => Ok(None),
262    }
263}
264
265pub fn persist_auto_increment_identity(
266    context: InsertIdentityContext<'_>,
267    table: &str,
268    auto_id_column: Option<&str>,
269    action: &str,
270) -> Result<(), SQLError> {
271    let Some(auto_id_column) = auto_id_column else {
272        return Ok(());
273    };
274    let legacy = context
275        .catalog
276        .auto_increment_columns(table)
277        .map_err(|error| dml_storage_error(action, error))?
278        .into_iter()
279        .find(|(column, _)| column == auto_id_column)
280        .is_some_and(|(_, provenance)| provenance.kind == AutoIncrementKind::Legacy);
281    if !legacy {
282        return Ok(());
283    }
284    let owner = uqa_sql::semantics::partition::partition_identity_owner(context.partitions, table)?;
285    context
286        .identifiers
287        .persist_next_id(&owner)
288        .map_err(|error| identifier_storage_error(action, &error))
289}
290
291/// Select the identity of a row `document` inserts into `allocation_table`, and whether the row supplied it. An integer key the table maps is the identity; a row whose integer key names none takes an identity the table generates at or above `KEY_IDENTITY_LIMIT`, except that a legacy counter key column the row leaves out draws its value from the table counter and that value names the row.
292pub fn prepare_insert_identity(
293    context: InsertIdentityContext<'_>,
294    allocation_table: &str,
295    id_column: &str,
296    source: IdentitySource,
297    auto_id_column: Option<&str>,
298    document: &mut Document,
299    action: &str,
300) -> Result<(DocId, bool), SQLError> {
301    let (doc_id, supplied) = match source {
302        IdentitySource::Generated => (
303            context.identifiers.allocate_next_id(allocation_table)?,
304            false,
305        ),
306        IdentitySource::Document => match document_supplied_id(document, id_column) {
307            Some(doc_id) => (doc_id, true),
308            None => (
309                context.identifiers.allocate_next_id(allocation_table)?,
310                false,
311            ),
312        },
313        IdentitySource::IntegerKey => match document
314            .get(id_column)
315            .filter(|value| !matches!(value, Value::Null))
316        {
317            Some(key) => match key_document_id(key) {
318                Some(doc_id) if context.identifiers.maps_integer_keys(allocation_table)? => {
319                    (doc_id, true)
320                }
321                _ => (
322                    context.identifiers.allocate_unmapped_id(allocation_table)?,
323                    false,
324                ),
325            },
326            None if auto_id_column == Some(id_column) => {
327                let doc_id = context.identifiers.allocate_next_id(allocation_table)?;
328                document.insert(id_column.to_string(), doc_id_value(doc_id)?);
329                (doc_id, false)
330            }
331            // A missing key fails its NOT NULL constraint; the row takes an identity no key names until then.
332            None => (
333                context.identifiers.allocate_unmapped_id(allocation_table)?,
334                false,
335            ),
336        },
337    };
338    context
339        .identifiers
340        .advance_next_id(allocation_table, doc_id)
341        .map_err(|error| identifier_storage_error(action, &error))?;
342    Ok((doc_id, supplied))
343}
344
345/// Allocate document identities using the partition hierarchy's identity owner.
346pub struct IdentityAllocationContext<'a> {
347    pub identifiers: &'a dyn MutationIdentifiers,
348    pub partitions: &'a dyn PartitionCatalog,
349}
350
351/// Follow a `BEFORE INSERT` trigger that changed the row's identity column. A key the table maps moves the row to the identity it names; a key that names none takes an identity the table generates when the row held one a key names.
352pub fn refresh_insert_identity_after_trigger(
353    allocation: IdentityAllocationContext<'_>,
354    table: &str,
355    id_column: &str,
356    source: IdentitySource,
357    document: &Document,
358    identity: &mut (DocId, bool),
359) -> Result<(), SQLError> {
360    let doc_id = match source {
361        IdentitySource::Generated => return Ok(()),
362        IdentitySource::Document => document_supplied_id(document, id_column),
363        IdentitySource::IntegerKey => {
364            let named = document.get(id_column).and_then(key_document_id);
365            if named.is_some() && allocation.identifiers.maps_integer_keys(table)? {
366                named
367            } else {
368                if is_key_document_id(identity.0) {
369                    *identity = (allocation.identifiers.allocate_unmapped_id(table)?, false);
370                }
371                return Ok(());
372            }
373        }
374    };
375    let Some(doc_id) = doc_id else {
376        return Ok(());
377    };
378    if doc_id == identity.0 {
379        return Ok(());
380    }
381    let owner =
382        uqa_sql::semantics::partition::partition_identity_owner(allocation.partitions, table)?;
383    allocation
384        .identifiers
385        .advance_next_id(&owner, doc_id)
386        .map_err(|error| {
387            identifier_storage_error("apply BEFORE INSERT trigger identity", &error)
388        })?;
389    *identity = (doc_id, true);
390    Ok(())
391}