Skip to main content

uqa_engine/table_storage/
fts.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Full-text field registration and removal.
8
9use super::{AnalyzerPhase, Engine, FieldName};
10use uqa_execution::storage_errors::storage_error;
11use uqa_sql::SQLError;
12
13impl Engine {
14    /// Append `field` to the table's FTS field list. Existing rows are
15    /// indexed immediately so SQL `CREATE INDEX USING gin` behaves like a
16    /// real secondary-index build rather than a metadata-only toggle.
17    pub fn add_fts_field(&self, table: &str, field: FieldName) -> Result<(), String> {
18        self.add_fts_field_with_analyzer(table, field, None)
19    }
20
21    /// Same as [`Engine::add_fts_field`], but allows registering a
22    /// per-field analyzer name (e.g. `standard_cjk`). When `None`, the
23    /// table-level analyzer continues to apply.
24    pub fn add_fts_field_with_analyzer(
25        &self,
26        table: &str,
27        field: FieldName,
28        analyzer: Option<&str>,
29    ) -> Result<(), String> {
30        self.with_implicit_string_transaction(|engine| {
31            engine
32                .add_fts_field_with_analyzer_inner(table, field, analyzer)
33                .map_err(|error| error.to_string())?;
34            engine
35                .publish_catalog_constraint_tuples()
36                .map_err(|error| error.to_string())
37        })
38    }
39
40    pub(crate) fn add_fts_field_with_analyzer_inner(
41        &self,
42        table: &str,
43        field: FieldName,
44        analyzer: Option<&str>,
45    ) -> Result<(), SQLError> {
46        let table_name = self
47            .try_resolve_table_name(table)
48            .map_err(|error| storage_error("resolve FTS table", &error))?
49            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
50        let t = self
51            .try_table(table)
52            .map_err(|error| storage_error("resolve FTS table", &error))?
53            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
54        let existing = self
55            .durable
56            .table_field_analyzers
57            .read()
58            .get(&(table_name.clone(), field.clone()))
59            .cloned();
60        let uses_default = analyzer.is_none() && existing.is_none();
61        let candidate = if let Some(name) = analyzer {
62            let name = name.trim();
63            let revision = self
64                .resolve_analyzer_revision(name)
65                .map_err(|error| storage_error("resolve FTS analyzer", &error))?;
66            let previous = existing.unwrap_or_else(|| {
67                uqa_storage::FieldAnalyzerBinding::unassigned(revision.clone(), revision.clone())
68            });
69            match previous.owner {
70                uqa_storage::AnalyzerBindingOwner::Field
71                    if previous.index.name.is_some() || previous.search.name.is_some() =>
72                {
73                    return Err(SQLError::Unsupported(
74                        "GIN analyzer option competes with an existing field assignment".into(),
75                    ))
76                }
77                uqa_storage::AnalyzerBindingOwner::Gin
78                    if previous.index.name.as_deref() != Some(name)
79                        || previous.index.compiled.descriptor().fingerprint()
80                            != revision.descriptor().fingerprint() =>
81                {
82                    return Err(SQLError::Unsupported(
83                        "GIN analyzer option competes with an existing GIN revision".into(),
84                    ))
85                }
86                _ => {}
87            }
88            previous.assigned(
89                name,
90                revision,
91                AnalyzerPhase::Both,
92                uqa_storage::AnalyzerBindingOwner::Gin,
93            )
94        } else {
95            self.current_field_analyzer_binding(&table_name, &t, &field)
96                .map_err(|error| storage_error("resolve FTS analyzer binding", &error))?
97        };
98        {
99            let mut fts = t.fts_fields.write();
100            if !fts.contains(&field) {
101                fts.push(field.clone());
102            }
103        }
104        let mut source = Self::fts_source(&t, Some(&self.runtime.cancellation))
105            .map_err(|error| storage_error("read FTS rebuild source", &error))?;
106        let phase = if analyzer.is_some() {
107            AnalyzerPhase::Both
108        } else {
109            AnalyzerPhase::Index
110        };
111        t.inverted_index
112            .write()
113            .rebuild_with_analyzer_revision_cancellable(
114                &field,
115                candidate.index.compiled.clone(),
116                phase,
117                &mut source,
118                &self.runtime.cancellation,
119            )
120            .map_err(|error| storage_error("add_fts_field", &error))?;
121        candidate
122            .install(&field, t.inverted_index.write().as_mut())
123            .map_err(|error| storage_error("install FTS analyzer", &error))?;
124        if uses_default {
125            *t.analyzer.write() = candidate
126                .index
127                .compiled
128                .descriptor()
129                .configuration()
130                .map_err(|error| storage_error("read FTS analyzer configuration", &error.into()))?;
131        }
132        self.persist_field_analyzer_binding(&table_name, &field, &candidate)
133            .map_err(|error| storage_error("persist FTS analyzer binding", &error))?;
134        self.durable
135            .table_field_analyzers
136            .write()
137            .insert((table_name.clone(), field), candidate);
138        if self.is_persistent() {
139            self.try_save_table_schema(&table_name, &t)
140                .map_err(|error| storage_error("persist FTS schema", &error))?;
141        }
142        Ok(())
143    }
144
145    /// Remove a field from the physical FTS index and from every piece of
146    /// analyzer/schema metadata that makes the field searchable.  Callers
147    /// must first establish that no other logical GIN index still references
148    /// the field.
149    pub(crate) fn drop_fts_field(&self, table: &str, field: &str) -> Result<(), SQLError> {
150        self.with_implicit_transaction(|engine| engine.drop_fts_field_inner(table, field))
151    }
152
153    pub(super) fn drop_fts_field_inner(&self, table: &str, field: &str) -> Result<(), SQLError> {
154        let table_name = self
155            .try_resolve_table_name(table)
156            .map_err(|error| storage_error("resolve FTS table", &error))?
157            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
158        let t = self
159            .try_table(&table_name)
160            .map_err(|error| storage_error("resolve FTS table", &error))?
161            .ok_or_else(|| SQLError::UnknownTable(table_name.clone()))?;
162
163        if !t
164            .fts_fields
165            .read()
166            .iter()
167            .any(|candidate| candidate == field)
168        {
169            return Err(SQLError::Internal(format!(
170                "field `{table_name}`.`{field}` is not registered in the physical FTS index"
171            )));
172        }
173
174        t.fts_fields.write().retain(|candidate| candidate != field);
175        Self::rebuild_fts_index_cancellable(&t, &self.runtime.cancellation)
176            .map_err(|error| storage_error("rebuild FTS index", &error))?;
177        t.inverted_index
178            .write()
179            .remove_field_analyzers(field)
180            .map_err(|error| SQLError::Internal(format!("remove FTS analyzer: {error}")))?;
181
182        if let Some(catalog) = self.storage.catalog.as_ref() {
183            catalog
184                .drop_table_field_analyzer_field(&table_name, field)
185                .map_err(|error| storage_error("drop persisted FTS analyzer", &error))?;
186        }
187        self.durable
188            .table_field_analyzers
189            .write()
190            .remove(&(table_name.clone(), field.to_string()));
191        if self.is_persistent() {
192            self.try_save_table_schema(&table_name, &t)
193                .map_err(|error| storage_error("persist FTS schema", &error))?;
194            self.note_catalog_registry_changed();
195        }
196        Ok(())
197    }
198}
199
200impl Engine {
201    /// Release the last explicit GIN analyzer owner while another GIN still keeps the field indexed.
202    pub(crate) fn release_fts_analyzer_owner(
203        &self,
204        table: &str,
205        field: &str,
206    ) -> Result<(), SQLError> {
207        let table_name = self
208            .try_resolve_table_name(table)
209            .map_err(|error| storage_error("resolve FTS table", &error))?
210            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
211        let t = self
212            .try_table(&table_name)
213            .map_err(|error| storage_error("resolve FTS table", &error))?
214            .ok_or_else(|| SQLError::UnknownTable(table.into()))?;
215        let Some(previous) = self
216            .durable
217            .table_field_analyzers
218            .read()
219            .get(&(table_name.clone(), field.to_owned()))
220            .cloned()
221        else {
222            return Ok(());
223        };
224        if previous.owner != uqa_storage::AnalyzerBindingOwner::Gin {
225            return Ok(());
226        }
227        let revision = t
228            .analyzer
229            .read()
230            .clone()
231            .compile()
232            .map_err(|error| storage_error("compile FTS analyzer", &error.into()))?;
233        let binding =
234            uqa_storage::FieldAnalyzerBinding::unassigned(revision.clone(), revision.clone());
235        let mut source = Self::fts_source(&t, Some(&self.runtime.cancellation))
236            .map_err(|error| storage_error("read FTS rebuild source", &error))?;
237        t.inverted_index
238            .write()
239            .rebuild_with_analyzer_revision_cancellable(
240                field,
241                revision.clone(),
242                AnalyzerPhase::Both,
243                &mut source,
244                &self.runtime.cancellation,
245            )
246            .map_err(|error| storage_error("rebuild FTS analyzer", &error))?;
247        *t.analyzer.write() = revision
248            .descriptor()
249            .configuration()
250            .map_err(|error| storage_error("read FTS analyzer configuration", &error.into()))?;
251        self.persist_field_analyzer_binding(&table_name, field, &binding)
252            .map_err(|error| storage_error("persist FTS analyzer binding", &error))?;
253        self.durable
254            .table_field_analyzers
255            .write()
256            .insert((table_name.clone(), field.to_owned()), binding);
257        if self.is_persistent() && t.persistence != uqa_sql::ast::RelationPersistence::Temporary {
258            self.try_save_table_schema(&table_name, &t)
259                .map_err(|error| storage_error("persist FTS schema", &error))?;
260            self.note_table_catalog_changed();
261            self.note_catalog_registry_changed();
262        }
263        Ok(())
264    }
265}