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