Skip to main content

uqa_execution/
lib.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Volcano-model physical operator pipeline.
8//!
9//! The pipeline uses an `open` / `next` / `close` iterator protocol with
10//! row-oriented batches so the
11//! engine can expose the operator surface without the `arrow-rs` build
12//! dependency. The operator trait and operator catalogue defined here are
13//! the execution contract.
14//!
15//! # Operator catalogue
16//!
17//! * [`scan::TableScan`] -- pulls every row of a logical relation into
18//!   the pipeline. The relation source is supplied through
19//!   [`scan::RowSource`], so the caller decides whether the rows come
20//!   from the engine's per-table store, a CTE materialisation, or an
21//!   FDW.
22//! * [`relational::Filter`] -- keeps rows for which the predicate
23//!   evaluates truthy.
24//! * [`relational::Project`] -- emits a new schema by evaluating an
25//!   expression list against each row.
26//! * [`relational::Sort`] -- fully materialises the input, sorts by a
27//!   list of `(expr, descending)` keys, and yields the sorted rows in
28//!   batches.
29//! * [`relational::Limit`] -- caps the row count at `offset + limit`,
30//!   skipping the first `offset` rows.
31//! * [`relational::HashAggregate`] -- group-by + aggregate over a
32//!   blocking input, supporting `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`.
33//! * [`relational::Window`] -- partition + order + frame-aware
34//!   computation of `ROW_NUMBER` / `RANK` / `DENSE_RANK` / `LAG` /
35//!   `LEAD` / `NTILE` and pure aggregate windows.
36//! * [`spill::SpillBuffer`] -- disk-backed row buffer for blocking
37//!   operators that exceed an in-memory budget.
38
39#![allow(
40    clippy::enum_glob_use,
41    clippy::implicit_hasher,
42    clippy::iter_without_into_iter,
43    clippy::struct_field_names,
44    clippy::single_match_else,
45    clippy::option_if_let_else,
46    clippy::map_unwrap_or,
47    clippy::filter_map_identity,
48    clippy::needless_collect,
49    clippy::explicit_iter_loop,
50    clippy::manual_let_else,
51    clippy::cast_lossless,
52    clippy::explicit_auto_deref,
53    clippy::needless_pass_by_value,
54    clippy::unnecessary_wraps,
55    clippy::similar_names,
56    clippy::module_name_repetitions
57)]
58
59pub mod batch;
60pub mod column_selection;
61pub mod columnar_batch;
62pub mod distinct;
63pub mod external_sort;
64pub mod join;
65pub mod join_output;
66pub mod lateral_join;
67pub mod map_rows;
68pub mod physical;
69pub mod project_set;
70pub mod projected_predicate;
71pub mod projected_row;
72pub mod relational;
73pub mod scalar;
74pub mod scan;
75pub mod scope_overlay;
76pub mod scroll_materialize;
77pub mod set_operation;
78pub mod spill;
79pub mod spill_scan;
80pub mod type_resolution;
81
82pub use batch::{
83    Batch, ColumnIdentity, OwnedPhysicalRow, PhysicalRow, PhysicalRowView, RowLockOrigin,
84    RowProjectionValue, RowSchema, DEFAULT_BATCH_SIZE,
85};
86pub use column_selection::ColumnSelection;
87pub use columnar_batch::{ColumnVector, ColumnarBatch};
88pub use distinct::{
89    canonical_row_key, hash_canonical_row, try_pack_compact_text_pair, CanonicalRowHashSet,
90    Distinct, ExactRowSet,
91};
92pub use external_sort::{ExternalSort, EXTERNAL_SORT_MERGE_FAN_IN};
93pub use join::{HashJoin, NestedLoopJoin};
94pub use join_output::{JoinOutput, JoinOutputSource};
95pub use lateral_join::{LateralJoin, LateralRows, LateralSource};
96pub use map_rows::{MapRows, SharedRowMapper};
97pub use physical::{
98    order_expression_position, ordering_satisfies, BackwardScanSupport, ExecError, ExecResult,
99    OperatorBatchCursor, PhysicalOperator, PhysicalOrder, PhysicalScanDirection,
100};
101pub use project_set::{
102    PhysicalProjectRows, PhysicalProjectSet, PhysicalSetProjector, ProjectRows, ProjectSet,
103    SetProjector,
104};
105pub use projected_predicate::ProjectedPredicate;
106pub use projected_row::{ProjectedRow, ProjectedValueSlot};
107pub use relational::{
108    AggregateExecutor, AggregateKind, AggregateSpec, ExpressionEvaluator, Filter, HashAggregate,
109    Limit, Project, ProjectionTarget, RowPredicate, SetOperation, SharedExpressionEvaluator,
110    SharedRowPredicate, Sort, SortKey, Window, WindowExecutor, WindowKind,
111};
112pub use scalar::{
113    eval_call_arguments, eval_scalar, scalar_call_argument, scalar_call_arguments,
114    validate_scalar_call_arguments, ScalarCallArgument, ScalarEvalContext, ScalarExpr,
115    ScalarFrameBound, ScalarOrder, ScalarSubqueryRunner, ScalarWindowFrame, ScalarWindowSpec,
116    SubqueryId, SubqueryResult,
117};
118pub use scan::{PhysicalRowIteratorScan, RowIteratorScan, RowSource, TableScan};
119pub use scope_overlay::ScopeOverlay;
120pub use scroll_materialize::{prepare_backward_scan, ScrollMaterialize};
121pub use set_operation::ExternalSetOperation;
122pub use spill::{IndexedSpill, SharedSpill, SharedSpillReader, SpillBuffer};
123pub use spill_scan::{SharedSpillScan, SpillScan};
124pub use type_resolution::{
125    bind_type_introspection, bind_type_introspection_with_resolver,
126    builtin_function_argument_targets, common_context_expression_type, common_type,
127    equality_operand_type, foreign_key_operand_type, resolve_checksum_overload,
128    resolve_gamma_overload, resolve_json_strip_overload, resolve_length_overload,
129    resolve_md5_overload, resolve_reverse_overload, scalar_type, scalar_type_with_resolver,
130    values_column_types, BuiltinFunctionOverload, FunctionTypeResolver, ResolvedChecksumOverload,
131    ResolvedFunctionOverload, ResolvedGammaOverload, ResolvedJsonStripOverload,
132    ResolvedLengthOverload, ResolvedMd5Overload, ResolvedReverseOverload,
133    ResolvedStringBinaryOverload, ResolvedTextByteaOverload,
134};
135#[doc(hidden)]
136pub use type_resolution::{
137    builtin_binding_matches, builtin_name_matches, canonical_column_type_name,
138    canonical_routine_type_name, effective_overload_argument_type,
139    effective_overload_argument_type_with_params, fixed_builtin_return_type,
140    function_call_argument_signature, function_resolution_error, is_fixed_builtin,
141    match_builtin_function_overload, match_function_signature, match_routine_signature,
142    rank_function_matches, require_equality_operator, require_ordering_operator,
143    resolve_fixed_builtin_call, resolve_local_builtin_overload, routine_polymorphic_type,
144    routine_type_accepts_implicit_cast, routine_type_category, routine_type_is_preferred,
145    FunctionCallArgumentSignature, FunctionParameterDescriptor, MatchedBuiltinFunction,
146    MatchedFunctionSignature, MatchedRoutineSignature, RankedFunctionMatch,
147    ResolvedFixedBuiltinCall, RoutineCallDescriptor, RoutineCoercionTarget,
148    RoutineParameterDescriptor, RoutinePolymorphicFamily, RoutinePolymorphicType,
149    RoutineSignatureMatchError, RoutineTypeSubstitutions, RoutineVariadicMode, RoutineVariadicPlan,
150};