Skip to main content

uqa_execution/serializable/
column_index.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bind selected column accelerators and evaluated writes to immutable logical index addresses.
8
9use std::collections::BTreeMap;
10use uqa_core::{CancellationToken, DocId, Predicate, Value};
11use uqa_sql::{
12    ast::{ColumnDef, TableKeyConstraint},
13    SQLError,
14};
15use uqa_storage::{
16    document_store::Document,
17    mvcc::{SerializableKeySpace, SerializablePredicate, SerializableSession},
18    read_control::StorageReadControl,
19    PersistentStorageBackend, ValueIndexEntry, ValueIndexKey,
20};
21
22use super::{index_key::IndexDomain, SerializableRelationRead};
23use crate::{
24    catalog::index::physical::{rebuild::IndexDocuments, PhysicalIndexDefinitions},
25    storage_errors::storage_error,
26};
27
28fn binding(columns: &[ColumnDef], name: &str) -> Result<([u8; 16], IndexDomain), SQLError> {
29    let column = columns
30        .iter()
31        .find(|column| column.name == name)
32        .ok_or_else(|| SQLError::UnknownColumn(name.into()))?;
33    let identity = column
34        .object_id
35        .filter(|identity| *identity != [0; 16])
36        .ok_or_else(|| SQLError::Internal("column index has no immutable identity".into()))?;
37    let domain = IndexDomain::from_column_type(&column.ty).ok_or_else(|| {
38        SQLError::Unsupported(format!(
39            "serializable column index keys for {:?}",
40            column.ty
41        ))
42    })?;
43    Ok((identity, domain))
44}
45
46impl SerializableRelationRead {
47    /// Register after the executing column access path selects its predicate and before exposing a result. Catalog estimates, hydration and constraint probes do not call this boundary.
48    pub fn observe_column_index(
49        &self,
50        columns: &[ColumnDef],
51        field: &ValueIndexKey,
52        predicate: &Predicate,
53    ) -> Result<(), SQLError> {
54        let ValueIndexKey::Column(name) = field else {
55            return Err(SQLError::Internal(
56                "column index read requires a column accelerator".into(),
57            ));
58        };
59        let (identity, domain) = binding(columns, name)?;
60        domain.visit_predicate(predicate, &self.control, &mut |range| {
61            let (lower, upper) = range.bounds();
62            self.observe(SerializablePredicate::range(
63                self.object,
64                SerializableKeySpace::Index(identity),
65                lower,
66                upper,
67            ))
68        })
69    }
70}
71
72pub struct SerializableColumnWrites<'a> {
73    session: &'a dyn SerializableSession,
74    backend: &'a dyn PersistentStorageBackend,
75    object: [u8; 16],
76    control: StorageReadControl,
77}
78
79pub struct ColumnIndexChange<'a> {
80    pub table: &'a str,
81    pub columns: &'a [ColumnDef],
82    pub constraints: &'a [TableKeyConstraint],
83    pub definitions: &'a PhysicalIndexDefinitions,
84    pub documents: &'a dyn IndexDocuments,
85    pub doc_id: DocId,
86    pub had_old: bool,
87    pub cached_old: Option<&'a BTreeMap<ValueIndexKey, Value>>,
88    pub new: Option<&'a BTreeMap<ValueIndexKey, Value>>,
89}
90
91impl<'a> SerializableColumnWrites<'a> {
92    pub fn new(
93        backend: Option<&'a dyn PersistentStorageBackend>,
94        object: Option<[u8; 16]>,
95        cancellation: &CancellationToken,
96    ) -> Result<Option<Self>, SQLError> {
97        let (Some(backend), Some(object)) = (backend, object) else {
98            return Ok(None);
99        };
100        let Some(session) = backend.serializable_session() else {
101            return Ok(None);
102        };
103        let Some(context) = session
104            .serializable_read_context()
105            .map_err(|error| storage_error("retain serializable index writer", &error))?
106        else {
107            return Ok(None);
108        };
109        Ok(Some(Self {
110            session,
111            backend,
112            object,
113            control: context.read_control(cancellation),
114        }))
115    }
116
117    /// Observe the original and replacement column keys before any private index or row publication. Savepoint ownership remains with the surrounding statement.
118    pub fn observe(&self, change: ColumnIndexChange<'_>) -> Result<(), SQLError> {
119        // A column that an index only carries answers no predicate, so no reader observed its keys.
120        let fields =
121            change
122                .definitions
123                .search_fields(change.table, change.columns, change.constraints);
124        let mut projected_old: Option<Option<Document>> = None;
125        for field in fields {
126            let ValueIndexKey::Column(name) = &field else {
127                continue;
128            };
129            let (identity, domain) = binding(change.columns, name)?;
130            if change.had_old {
131                if let Some(value) = change.cached_old.and_then(|values| values.get(&field)) {
132                    self.observe_value(identity, domain, value)?;
133                } else {
134                    match self
135                        .backend
136                        .read_btree_index_entry(change.table, &field, change.doc_id)
137                        .map_err(|error| storage_error("read original index key", &error))?
138                    {
139                        ValueIndexEntry::Present(value) => {
140                            self.observe_value(identity, domain, &value)?;
141                        }
142                        ValueIndexEntry::Absent | ValueIndexEntry::Unbuilt => {
143                            if projected_old.is_none() {
144                                projected_old =
145                                    Some(change.documents.read().get(change.doc_id).map_err(
146                                        |error| {
147                                            storage_error("project original column key", &error)
148                                        },
149                                    )?);
150                            }
151                            if let Some(document) = projected_old.as_ref().and_then(Option::as_ref)
152                            {
153                                self.observe_value(
154                                    identity,
155                                    domain,
156                                    crate::catalog::index::physical::column_value(document, name),
157                                )?;
158                            }
159                        }
160                    }
161                }
162            }
163            if let Some(values) = change.new {
164                let value = values.get(&field).ok_or_else(|| {
165                    SQLError::Internal(format!("replacement index key missing for {field}"))
166                })?;
167                self.observe_value(identity, domain, value)?;
168            }
169        }
170        Ok(())
171    }
172
173    fn observe_value(
174        &self,
175        identity: [u8; 16],
176        domain: IndexDomain,
177        value: &Value,
178    ) -> Result<(), SQLError> {
179        let key = domain.encode(value, &self.control)?;
180        self.session
181            .observe_serializable_write(SerializablePredicate::point(
182                self.object,
183                SerializableKeySpace::Index(identity),
184                &key,
185            ))
186            .map_err(|error| storage_error("observe serializable index write", &error))
187    }
188}