Skip to main content

uqa_execution/query/scored_input/
hierarchy.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! One logical scored scan over independently stored hierarchy members.
8
9use crate::RowSchemaExecution;
10use std::collections::VecDeque;
11
12use crate::{ExecResult, PhysicalRow, RowSchema, RowSource};
13use uqa_sql::ResultRow;
14
15use super::{SQLError, ScoredDocumentSource};
16
17/// Concatenate scored physical relation sources without collapsing their
18/// table-local document identifiers. Each child source materializes against
19/// its own table and carries its own row-lock origin, while this adapter
20/// exposes the selected ancestor's one logical row type.
21pub struct HierarchyScoredDocumentSource {
22    sources: VecDeque<ScoredDocumentSource>,
23    schema: Vec<String>,
24    physical_schema: RowSchema,
25    estimated_cardinality: u64,
26}
27
28impl HierarchyScoredDocumentSource {
29    pub fn new(
30        sources: Vec<ScoredDocumentSource>,
31        estimated_cardinality: usize,
32    ) -> Result<Self, SQLError> {
33        let first = sources.first().ok_or_else(|| {
34            SQLError::Internal("hierarchy retrieval was built without a physical table".into())
35        })?;
36        let schema = first.schema().to_vec();
37        let physical_schema = first
38            .physical_schema()
39            .cloned()
40            .ok_or_else(|| SQLError::Internal("scored source has no physical schema".into()))?;
41        for source in sources.iter().skip(1) {
42            if source.schema() != schema
43                || source
44                    .physical_schema()
45                    .is_none_or(|candidate| candidate != &physical_schema)
46            {
47                return Err(SQLError::Internal(
48                    "hierarchy retrieval sources do not share one logical row type".into(),
49                ));
50            }
51        }
52        let estimated_cardinality = u64::try_from(estimated_cardinality).map_err(|_| {
53            SQLError::Internal("hierarchy retrieval cardinality exceeds u64".into())
54        })?;
55        Ok(Self {
56            sources: sources.into(),
57            schema,
58            physical_schema,
59            estimated_cardinality,
60        })
61    }
62}
63
64impl RowSource for HierarchyScoredDocumentSource {
65    fn schema(&self) -> &[String] {
66        &self.schema
67    }
68
69    fn physical_schema(&self) -> Option<&RowSchema> {
70        Some(&self.physical_schema)
71    }
72
73    fn estimated_cardinality(&self) -> Option<u64> {
74        Some(self.estimated_cardinality)
75    }
76
77    fn next_row(&mut self) -> ExecResult<Option<ResultRow>> {
78        Ok(self.next_batch(1)?.pop())
79    }
80
81    fn next_batch(&mut self, max_rows: usize) -> ExecResult<Vec<ResultRow>> {
82        let rows = self.next_physical_batch(max_rows)?;
83        Ok(rows
84            .iter()
85            .map(|row| self.physical_schema.view(row).to_result_row())
86            .collect())
87    }
88
89    fn next_physical_batch(&mut self, max_rows: usize) -> ExecResult<Vec<PhysicalRow>> {
90        let mut rows = Vec::with_capacity(max_rows);
91        while rows.len() < max_rows {
92            let Some(source) = self.sources.front_mut() else {
93                break;
94            };
95            let mut batch = source.next_physical_batch(max_rows - rows.len())?;
96            if batch.is_empty() {
97                self.sources.pop_front();
98            } else {
99                rows.append(&mut batch);
100            }
101        }
102        Ok(rows)
103    }
104}