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