uqa-execution 0.6.2

Volcano physical operators with row-batch pipelines
Documentation
//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Materialized, spilled, hash-key, and directional query result collection.

use super::{
    consumer::{QueryConsumerControl, QueryOutputMode, QueryRowConsumer},
    output::{QueryOutput, QueryRows},
    projection::{close_after_physical_failure, physical_exec_error, physical_work_mem_bytes},
    runtime::QueryRuntimeView,
};
use crate::RowSchemaExecution;
use smallvec::SmallVec;
use std::rc::Rc;
use uqa_core::Value;
use uqa_sql::SQLError;

#[cfg(test)]
mod tests;

pub fn collect_query_operator<'a>(
    runtime: QueryRuntimeView<'_>,
    columns: Vec<String>,
    operator: Box<dyn crate::PhysicalOperator + 'a>,
    output_mode: QueryOutputMode<'_>,
) -> Result<QueryOutput, SQLError> {
    let mut operator = runtime.diagnostics.observe(operator, "Query Pipeline")?;
    let internal_schema = operator.row_schema().clone();
    let column_types = columns
        .iter()
        .enumerate()
        .map(|(index, column)| {
            if internal_schema.columns().get(index) == Some(column) {
                internal_schema.column_type(index).cloned()
            } else {
                internal_schema
                    .position(column)
                    .and_then(|position| internal_schema.column_type(position).cloned())
            }
        })
        .collect();
    let rows = match output_mode {
        QueryOutputMode::Rows => collect_materialized_rows(operator.as_mut())?,
        QueryOutputMode::SharedSpill => {
            collect_spilled_rows(runtime, operator.as_mut(), internal_schema.clone())?
        }
        QueryOutputMode::ExistsKeySet(catalog) => {
            collect_exists_keys(&columns, operator.as_mut(), catalog)?
        }
        QueryOutputMode::RowConsumer(consumer) => collect_consumed_rows(
            &columns,
            &internal_schema,
            &mut operator,
            &consumer,
            runtime.cancellation,
        )?,
    };
    Ok(QueryOutput {
        columns,
        column_types,
        internal_schema,
        rows,
    })
}

fn collect_materialized_rows(
    operator: &mut dyn crate::PhysicalOperator,
) -> Result<QueryRows, SQLError> {
    let mut input =
        crate::physical::OperatorBatchCursor::open(operator).map_err(physical_exec_error)?;
    let mut rows = input
        .next()
        .transpose()
        .map_err(physical_exec_error)?
        .map_or_else(Vec::new, |batch| batch.rows);
    for batch in input {
        rows.extend(batch.map_err(physical_exec_error)?.rows);
    }
    Ok(QueryRows::Rows(rows))
}

fn collect_spilled_rows(
    runtime: QueryRuntimeView<'_>,
    operator: &mut dyn crate::PhysicalOperator,
    internal_schema: crate::RowSchema,
) -> Result<QueryRows, SQLError> {
    let work_mem = physical_work_mem_bytes(runtime).map_err(|error| {
        close_after_physical_failure(operator, error.into(), "prepare spill buffer")
    })?;
    let mut buffer = crate::SpillBuffer::new(work_mem.max(1));
    if let Err(error) = operator.open() {
        return Err(close_after_physical_failure(operator, error, "open"));
    }
    loop {
        let batch = match operator.next() {
            Ok(batch) => batch,
            Err(error) => {
                return Err(close_after_physical_failure(operator, error, "execution"));
            }
        };
        let Some(batch) = batch else {
            break;
        };
        if let Err(error) = buffer.push(batch) {
            return Err(close_after_physical_failure(
                operator,
                error,
                "spill buffering",
            ));
        }
    }
    operator.close().map_err(physical_exec_error)?;
    Ok(QueryRows::SharedSpill(
        buffer
            .into_shared(internal_schema)
            .map_err(physical_exec_error)?,
    ))
}

fn collect_exists_keys(
    columns: &[String],
    operator: &mut dyn crate::PhysicalOperator,
    catalog: Option<&dyn uqa_sql::expr::SQLValueCatalog>,
) -> Result<QueryRows, SQLError> {
    if operator.row_schema().len() < columns.len() {
        let error = SQLError::Internal(format!(
            "decorrelated EXISTS result has {} columns for {} keys",
            operator.row_schema().len(),
            columns.len()
        ));
        return Err(close_after_physical_failure(
            operator,
            error.into(),
            "prepare EXISTS keys",
        ));
    }
    let key_positions = (0..columns.len()).collect::<Vec<_>>();
    let types = key_positions
        .iter()
        .map(|position| operator.row_schema().column_type(*position).cloned())
        .collect();
    let mut keys = crate::CanonicalRowHashSet::with_sql_types(types);
    if let Err(error) = operator.open() {
        return Err(close_after_physical_failure(
            operator,
            error,
            "open EXISTS key input",
        ));
    }
    loop {
        let batch = match operator.next() {
            Ok(batch) => batch,
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator,
                    error,
                    "collect EXISTS keys",
                ));
            }
        };
        let Some(batch) = batch else {
            break;
        };
        for row in &batch.rows {
            let view = batch.schema.view(row);
            let mut key = SmallVec::<[&Value; 4]>::with_capacity(key_positions.len());
            let mut contains_null = false;
            for position in &key_positions {
                let Some(value) = view.value_at(*position) else {
                    contains_null = true;
                    break;
                };
                if matches!(value, Value::Null) {
                    contains_null = true;
                    break;
                }
                key.push(value);
            }
            if !contains_null {
                if let Err(error) = keys.insert_borrowed_with_catalog(&key, catalog) {
                    return Err(close_after_physical_failure(
                        operator,
                        error,
                        "hash EXISTS keys",
                    ));
                }
            }
        }
    }
    operator.close().map_err(physical_exec_error)?;
    Ok(QueryRows::ExistsKeySet(keys))
}

fn collect_consumed_rows(
    columns: &[String],
    internal_schema: &crate::RowSchema,
    operator: &mut Box<dyn crate::PhysicalOperator + '_>,
    consumer: &Rc<dyn QueryRowConsumer + '_>,
    cancellation: &uqa_core::CancellationToken,
) -> Result<QueryRows, SQLError> {
    if consumer.uses_directional_scan() {
        collect_directional_query_operator(columns, operator, consumer)?;
        return Ok(QueryRows::Rows(Vec::new()));
    }
    consumer.begin(columns, internal_schema).map_err(|error| {
        close_after_physical_failure(operator.as_mut(), error.into(), "begin row consumer")
    })?;
    if let Err(error) = operator.open() {
        return Err(close_after_physical_failure(
            operator.as_mut(),
            error,
            "open row consumer input",
        ));
    }
    let batched_input = operator.supports_batched_consumption();
    if batched_input && consumer.input_demand().is_none() {
        match consumer.collect_native_materialized(operator.as_mut(), cancellation) {
            Ok(true) => {
                operator.close().map_err(physical_exec_error)?;
                return Ok(QueryRows::Rows(Vec::new()));
            }
            Ok(false) => {}
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    error,
                    "collect native materialized input",
                ));
            }
        }
    }
    loop {
        let demand = consumer
            .input_demand()
            .or_else(|| (!batched_input).then_some(crate::physical::demand::ONE));
        let next = match demand {
            Some(rows) => operator.next_with_demand(rows),
            None => operator.next(),
        };
        let batch = match next {
            Ok(batch) => batch,
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    error,
                    "execute row consumer input",
                ));
            }
        };
        let Some(batch) = batch else {
            break;
        };
        match consumer.consume_batch(batch) {
            Ok(QueryConsumerControl::Continue) => {}
            Ok(QueryConsumerControl::Stop) => break,
            Ok(QueryConsumerControl::Rewind) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    crate::ExecError::Other("forward-only row consumer requested rewind".into()),
                    "consume query row",
                ));
            }
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    crate::ExecError::SQL(error),
                    "consume query row",
                ));
            }
        }
    }
    operator.close().map_err(physical_exec_error)?;
    Ok(QueryRows::Rows(Vec::new()))
}

fn collect_directional_query_operator(
    columns: &[String],
    operator: &mut Box<dyn crate::PhysicalOperator + '_>,
    consumer: &Rc<dyn QueryRowConsumer + '_>,
) -> Result<(), SQLError> {
    open_directional_consumer(columns, operator, consumer)?;
    loop {
        let batch = match operator.next_direction(consumer.scan_direction()) {
            Ok(batch) => batch,
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    error,
                    "execute directional row consumer input",
                ));
            }
        };
        let control = if let Some(batch) = batch {
            if batch.rows.len() != 1 {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    crate::ExecError::Other(format!(
                        "directional query operator returned {} rows in one pull",
                        batch.rows.len()
                    )),
                    "execute directional row consumer input",
                ));
            }
            let crate::Batch { schema, mut rows } = batch;
            let row = crate::OwnedPhysicalRow::new(
                schema,
                rows.pop().expect("directional batch width checked"),
            );
            consumer.consume(row)
        } else {
            consumer.direction_exhausted()
        };
        let mut control = match control {
            Ok(control) => control,
            Err(error) => {
                return Err(close_after_physical_failure(
                    operator.as_mut(),
                    crate::ExecError::SQL(error),
                    "consume directional query row",
                ));
            }
        };
        loop {
            match control {
                QueryConsumerControl::Continue => break,
                QueryConsumerControl::Stop => {
                    operator.close().map_err(physical_exec_error)?;
                    return Ok(());
                }
                QueryConsumerControl::Rewind => {
                    if let Err(error) = operator.rewind() {
                        return Err(close_after_physical_failure(
                            operator.as_mut(),
                            error,
                            "rewind directional query input",
                        ));
                    }
                    control = match consumer.rewound() {
                        Ok(control) => control,
                        Err(error) => {
                            return Err(close_after_physical_failure(
                                operator.as_mut(),
                                crate::ExecError::SQL(error),
                                "acknowledge directional query rewind",
                            ));
                        }
                    };
                }
            }
        }
    }
}

fn open_directional_consumer(
    columns: &[String],
    operator: &mut Box<dyn crate::PhysicalOperator + '_>,
    consumer: &Rc<dyn QueryRowConsumer + '_>,
) -> Result<(), SQLError> {
    let support = operator.backward_scan_support();
    consumer
        .directional_scan_prepared(support)
        .map_err(|error| {
            close_after_physical_failure(
                operator.as_mut(),
                error.into(),
                "prepare directional consumer",
            )
        })?;
    if support != crate::BackwardScanSupport::Native {
        let placeholder: Box<dyn crate::PhysicalOperator> = Box::new(
            crate::TableScan::from_physical_rows(operator.row_schema().clone(), Vec::new()),
        );
        let inner = std::mem::replace(operator, placeholder);
        *operator = Box::new(crate::ScrollMaterialize::new(inner));
    }
    consumer
        .begin(columns, operator.row_schema())
        .map_err(|error| {
            close_after_physical_failure(
                operator.as_mut(),
                error.into(),
                "begin directional consumer",
            )
        })?;
    if let Err(error) = operator.open() {
        return Err(close_after_physical_failure(
            operator.as_mut(),
            error,
            "open directional row consumer input",
        ));
    }
    Ok(())
}