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