Skip to main content

uqa_execution/operator_tree/driver/
posting.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Posting-list adapters and document-wise fusion utilities.
8
9use super::{
10    BTreeMap, BTreeSet, DocId, DriverResult, Payload, PostingEntry, PostingList, SQLError,
11    ScoredEntry, Value,
12};
13
14/// Replay a computed child posting list for operators that consume already-evaluated signals.
15pub(super) struct StaticPostingList {
16    pub(super) pl: PostingList,
17}
18
19pub(super) fn static_operator(pl: PostingList) -> std::sync::Arc<dyn uqa_operators::Operator> {
20    std::sync::Arc::new(StaticPostingList { pl })
21}
22
23pub(super) fn numeric_score(value: &Value) -> f64 {
24    match value {
25        Value::Int(value) => *value as f64,
26        Value::Float(value) => *value,
27        _ => 0.0,
28    }
29}
30
31impl uqa_operators::base::Operator for StaticPostingList {
32    fn execute(
33        &self,
34        _ctx: &uqa_operators::base::ExecutionContext,
35    ) -> uqa_operators::base::OperatorResult {
36        Ok(self.pl.clone())
37    }
38}
39
40/// Combine a vector of per-signal posting lists into a single fused posting list. `fuse` receives one document's per-signal probability vector and returns its fused score.
41pub(super) fn fuse_signals_with<F>(
42    posting_lists: &[PostingList],
43    fuse: F,
44) -> DriverResult<PostingList>
45where
46    F: Fn(&[f64]) -> DriverResult<f64>,
47{
48    fuse_signal_batches_with(posting_lists, |probabilities| {
49        probabilities.iter().map(|sample| fuse(sample)).collect()
50    })
51}
52
53pub(super) fn fuse_signal_batches_with<F>(
54    posting_lists: &[PostingList],
55    fuse: F,
56) -> DriverResult<PostingList>
57where
58    F: Fn(&[Vec<f64>]) -> DriverResult<Vec<f64>>,
59{
60    let (candidate_ids, probabilities) = fusion_probability_matrix(posting_lists);
61    if candidate_ids.is_empty() {
62        return Ok(PostingList::new());
63    }
64    let fused = fuse(&probabilities)?;
65    if fused.len() != candidate_ids.len() {
66        return Err(SQLError::Internal(format!(
67            "fusion returned {} scores for {} candidates",
68            fused.len(),
69            candidate_ids.len()
70        )));
71    }
72    let entries = candidate_ids
73        .into_iter()
74        .zip(fused)
75        .map(|(doc_id, score)| {
76            PostingEntry::new(
77                doc_id,
78                Payload {
79                    score,
80                    ..Default::default()
81                },
82            )
83        })
84        .collect();
85    Ok(PostingList::from_sorted_unchecked(entries))
86}
87
88pub(super) fn fusion_probability_matrix(
89    posting_lists: &[PostingList],
90) -> (Vec<DocId>, Vec<Vec<f64>>) {
91    let mut maps: Vec<BTreeMap<DocId, f64>> = Vec::with_capacity(posting_lists.len());
92    let mut all_ids: BTreeSet<DocId> = BTreeSet::new();
93    for pl in posting_lists {
94        let mut m: BTreeMap<DocId, f64> = BTreeMap::new();
95        for entry in pl {
96            m.insert(entry.doc_id, entry.payload.score);
97            all_ids.insert(entry.doc_id);
98        }
99        maps.push(m);
100    }
101    let total = all_ids.len();
102    if total == 0 {
103        return (Vec::new(), Vec::new());
104    }
105    let defaults: Vec<f64> = maps
106        .iter()
107        .map(|m| uqa_operators::hybrid::coverage_based_default(m.len(), total, 0.01))
108        .collect();
109    let mut candidate_ids = Vec::with_capacity(total);
110    let mut probabilities = Vec::with_capacity(total);
111    for doc_id in all_ids {
112        let probs: Vec<f64> = maps
113            .iter()
114            .enumerate()
115            .map(|(j, m)| *m.get(&doc_id).unwrap_or(&defaults[j]))
116            .collect();
117        candidate_ids.push(doc_id);
118        probabilities.push(probs);
119    }
120    (candidate_ids, probabilities)
121}
122
123pub fn scored_to_posting_list(scored: &[ScoredEntry]) -> PostingList {
124    let mut entries: Vec<PostingEntry> = scored
125        .iter()
126        .map(|e| PostingEntry::new(e.doc_id, Payload::with_score(e.score)))
127        .collect();
128    entries.sort_by_key(|e| e.doc_id);
129    PostingList::from_sorted_unchecked(entries)
130}
131
132pub fn posting_list_to_scored(pl: &PostingList) -> Vec<ScoredEntry> {
133    pl.entries()
134        .iter()
135        .map(|e| ScoredEntry {
136            doc_id: e.doc_id,
137            score: e.payload.score,
138        })
139        .collect()
140}
141
142pub(super) fn sparse_threshold_inline(
143    source: &PostingList,
144    threshold: f64,
145) -> DriverResult<PostingList> {
146    if !threshold.is_finite() {
147        return Err(SQLError::TypeMismatch(format!(
148            "sparse threshold must be finite, got {threshold}"
149        )));
150    }
151    let entries = source
152        .iter()
153        .map(|entry| {
154            if !entry.payload.score.is_finite() {
155                return Err(SQLError::Internal(format!(
156                    "sparse threshold source produced non-finite score {} for document {}",
157                    entry.payload.score, entry.doc_id
158                )));
159            }
160            let adjusted = entry.payload.score - threshold;
161            if !adjusted.is_finite() {
162                return Err(SQLError::Internal(format!(
163                    "sparse threshold produced non-finite score for document {}",
164                    entry.doc_id
165                )));
166            }
167            if adjusted > 0.0 {
168                Ok(Some(PostingEntry::new(
169                    entry.doc_id,
170                    Payload {
171                        positions: entry.payload.positions.clone(),
172                        score: adjusted,
173                        fields: entry.payload.fields.clone(),
174                    },
175                )))
176            } else {
177                Ok(None)
178            }
179        })
180        .collect::<DriverResult<Vec<_>>>()?
181        .into_iter()
182        .flatten()
183        .collect();
184    Ok(PostingList::from_unsorted(entries))
185}