Skip to main content

uqa_execution/query/
scored_input.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Streaming scored-document input adapters.
8
9mod borrowed;
10mod capture;
11mod deferred;
12mod hierarchy;
13mod indexed;
14mod materialize;
15mod projection;
16mod public_result;
17
18pub use capture::CapturedScoredEntries;
19pub(crate) use capture::ScoredEntryCapture;
20pub(in crate::query) use deferred::defer_entries;
21pub use hierarchy::HierarchyScoredDocumentSource;
22
23/// One execution of already-bound retrieval work under the retained statement inputs.
24pub type ScoredEntriesProducer<'a> =
25    Box<dyn FnOnce() -> Result<ProducedScoredEntries, SQLError> + Send + 'a>;
26
27pub enum ProducedScoredEntries {
28    Materialized(Vec<ScoredEntry>),
29    Captured(CapturedScoredEntries),
30}
31
32impl ProducedScoredEntries {
33    pub(crate) fn estimated_cardinality(&self) -> usize {
34        match self {
35            Self::Materialized(entries) => entries.len(),
36            Self::Captured(entries) => entries.estimated_cardinality(),
37        }
38    }
39}
40
41impl From<Vec<ScoredEntry>> for ProducedScoredEntries {
42    fn from(entries: Vec<ScoredEntry>) -> Self {
43        Self::Materialized(entries)
44    }
45}
46
47use crate::{query::table_read::TableRead, row_locks::recheck::RecheckDoc, ExecResult};
48use std::sync::Arc;
49use uqa_core::ScoredEntry;
50use uqa_core::{DocId, Value};
51use uqa_sql::semantics::SCORE_COLUMN;
52use uqa_sql::{
53    plan::source_projection::RelationMetadataProjection,
54    semantics::{
55        doc_id_value, DOC_ID_COLUMN, META_DOC_ID_COLUMN, META_QUALIFIER, META_SCORE_COLUMN,
56        TABLE_OID_COLUMN, XMIN_COLUMN,
57    },
58    ResultRow, SQLError,
59};
60
61pub enum ScoredInput {
62    All,
63    Candidates(super::SelectedIds),
64    Entries {
65        entries: Vec<ScoredEntry>,
66        score_bearing: bool,
67    },
68}
69
70#[derive(Clone, Copy)]
71pub(super) enum ScoreOrigin {
72    Unscored,
73    Retrieval,
74}
75
76impl ScoreOrigin {
77    fn from_score_bearing(score_bearing: bool) -> Self {
78        if score_bearing {
79            Self::Retrieval
80        } else {
81            Self::Unscored
82        }
83    }
84
85    pub(super) fn is_retrieval(self) -> bool {
86        matches!(self, Self::Retrieval)
87    }
88}
89
90#[derive(Clone, Copy)]
91pub(super) enum HiddenColumn {
92    DocId,
93    Score,
94    TableOid,
95}
96
97impl HiddenColumn {
98    const ALL: [Self; 3] = [Self::DocId, Self::Score, Self::TableOid];
99
100    fn bit(self) -> u8 {
101        match self {
102            Self::DocId => 1,
103            Self::Score => 2,
104            Self::TableOid => 4,
105        }
106    }
107
108    fn name(self) -> &'static str {
109        match self {
110            Self::DocId => DOC_ID_COLUMN,
111            Self::Score => SCORE_COLUMN,
112            Self::TableOid => TABLE_OID_COLUMN,
113        }
114    }
115}
116
117/// Whether a column of a scan's schema is one the scan attaches from row metadata instead of reading it from the stored fields: `_doc_id`, `_score` or `tableoid` where the table declares no column of that name. A predicate pushed into the scan sees only the stored fields.
118pub(crate) fn is_attached_metadata_column(
119    column: &str,
120    definitions: &[uqa_sql::ast::ColumnDef],
121) -> bool {
122    HiddenColumn::ALL
123        .iter()
124        .any(|hidden| hidden.name() == column)
125        && !definitions
126            .iter()
127            .any(|definition| definition.name == column)
128}
129
130#[derive(Clone, Copy)]
131pub(super) struct HiddenColumns(u8);
132
133impl HiddenColumns {
134    fn from_schema(
135        schema: &[String],
136        definitions: &[uqa_sql::ast::ColumnDef],
137        score_origin: ScoreOrigin,
138    ) -> Self {
139        let mut columns = Self(0);
140        for column in HiddenColumn::ALL {
141            let user_column = definitions
142                .iter()
143                .any(|definition| definition.name == column.name());
144            if !user_column && schema.iter().any(|candidate| candidate == column.name()) {
145                columns.insert(column);
146            }
147        }
148        if score_origin.is_retrieval()
149            && !definitions
150                .iter()
151                .any(|definition| definition.name == SCORE_COLUMN)
152        {
153            columns.insert(HiddenColumn::Score);
154        }
155        columns
156    }
157
158    fn insert(&mut self, column: HiddenColumn) {
159        self.0 |= column.bit();
160    }
161
162    pub(super) fn contains(self, column: HiddenColumn) -> bool {
163        self.0 & column.bit() != 0
164    }
165}
166
167#[derive(Clone, Copy)]
168pub(super) struct ScoredRowMetadata {
169    doc_id: DocId,
170    score: f64,
171    table_oid: Option<i64>,
172    columns: HiddenColumns,
173}
174
175impl ScoredRowMetadata {
176    fn projected_values(self) -> Result<[Option<Value>; 3], SQLError> {
177        #[cfg(test)]
178        METADATA_PREPARATIONS.with(|count| count.set(count.get() + 1));
179        Ok([self.doc_id()?, self.score(), self.table_oid()])
180    }
181
182    pub(super) fn doc_id(self) -> Result<Option<Value>, SQLError> {
183        self.columns
184            .contains(HiddenColumn::DocId)
185            .then(|| doc_id_value(self.doc_id))
186            .transpose()
187    }
188
189    pub(super) fn score(self) -> Option<Value> {
190        self.columns
191            .contains(HiddenColumn::Score)
192            .then_some(Value::Float(self.score))
193    }
194
195    pub(super) fn table_oid(self) -> Option<Value> {
196        self.columns
197            .contains(HiddenColumn::TableOid)
198            .then(|| self.table_oid.map_or(Value::Null, Value::Int))
199    }
200
201    pub(super) fn insert_into(self, row: &mut ResultRow) -> Result<(), SQLError> {
202        if let Some(value) = self.doc_id()? {
203            row.insert(DOC_ID_COLUMN.into(), value);
204        }
205        if let Some(value) = self.score() {
206            row.insert(SCORE_COLUMN.into(), value);
207        }
208        if let Some(value) = self.table_oid() {
209            row.insert(TABLE_OID_COLUMN.into(), value);
210        }
211        Ok(())
212    }
213}
214
215/// Scalar metadata carriers belong to the input batch. Each row updates only selected variable values; immutable table metadata and absent extras are reused.
216struct ProjectedMetadata {
217    values: [Option<Value>; 3],
218}
219
220impl ProjectedMetadata {
221    fn for_row(&mut self, doc_id: DocId, score: f64) -> Result<&[Option<Value>], SQLError> {
222        if self.values[0].is_some() {
223            self.values[0] = Some(doc_id_value(doc_id)?);
224        }
225        if let Some(Value::Float(value)) = self.values[1].as_mut() {
226            *value = score;
227        }
228        Ok(&self.values)
229    }
230}
231
232#[cfg(test)]
233thread_local! {
234    static METADATA_PREPARATIONS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
235}
236
237impl ScoredInput {
238    pub fn entries(entries: Vec<ScoredEntry>, score_bearing: bool) -> Self {
239        Self::Entries {
240            entries,
241            score_bearing,
242        }
243    }
244
245    /// Discard rows whose score cannot reach a score-first SQL slice while
246    /// retaining the complete boundary-score group for exact secondary
247    /// ordering. The relational sort still chooses the final `LIMIT` rows.
248    pub fn retain_top_scores_with_ties(&mut self, top_k: usize) {
249        let Self::Entries {
250            entries,
251            score_bearing: true,
252        } = self
253        else {
254            return;
255        };
256        if top_k == 0 {
257            entries.clear();
258            return;
259        }
260        if entries.len() <= top_k {
261            return;
262        }
263        let (_, boundary, _) =
264            entries.select_nth_unstable_by(top_k - 1, |a, b| b.score.total_cmp(&a.score));
265        let cutoff = boundary.score;
266        entries.retain(|entry| !entry.score.total_cmp(&cutoff).is_lt());
267    }
268}
269
270pub struct ScoredDocumentSource {
271    index_read_control: uqa_storage::read_control::StorageReadControl,
272    serializable: crate::serializable::SerializableScan,
273    scan_batch_bytes: usize,
274    batch_layout: crate::spill::EncodedBatchLayout,
275    shared_page_rows: usize,
276    table_name: String,
277    table: Arc<dyn TableRead>,
278    column_definitions: Vec<uqa_sql::ast::ColumnDef>,
279    input: ScoredInputCursor,
280    schema: crate::RowSchema,
281    projected_fields: Vec<String>,
282    projected_slots: Vec<crate::ProjectedValueSlot>,
283    projection_properties: projection::ProjectionProperties,
284    predicate: Option<crate::ProjectedPredicate>,
285    hidden_columns: HiddenColumns,
286    metadata_doc_id_attribute: Option<uqa_sql::ast::InternalColumnRef>,
287    metadata_score_attribute: Option<uqa_sql::ast::InternalColumnRef>,
288    appended_doc_id_attribute: Option<uqa_sql::ast::InternalColumnRef>,
289    appended_score_attribute: Option<uqa_sql::ast::InternalColumnRef>,
290    table_oid: Option<i64>,
291    ordering: Vec<crate::PhysicalOrder>,
292    input_guarantees_presence: bool,
293    /// The table's indexes hold every projected field, so rows are projected from index entries without reading a document.
294    index_only: bool,
295    lock_origin: Option<crate::query::local_table::SharedLockOrigin>,
296    recheck_pinned: bool,
297    recheck_documents: std::collections::BTreeMap<DocId, Arc<uqa_storage::StoredDocument>>,
298}
299
300pub enum ScoredInputCursor {
301    All { after: Option<DocId> },
302    Entries(std::vec::IntoIter<ScoredEntry>),
303    Captured(Box<CapturedScoredEntries>),
304    Candidates(Box<super::SelectedIdCursor>),
305}
306
307#[derive(Clone, Copy, Default)]
308pub struct ScoredSourceAttributes {
309    shared_score: Option<uqa_sql::ast::InternalColumnRef>,
310    metadata: RelationMetadataProjection,
311}
312
313impl ScoredSourceAttributes {
314    pub fn shared_score(
315        column: uqa_sql::ast::InternalColumnRef,
316        metadata: RelationMetadataProjection,
317    ) -> Self {
318        Self {
319            shared_score: Some(column),
320            metadata,
321        }
322    }
323}
324
325fn expose_metadata_namespace(
326    schema: &crate::RowSchema,
327    doc_id: Option<uqa_sql::ast::InternalColumnRef>,
328    score: Option<uqa_sql::ast::InternalColumnRef>,
329) -> crate::RowSchema {
330    let aliases = [
331        doc_id.and_then(|column| {
332            schema.internal_slot(column).map(|slot| {
333                (
334                    crate::ColumnIdentity::qualified(META_QUALIFIER, META_DOC_ID_COLUMN),
335                    slot,
336                    Some(uqa_sql::ast::ColumnType::BigInteger),
337                )
338            })
339        }),
340        score.and_then(|column| {
341            schema.internal_slot(column).map(|slot| {
342                (
343                    crate::ColumnIdentity::qualified(META_QUALIFIER, META_SCORE_COLUMN),
344                    slot,
345                    Some(uqa_sql::ast::ColumnType::DoublePrecision),
346                )
347            })
348        }),
349    ]
350    .into_iter()
351    .flatten()
352    .collect::<Vec<_>>();
353    if aliases.is_empty() {
354        schema.clone()
355    } else {
356        crate::RowSchema::with_physical_identity_aliases(schema, &aliases)
357    }
358}
359
360fn bind_structural_metadata_attribute(
361    schema: &crate::RowSchema,
362    hidden_columns: HiddenColumns,
363    hidden: HiddenColumn,
364    column: uqa_sql::ast::InternalColumnRef,
365    ty: uqa_sql::ast::ColumnType,
366) -> (crate::RowSchema, bool) {
367    if hidden_columns.contains(hidden) {
368        let position = schema
369            .position(hidden.name())
370            .expect("requested source metadata must have a logical position");
371        let slot = schema
372            .physical_slot(position)
373            .expect("requested source metadata must have a physical slot");
374        return (
375            crate::RowSchema::with_physical_internal_aliases(schema, &[(column, slot, Some(ty))]),
376            false,
377        );
378    }
379    (
380        crate::RowSchema::append_internal_typed(schema, &[(column, Some(ty))]),
381        true,
382    )
383}
384
385impl ScoredDocumentSource {
386    pub fn new(
387        table_name: &str,
388        table: Arc<dyn TableRead>,
389        input: ScoredInput,
390        schema: Vec<String>,
391        ordered_primary_key: Option<String>,
392        predicate: Option<crate::ProjectedPredicate>,
393    ) -> Self {
394        Self::new_with_metadata(
395            table_name,
396            table,
397            input,
398            schema,
399            ordered_primary_key,
400            predicate,
401            RelationMetadataProjection::default(),
402        )
403    }
404
405    pub fn new_with_metadata(
406        table_name: &str,
407        table: Arc<dyn TableRead>,
408        input: ScoredInput,
409        schema: Vec<String>,
410        ordered_primary_key: Option<String>,
411        predicate: Option<crate::ProjectedPredicate>,
412        metadata: RelationMetadataProjection,
413    ) -> Self {
414        Self::new_configured(
415            table_name,
416            table,
417            input,
418            schema,
419            ordered_primary_key,
420            predicate,
421            ScoredSourceAttributes {
422                metadata,
423                ..ScoredSourceAttributes::default()
424            },
425        )
426    }
427
428    /// Build one physical scored source while optionally sharing the opaque score attribute with sibling scans that form one logical relation.
429    #[expect(
430        clippy::too_many_lines,
431        reason = "preserves SELECT schema and row identity"
432    )]
433    pub fn new_configured(
434        table_name: &str,
435        table: Arc<dyn TableRead>,
436        input: ScoredInput,
437        mut schema: Vec<String>,
438        ordered_primary_key: Option<String>,
439        predicate: Option<crate::ProjectedPredicate>,
440        attributes: ScoredSourceAttributes,
441    ) -> Self {
442        let ScoredSourceAttributes {
443            shared_score: score_column,
444            metadata,
445        } = attributes;
446        // Projection pruning may remove the primary-key column. An ordering
447        // property is only meaningful when the ordered value is present in
448        // the physical output schema.
449        let ordered_primary_key = ordered_primary_key
450            .and_then(|column| schema.iter().position(|candidate| candidate == &column));
451        let (input, score_origin, ordering, input_guarantees_presence) = match input {
452            ScoredInput::All => (
453                ScoredInputCursor::All { after: None },
454                ScoreOrigin::Unscored,
455                ordered_primary_key
456                    .into_iter()
457                    .map(|position| crate::PhysicalOrder {
458                        position,
459                        descending: false,
460                        nulls_first: None,
461                        nullable: false,
462                    })
463                    .collect(),
464                true,
465            ),
466            ScoredInput::Candidates(ids) => (
467                ScoredInputCursor::Candidates(Box::new(ids.cursor())),
468                ScoreOrigin::Unscored,
469                ordered_primary_key
470                    .into_iter()
471                    .map(|position| crate::PhysicalOrder {
472                        position,
473                        descending: false,
474                        nulls_first: None,
475                        nullable: false,
476                    })
477                    .collect(),
478                false,
479            ),
480            ScoredInput::Entries {
481                entries,
482                score_bearing,
483            } => {
484                let doc_ids_are_ordered = entries
485                    .windows(2)
486                    .all(|pair| pair[0].doc_id <= pair[1].doc_id);
487                let ordering = if doc_ids_are_ordered {
488                    ordered_primary_key
489                        .into_iter()
490                        .map(|position| crate::PhysicalOrder {
491                            position,
492                            descending: false,
493                            nulls_first: None,
494                            nullable: false,
495                        })
496                        .collect()
497                } else {
498                    Vec::new()
499                };
500                (
501                    ScoredInputCursor::Entries(entries.into_iter()),
502                    ScoreOrigin::from_score_bearing(score_bearing),
503                    ordering,
504                    false,
505                )
506            }
507        };
508        let column_definitions = table.column_definitions();
509        let hidden_columns = HiddenColumns::from_schema(&schema, &column_definitions, score_origin);
510        for column in HiddenColumn::ALL {
511            if hidden_columns.contains(column)
512                && !schema.iter().any(|candidate| candidate == column.name())
513            {
514                schema.push(column.name().to_string());
515            }
516        }
517        let projected_fields = schema
518            .iter()
519            .filter(|column| !is_attached_metadata_column(column, &column_definitions))
520            .cloned()
521            .collect::<Vec<_>>();
522        let extra_columns = HiddenColumn::ALL.map(HiddenColumn::name);
523        let projected_slots =
524            crate::ProjectedValueSlot::compile(&schema, &projected_fields, &extra_columns);
525        let projection_properties = projection::ProjectionProperties::new(
526            &column_definitions,
527            &projected_fields,
528            &projected_slots,
529        );
530        let wildcard_hidden = schema
531            .iter()
532            .enumerate()
533            .filter_map(|(position, name)| {
534                (name == XMIN_COLUMN
535                    || name == TABLE_OID_COLUMN
536                    || HiddenColumn::ALL.iter().any(|hidden| {
537                        hidden_columns.contains(*hidden) && name.as_str() == hidden.name()
538                    }))
539                .then_some(position)
540            })
541            .collect::<Vec<_>>();
542        let schema = crate::RowSchema::with_column_metadata(
543            None,
544            schema.into_iter().map(|column| {
545                let definition = column_definitions
546                    .iter()
547                    .find(|definition| definition.name == column);
548                let ty =
549                    definition
550                        .map(|definition| definition.ty.clone())
551                        .or(match column.as_str() {
552                            DOC_ID_COLUMN => Some(uqa_sql::ast::ColumnType::BigInteger),
553                            SCORE_COLUMN => Some(uqa_sql::ast::ColumnType::DoublePrecision),
554                            TABLE_OID_COLUMN => Some(uqa_sql::ast::ColumnType::Oid),
555                            XMIN_COLUMN => Some(uqa_sql::ast::ColumnType::Xid),
556                            _ => None,
557                        });
558                (
559                    column,
560                    ty,
561                    definition.and_then(|definition| definition.collation_oid),
562                )
563            }),
564        );
565        let schema = crate::RowSchema::with_wildcard_hidden_positions(&schema, wildcard_hidden);
566        let mut schema = schema;
567        let mut metadata_doc_id_attribute = None;
568        let mut metadata_score_attribute = None;
569        let mut appended_doc_id_attribute = None;
570        let mut appended_score_attribute = None;
571        if metadata.includes_doc_id() {
572            let column = uqa_sql::ast::InternalRelationId::allocate().column(0);
573            metadata_doc_id_attribute = Some(column);
574            let (bound, appended) = bind_structural_metadata_attribute(
575                &schema,
576                hidden_columns,
577                HiddenColumn::DocId,
578                column,
579                uqa_sql::ast::ColumnType::BigInteger,
580            );
581            schema = bound;
582            appended_doc_id_attribute = appended.then_some(column);
583        }
584        if score_origin.is_retrieval() || metadata.includes_score() {
585            let column = score_column
586                .unwrap_or_else(|| uqa_sql::ast::InternalRelationId::allocate().column(0));
587            if metadata.includes_score() {
588                metadata_score_attribute = Some(column);
589            }
590            let (bound, appended) = bind_structural_metadata_attribute(
591                &schema,
592                hidden_columns,
593                HiddenColumn::Score,
594                column,
595                uqa_sql::ast::ColumnType::DoublePrecision,
596            );
597            schema = bound;
598            appended_score_attribute = appended.then_some(column);
599            if score_origin.is_retrieval() {
600                schema = crate::RowSchema::with_score_source(&schema, None, column);
601            }
602        }
603        schema =
604            expose_metadata_namespace(&schema, metadata_doc_id_attribute, metadata_score_attribute);
605        Self {
606            scan_batch_bytes: 64 * 1024 * 1024,
607            batch_layout: crate::spill::EncodedBatchLayout::default(),
608            index_read_control: uqa_storage::read_control::StorageReadControl::with_limit(
609                64 * 1024,
610            ),
611            shared_page_rows: 1,
612            table_name: table_name.to_string(),
613            table,
614            column_definitions,
615            input,
616            schema,
617            projected_fields,
618            projected_slots,
619            projection_properties,
620            predicate,
621            hidden_columns,
622            metadata_doc_id_attribute,
623            metadata_score_attribute,
624            appended_doc_id_attribute,
625            appended_score_attribute,
626            table_oid: None,
627            ordering,
628            input_guarantees_presence,
629            index_only: false,
630            lock_origin: None,
631            recheck_pinned: false,
632            recheck_documents: std::collections::BTreeMap::new(),
633            serializable: crate::serializable::SerializableScan::default(),
634        }
635    }
636
637    /// Fill a prepared retrieval source before its first read, preserving its bound score attribute and row schema. Candidate ordering is determined only by the evaluated retrieval.
638    pub(in crate::query) fn with_retrieval_entries(mut self, entries: Vec<ScoredEntry>) -> Self {
639        self.input = ScoredInputCursor::Entries(entries.into_iter());
640        self.input_guarantees_presence = false;
641        self.ordering.clear();
642        self
643    }
644
645    pub(in crate::query) fn with_captured_entries(
646        mut self,
647        entries: CapturedScoredEntries,
648    ) -> Self {
649        self.input = ScoredInputCursor::Captured(Box::new(entries));
650        self.input_guarantees_presence = false;
651        self.ordering.clear();
652        self
653    }
654
655    pub fn with_serializable_read(
656        mut self,
657        read: Option<crate::serializable::SerializableRelationRead>,
658    ) -> Self {
659        self.serializable = crate::serializable::SerializableScan::new(read);
660        self
661    }
662
663    /// Bound the bytes retained by an ordered shared or borrowed document cursor. The current row may exceed the allowance; the next row belongs to the next batch.
664    pub fn with_scan_batch_bytes(mut self, bytes: usize) -> Self {
665        self.scan_batch_bytes = bytes;
666        self
667    }
668
669    /// Project rows from the index entries the table holds for every projected field. A row-locking read and a pinned recheck still read their documents.
670    pub fn with_index_only(mut self, index_only: bool) -> Self {
671        self.index_only = index_only;
672        self
673    }
674
675    pub fn with_index_read_control(
676        mut self,
677        control: uqa_storage::read_control::StorageReadControl,
678    ) -> Self {
679        self.index_read_control = control;
680        self
681    }
682
683    pub fn with_lock_origin(
684        mut self,
685        origin: Option<crate::query::local_table::SharedLockOrigin>,
686    ) -> Self {
687        self.lock_origin = origin;
688        self
689    }
690
691    pub fn with_table_oid(mut self, table_oid: i64) -> Self {
692        self.table_oid = Some(table_oid);
693        self
694    }
695
696    /// Pin this scan to a tuple-local recheck candidate's tuples. A ranked input (retrieval predicate) was re-executed against the latest index state when the recheck rebuilt the scan, so a pinned tuple survives only if the retrieval still matches it, exactly like `PostgreSQL` re-evaluating the WHERE clause on the substituted tuple; its score is the re-executed retrieval score. A plain scan input keeps every pinned tuple and lets the residual predicates decide.
697    pub fn with_recheck_pins(
698        mut self,
699        pins: Option<Arc<Vec<RecheckDoc>>>,
700    ) -> Result<Self, SQLError> {
701        let Some(pins) = pins else {
702            return Ok(self);
703        };
704        let mut selected = pins
705            .iter()
706            .map(|pin| (pin.doc_id, None))
707            .collect::<std::collections::BTreeMap<_, _>>();
708        let indexed = match &mut self.input {
709            ScoredInputCursor::Captured(entries) => {
710                for entry in entries.by_ref() {
711                    let entry = entry?;
712                    if let Some(score) = selected.get_mut(&entry.doc_id) {
713                        *score = Some(entry.score);
714                    }
715                }
716                true
717            }
718            ScoredInputCursor::Entries(entries) => {
719                for entry in entries.by_ref() {
720                    if let Some(score) = selected.get_mut(&entry.doc_id) {
721                        *score = Some(entry.score);
722                    }
723                }
724                true
725            }
726            ScoredInputCursor::Candidates(ids) => {
727                for id in ids.by_ref() {
728                    if let Some(score) = selected.get_mut(&id?) {
729                        *score = Some(0.0);
730                    }
731                }
732                true
733            }
734            ScoredInputCursor::All { .. } => false,
735        };
736        let entries = pins
737            .iter()
738            .filter_map(|pin| {
739                let score = if indexed {
740                    selected.get(&pin.doc_id).copied().flatten()
741                } else {
742                    Some(0.0)
743                };
744                score.map(|score| ScoredEntry {
745                    doc_id: pin.doc_id,
746                    score,
747                })
748            })
749            .collect::<Vec<_>>();
750        if !entries
751            .windows(2)
752            .all(|pair| pair[0].doc_id <= pair[1].doc_id)
753        {
754            self.ordering.clear();
755        }
756        self.recheck_documents = pins
757            .iter()
758            .filter_map(|pin| {
759                pin.document
760                    .as_ref()
761                    .map(|document| (pin.doc_id, Arc::clone(document)))
762            })
763            .collect();
764        self.recheck_pinned = true;
765        self.input = ScoredInputCursor::Entries(entries.into_iter());
766        Ok(self)
767    }
768
769    /// Bind every visible column to its relation without changing public labels or copying values.
770    pub fn with_qualifier(mut self, qualifier: &str) -> Self {
771        self.schema = crate::RowSchema::with_relation_qualifier(&self.schema, qualifier);
772        self.schema = expose_metadata_namespace(
773            &self.schema,
774            self.metadata_doc_id_attribute,
775            self.metadata_score_attribute,
776        );
777        self
778    }
779
780    /// Open document fields are explicitly addressable without expanding the source's declared wildcard row.
781    pub fn without_wildcard_columns(mut self) -> Self {
782        self.schema = crate::RowSchema::with_wildcard_hidden_positions(
783            &self.schema,
784            0..self.schema.columns().len(),
785        );
786        self
787    }
788
789    /// Keep the catalog's whole-row identity alongside selected fields and hidden retrieval metadata.
790    pub fn with_row_type(
791        mut self,
792        qualifier: &str,
793        row_type: Option<uqa_sql::ColumnType>,
794    ) -> Result<Self, uqa_sql::SQLError> {
795        if let Some(row_type) = row_type {
796            self.schema = self.schema.with_relation_row_type(qualifier, row_type)?;
797        }
798        Ok(self)
799    }
800
801    fn row_metadata(&self, doc_id: DocId, score: f64) -> ScoredRowMetadata {
802        ScoredRowMetadata {
803            doc_id,
804            score,
805            table_oid: self.table_oid,
806            columns: self.hidden_columns,
807        }
808    }
809
810    fn projected_metadata(&self) -> Result<ProjectedMetadata, SQLError> {
811        Ok(ProjectedMetadata {
812            values: self.row_metadata(0, 0.0).projected_values()?,
813        })
814    }
815
816    fn append_metadata_attributes(
817        &self,
818        row: crate::PhysicalRow,
819        doc_id: DocId,
820        score: f64,
821    ) -> Result<crate::PhysicalRow, SQLError> {
822        let mut values = Vec::with_capacity(2);
823        if self.appended_doc_id_attribute.is_some() {
824            values.push(doc_id_value(doc_id)?);
825        }
826        if self.appended_score_attribute.is_some() {
827            values.push(Value::Float(score));
828        }
829        Ok(if values.is_empty() {
830            row
831        } else {
832            row.append_values(values)
833        })
834    }
835
836    fn next_entries(&mut self, max_rows: usize) -> Result<Vec<ScoredEntry>, SQLError> {
837        if max_rows == 0 {
838            return Ok(Vec::new());
839        }
840        match &mut self.input {
841            ScoredInputCursor::Captured(entries) => entries
842                .by_ref()
843                .take(max_rows)
844                .map(|entry| {
845                    let entry = entry?;
846                    self.serializable.observe_row(entry.doc_id)?;
847                    Ok(entry)
848                })
849                .collect(),
850            ScoredInputCursor::Candidates(ids) => ids
851                .by_ref()
852                .take(max_rows)
853                .map(|id| {
854                    let doc_id = id?;
855                    self.serializable.observe_row(doc_id)?;
856                    Ok(ScoredEntry { doc_id, score: 0.0 })
857                })
858                .collect(),
859            ScoredInputCursor::Entries(entries) => {
860                for entry in entries.as_slice().iter().take(max_rows) {
861                    self.serializable.observe_row(entry.doc_id)?;
862                }
863                Ok(entries.by_ref().take(max_rows).collect())
864            }
865            ScoredInputCursor::All { after } => {
866                self.serializable.observe_relation()?;
867                let doc_ids = self
868                    .table
869                    .read_documents()
870                    .next_doc_ids(*after, max_rows)
871                    .map_err(|error| {
872                        SQLError::Internal(format!(
873                            "scan document ids for `{}`: {error}",
874                            self.table_name
875                        ))
876                    })?;
877                if let Some(doc_id) = doc_ids.last() {
878                    *after = Some(*doc_id);
879                }
880                Ok(doc_ids
881                    .into_iter()
882                    .map(|doc_id| ScoredEntry { doc_id, score: 0.0 })
883                    .collect())
884            }
885        }
886    }
887}
888
889impl crate::RowSource for ScoredDocumentSource {
890    fn schema(&self) -> &[String] {
891        self.schema.columns()
892    }
893
894    fn supports_batched_consumption(&self) -> bool {
895        // Plain scans keep predicate evaluation in row order. Candidate materialization, generated fields and locking/recheck reads retain their row boundaries.
896        matches!(self.input, ScoredInputCursor::All { .. })
897            && self.lock_origin.is_none()
898            && !self.recheck_pinned
899            && !self.projection_properties.requires_materialization
900    }
901
902    fn physical_schema(&self) -> Option<&crate::RowSchema> {
903        Some(&self.schema)
904    }
905
906    fn output_ordering(&self) -> &[crate::PhysicalOrder] {
907        &self.ordering
908    }
909
910    fn next_row(&mut self) -> ExecResult<Option<ResultRow>> {
911        Ok(self.next_batch(1)?.into_iter().next())
912    }
913
914    fn next_batch(&mut self, max_rows: usize) -> ExecResult<Vec<ResultRow>> {
915        loop {
916            let entries = self.next_entries(max_rows)?;
917            if entries.is_empty() {
918                return Ok(Vec::new());
919            }
920            let reached_end = entries.len() < max_rows;
921            let rows = self.materialize_entries(&entries)?;
922            if !rows.is_empty() || reached_end {
923                return Ok(rows);
924            }
925        }
926    }
927
928    fn next_physical_batch(&mut self, max_rows: usize) -> ExecResult<Vec<crate::PhysicalRow>> {
929        if let Some(rows) = self.next_shared_physical_batch(max_rows)? {
930            return Ok(rows);
931        }
932        if let Some(rows) = self.next_borrowed_physical_batch(max_rows)? {
933            return Ok(rows);
934        }
935        loop {
936            let entries = self.next_entries(max_rows)?;
937            if entries.is_empty() {
938                return Ok(Vec::new());
939            }
940            let reached_end = entries.len() < max_rows;
941            let rows = self.materialize_physical_entries(&entries)?;
942            if !rows.is_empty() || reached_end {
943                return Ok(rows);
944            }
945        }
946    }
947
948    fn collect_materialized(
949        &mut self,
950        sink: &mut crate::query::output::MaterializedResultSink<'_>,
951    ) -> ExecResult<bool> {
952        self.collect_shared_public_rows(sink)
953    }
954
955    fn consume_into_aggregate(
956        &mut self,
957        executor: &mut dyn crate::AggregateExecutor,
958    ) -> ExecResult<bool> {
959        if self.appended_doc_id_attribute.is_some() || self.appended_score_attribute.is_some() {
960            return Ok(false);
961        }
962        if !executor.supports_projected_rows() {
963            return Ok(false);
964        }
965        let supports_storage_borrowed_rows = executor.supports_storage_borrowed_rows();
966        loop {
967            if supports_storage_borrowed_rows {
968                if let Some(reached_end) =
969                    self.aggregate_shared_batch(crate::batch::DEFAULT_BATCH_SIZE, executor)?
970                {
971                    if reached_end {
972                        return Ok(true);
973                    }
974                    continue;
975                }
976            }
977            let entries = self.next_entries(crate::batch::DEFAULT_BATCH_SIZE)?;
978            if entries.is_empty() {
979                return Ok(true);
980            }
981            let reached_end = entries.len() < crate::batch::DEFAULT_BATCH_SIZE;
982            self.aggregate_entries(&entries, executor)?;
983            if reached_end {
984                return Ok(true);
985            }
986        }
987    }
988}
989
990#[cfg(test)]
991mod tests;