Skip to main content

uqa_engine/search/
learning.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Supervised and unsupervised scoring-parameter updates.
8
9use uqa_storage::InvertedIndex;
10
11use super::{
12    storage_sql_error, BM25Params, BTreeMap, DocId, Engine, ParameterLearner, SQLError,
13    ScoringMode, UnsupervisedBm25ScoreEstimator,
14};
15
16impl Engine {
17    pub fn learn_scoring_params(
18        &self,
19        table: &str,
20        field: &str,
21        query: &str,
22        labels: &[u8],
23    ) -> Result<std::collections::BTreeMap<String, f64>, SQLError> {
24        self.with_implicit_transaction(|engine| {
25            engine.learn_scoring_params_inner(table, field, query, labels)
26        })
27    }
28
29    pub(super) fn learn_scoring_params_inner(
30        &self,
31        table: &str,
32        field: &str,
33        query: &str,
34        labels: &[u8],
35    ) -> Result<std::collections::BTreeMap<String, f64>, SQLError> {
36        if self
37            .try_table(table)
38            .map_err(|error| storage_sql_error("resolve scoring table", error))?
39            .is_none()
40        {
41            return Err(SQLError::UnknownTable(table.to_string()));
42        }
43        let doc_ids = self.query_table_doc_ids(table)?;
44        if labels.len() != doc_ids.len() {
45            return Err(SQLError::TypeMismatch(format!(
46                "labels length ({}) must match document count ({})",
47                labels.len(),
48                doc_ids.len()
49            )));
50        }
51        if labels.iter().any(|label| *label > 1) {
52            return Err(SQLError::TypeMismatch(
53                "labels must contain only 0 or 1".into(),
54            ));
55        }
56
57        let mode = ScoringMode::BM25(BM25Params::default());
58        let score_map: std::collections::BTreeMap<DocId, f64> = self
59            .search(table, field, query, &mode, usize::MAX)?
60            .into_iter()
61            .map(|entry| (entry.doc_id, entry.score))
62            .collect();
63        let scores: Vec<f64> = doc_ids
64            .iter()
65            .map(|doc_id| score_map.get(doc_id).copied().unwrap_or(0.0))
66            .collect();
67        let labels_f: Vec<f64> = labels.iter().map(|label| f64::from(*label)).collect();
68        let mut learner = ParameterLearner::default();
69        let params = learner
70            .fit_with_options(&scores, &labels_f)
71            .map_err(|error| SQLError::Internal(format!("learn scoring parameters: {error}")))?;
72        let json = serde_json::to_string(&params)
73            .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
74        self.save_scoring_params(&format!("{table}.{field}"), &json)?;
75        Ok(params)
76    }
77
78    /// Estimate and persist an unsupervised BM25 score transform from a
79    /// field's indexed vocabulary and raw score distribution.
80    pub fn estimate_scoring_params(
81        &self,
82        table: &str,
83        field: &str,
84        n_samples: usize,
85        tokens_per_query: usize,
86        seed: i64,
87    ) -> Result<BTreeMap<String, f64>, SQLError> {
88        self.with_implicit_transaction(|engine| {
89            engine.estimate_scoring_params_inner(table, field, n_samples, tokens_per_query, seed)
90        })
91    }
92
93    pub(super) fn estimate_scoring_params_inner(
94        &self,
95        table: &str,
96        field: &str,
97        n_samples: usize,
98        tokens_per_query: usize,
99        seed: i64,
100    ) -> Result<BTreeMap<String, f64>, SQLError> {
101        if n_samples == 0 || tokens_per_query == 0 {
102            return Err(SQLError::TypeMismatch(
103                "n_samples and tokens_per_query must be positive".into(),
104            ));
105        }
106        if n_samples.checked_mul(tokens_per_query).is_none() {
107            return Err(SQLError::TypeMismatch(
108                "n_samples * tokens_per_query exceeds usize".into(),
109            ));
110        }
111        self.validate_text_search_field(table, field)?;
112        let Some(table_state) = self
113            .try_table(table)
114            .map_err(|error| storage_sql_error("resolve scoring table", error))?
115        else {
116            return Err(SQLError::UnknownTable(table.to_string()));
117        };
118        let estimator = UnsupervisedBm25ScoreEstimator::new(n_samples, tokens_per_query, seed)
119            .map_err(|error| SQLError::TypeMismatch(error.to_string()))?;
120        let queries = self.sample_calibration_queries(table, field, &estimator)?;
121        let (params, doc_count) = {
122            let index = table_state.inverted_index.read();
123            let index = uqa_execution::serializable::text::ObservedTextIndex::new(
124                index.as_ref(),
125                self.serializable_table_read(table)?,
126                table_state.columns.snapshot(),
127            );
128            let params = if queries.is_empty() {
129                estimator.estimate(&index, field, BM25Params::default())
130            } else {
131                estimator.estimate_with_query_keys(&index, field, BM25Params::default(), &queries)
132            }
133            .map_err(|error| storage_sql_error("estimate Bayesian BM25 parameters", error))?;
134            let doc_count = index
135                .doc_count()
136                .map_err(|error| storage_sql_error("read indexed document count", error))?;
137            (params, doc_count)
138        };
139        let values = BTreeMap::from([
140            ("alpha".to_string(), params.alpha),
141            ("beta".to_string(), params.beta),
142            ("base_rate".to_string(), params.base_rate),
143            ("calibration_tokens".to_string(), params.calibration_tokens),
144            ("beta_slope".to_string(), params.beta_slope),
145            ("sigma_slope".to_string(), params.sigma_slope),
146            ("estimated_doc_count".to_string(), doc_count as f64),
147        ]);
148        let json = serde_json::to_string(&values)
149            .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
150        self.save_scoring_params(&format!("{table}.{field}"), &json)?;
151        Ok(values)
152    }
153
154    pub fn update_scoring_params(
155        &self,
156        table: &str,
157        field: &str,
158        score: f64,
159        label: u8,
160    ) -> Result<(), SQLError> {
161        self.with_implicit_transaction(|engine| {
162            engine.update_scoring_params_inner(table, field, score, label)
163        })
164    }
165
166    pub(super) fn update_scoring_params_inner(
167        &self,
168        table: &str,
169        field: &str,
170        score: f64,
171        label: u8,
172    ) -> Result<(), SQLError> {
173        self.validate_text_search_field(table, field)?;
174        if !score.is_finite() {
175            return Err(SQLError::TypeMismatch(
176                "score must be a finite raw BM25 score".into(),
177            ));
178        }
179        if label > 1 {
180            return Err(SQLError::TypeMismatch("label must be 0 or 1".into()));
181        }
182        let key = format!("{table}.{field}");
183        self.lock_scoring_parameter_write(&key)?;
184        let saved = self.load_scoring_params(&key)?;
185        let has_saved_params = match saved.as_deref() {
186            Some(json) => {
187                serde_json::from_str::<BTreeMap<String, f64>>(json).map_err(|error| {
188                    SQLError::Internal(format!(
189                        "decode persisted scoring parameters `{key}`: {error}"
190                    ))
191                })?;
192                true
193            }
194            None => false,
195        };
196        let mut learner = if has_saved_params {
197            let current = self.bayesian_params_for(table, field)?;
198            let base_rate = (current.base_rate > 0.0).then_some(current.base_rate);
199            ParameterLearner::new(current.alpha, current.beta, base_rate).map_err(|error| {
200                SQLError::Internal(format!("restore scoring parameter learner: {error}"))
201            })?
202        } else {
203            ParameterLearner::default()
204        };
205        learner
206            .update(score, f64::from(label), 0.1)
207            .map_err(|error| SQLError::Internal(format!("update scoring parameters: {error}")))?;
208        let json = serde_json::to_string(&learner.params())
209            .map_err(|err| SQLError::Internal(format!("serialize scoring params: {err}")))?;
210        self.save_scoring_params(&key, &json)
211    }
212}