You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@datafusion.apache.org by "Xuanwo (via GitHub)" <gi...@apache.org> on 2026/07/23 05:06:07 UTC

[PR] feat: add ASOF join physical operator [datafusion]

Xuanwo opened a new pull request, #23828:
URL: https://github.com/apache/datafusion/pull/23828

   ## Which issue does this PR close?
   
   - Part of #318.
   - Umbrella PR: #23738.
   
   ## Rationale for this change
   
   This is the first layer of the ASOF JOIN stack. It establishes the physical
   execution contract independently so later logical-plan, SQL, DataFrame, and
   serialization changes can be reviewed as smaller follow-up PRs.
   
   ## What changes are included in this PR?
   
   - Add `AsOfJoinExec` for left-preserving, Snowflake-style ASOF semantics.
   - Require compatible equality partitioning and ordering on both inputs.
   - Preserve merge state across input and output batch boundaries.
   - Define output properties, statistics, and ASOF-specific metrics.
   - Add physical operator tests covering match directions, equality groups,
     batch boundaries, unmatched rows, and invalid contracts.
   
   ## Are these changes tested?
   
   Yes:
   
   - `cargo fmt --all`
   - `cargo clippy --all-targets --all-features -- -D warnings`
   - `cargo test -p datafusion-physical-plan joins::asof_join --all-features`
   - Extended workspace tests from the contributor guide
   
   ## Are there any user-facing changes?
   
   This adds a new physical operator API. SQL and DataFrame APIs are intentionally
   left to dependent PRs in the ASOF JOIN stack.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "alamb (via GitHub)" <gi...@apache.org>.
alamb commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5401563827

   <img width="302" height="200" alt="200" src="https://github.com/user-attachments/assets/3840f744-e198-43b1-a3b9-25e97417b996" />
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701266295


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {
+    schema: SchemaRef,
+    left: InputCursor,
+    right: InputCursor,
+    op: Operator,
+    right_output_indices: Vec<usize>,
+    candidate: Option<Candidate>,
+    group_sort_options: Vec<SortOptions>,
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    pending_left: PendingRows,
+    pending_right: PendingRows,
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {

Review Comment:
   Added!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701260644


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(

Review Comment:
   DONE.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701254555


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec

Review Comment:
   Agreed! I added a note that broadcast-left and repartitioned strategies can follow for other input-size and key-distribution profiles.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,

Review Comment:
   Added.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5054848361

   ## [Codecov](https://app.codecov.io/gh/apache/datafusion/pull/23828?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
   :x: Patch coverage is `79.94042%` with `202 lines` in your changes missing coverage. Please review.
   :white_check_mark: Project coverage is 80.72%. Comparing base ([`ba8796e`](https://app.codecov.io/gh/apache/datafusion/commit/ba8796e460bd60b8239c5f2f51f83d464efc177b?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`e546de5`](https://app.codecov.io/gh/apache/datafusion/commit/e546de5510de599c91f756bef4bf45243d93011a?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
   
   | [Files with missing lines](https://app.codecov.io/gh/apache/datafusion/pull/23828?dropdown=coverage&src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Patch % | Lines |
   |---|---|---|
   | [datafusion/physical-plan/src/joins/asof\_join.rs](https://app.codecov.io/gh/apache/datafusion/pull/23828?src=pr&el=tree&filepath=datafusion%2Fphysical-plan%2Fsrc%2Fjoins%2Fasof_join.rs&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#diff-ZGF0YWZ1c2lvbi9waHlzaWNhbC1wbGFuL3NyYy9qb2lucy9hc29mX2pvaW4ucnM=) | 79.94% | [147 Missing and 55 partials :warning: ](https://app.codecov.io/gh/apache/datafusion/pull/23828?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) |
   
   <details><summary>Additional details and impacted files</summary>
   
   
   
   ```diff
   @@            Coverage Diff             @@
   ##             main   #23828      +/-   ##
   ==========================================
   - Coverage   80.73%   80.72%   -0.01%     
   ==========================================
     Files        1089     1090       +1     
     Lines      368948   369955    +1007     
     Branches   368948   369955    +1007     
   ==========================================
   + Hits       297857   298658     +801     
   - Misses      53334    53481     +147     
   - Partials    17757    17816      +59     
   ```
   </details>
   
   [:umbrella: View full report in Codecov by Harness](https://app.codecov.io/gh/apache/datafusion/pull/23828?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).   
   :loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
   <details><summary> :rocket: New features to boost your workflow: </summary>
   
   - :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
   - :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
   </details>


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701257208


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left

Review Comment:
   Agreed! I added a note that broadcast-left and repartitioned strategies can follow for other input-size and key-distribution profiles.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3793759010


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -997,21 +1000,23 @@ impl AsOfJoinStreamState {
     ///   emit the left row with the candidate (or NULLs), then advance left
     /// flush pending rows without resetting either cursor or the candidate
     /// ```
-    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+    fn poll_next_impl(

Review Comment:
   I haven't fully figure out what's the best practice to implement the state machines to make them easy to read and extend, probably it is:
   - generator pattern https://github.com/apache/datafusion/issues/23974
   - If we need to draw a state machine to understand its mechanism, then use explicit state management like https://github.com/apache/datafusion/blob/9a83691aadaadbf72bf4c8b7d87bd28af9dc68dd/datafusion/physical-plan/src/aggregates/hash_stream.rs#L175
   
   Not an issue for now, we could experiment in the future.
   
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3792156253


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    /// Standard output-row and elapsed-compute metrics.
+    baseline: BaselineMetrics,
+    /// Peak bytes retained for the shared right input.
+    ///
+    /// `peak_memory_usage` records this as `MetricValue::PeakMemoryUsage`; `Gauge`
+    /// is the handle used to update that metric.
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,

Review Comment:
   Arc is intentional here: it keeps per-row clones O(1) and gives PendingRows a stable identity for deduplication. Added a short comment.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {

Review Comment:
   Agreed. I moved the state into AsOfJoinStream and made it implement Stream directly.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    /// Standard output-row and elapsed-compute metrics.
+    baseline: BaselineMetrics,
+    /// Peak bytes retained for the shared right input.
+    ///
+    /// `peak_memory_usage` records this as `MetricValue::PeakMemoryUsage`; `Gauge`
+    /// is the handle used to update that metric.
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Projected output columns and their input sides.
+    column_indices: Vec<ColumnIndex>,
+    /// Whether any projected column needs a right row reference.
+    projects_right: bool,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        column_indices: Vec<ColumnIndex>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            projects_right: column_indices
+                .iter()
+                .any(|column| column.side == JoinSide::Right),
+            column_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    ///
+    /// ```text
+    /// while the output batch is not full:
+    ///   load the current left row, or flush/finish at left EOF
+    ///   if its match or equality key is NULL, emit it unmatched and advance left
+    ///   clear the candidate if the left equality group changed
+    ///   while the current right row is before the left group or is eligible:
+    ///     remember the nearest eligible row and advance right
+    ///   emit the left row with the candidate (or NULLs), then advance left
+    /// flush pending rows without resetting either cursor or the candidate
+    /// ```
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance

Review Comment:
   Agreed. I removed RightAction and now update Option<Candidate> directly, using continue/break for cursor control.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701267569


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {
+    schema: SchemaRef,
+    left: InputCursor,
+    right: InputCursor,
+    op: Operator,
+    right_output_indices: Vec<usize>,
+    candidate: Option<Candidate>,
+    group_sort_options: Vec<SortOptions>,
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    pending_left: PendingRows,
+    pending_right: PendingRows,
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {

Review Comment:
   Updated.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701263102


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,

Review Comment:
   `UnspecifiedDistribution` is intentional for the left side of the broadcast-right plan: every left partition scans the complete right input, so equality keys do not require co-partitioning. Requiring `KeyPartitione`d would describe the repartition-based strategy and could reduce probe-side parallelism. I added this rationale inline.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]

Review Comment:
   DONE



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5312704913

   cc @jayzhan211, @xudong963, and @alamb, would you like to take another look and move forward?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "jayzhan211 (via GitHub)" <gi...@apache.org>.
jayzhan211 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3804351176


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1780 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is [`AsOfJoinStream::poll_next_impl`].
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{Stream, StreamExt, TryStreamExt, future::poll_fn, ready, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    RecordBatchStream, ReplaceChildrenOptions, SendableRecordBatchStream,
+    validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {

Review Comment:
   ```suggestion
           // ASOF emits exactly one row for each left row and never reorders the
           // left input. The right input is scanned independently.
           vec![true, false]
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5202130206

   There is no new commits after the previous review, you may have forgotten to push the local changes 🤔 @Xuanwo 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701264322


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(

Review Comment:
   I kept this small override because ASOF has two exact facts the default would discard: the output row count equals the left row count, and unmodified left columns retain their statistics. Right-side column statistics remain unknown. I added a comment to make that scope explicit.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5357685901

   Sure, I'm interested in helping with this project 🫡


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3747748177


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,

Review Comment:
   I think this left input is also possible to get projected, we could instead use the existing convention for projection:
   https://github.com/apache/datafusion/blob/308e21226ee4d96db4a5dc4778f99197d3eb3342/datafusion/physical-plan/src/joins/nested_loop_join.rs#L236



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {

Review Comment:
   I recommend to add a pseudocode in the comment for the algorithm implemented in this function.
   
   Besides, since this is the major loop, I think we can also point to this function from `execute()` and top doc comments, like 'the key state machine entry point is the `next_batch()` function'



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {

Review Comment:
   We could add some comments to this struct.
   
   Optional suggestion: I think we could put it inside the right `InputCursor` to simplify the implementation.
   
   Logically, this represents the "previous valid row," and it seems more like an internal implementation detail of `InputCursor` than a standalone module. I imagine the state machine code would be easier to understand if we structured it this way.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,

Review Comment:
   I remember here we might want to use another metrics type `PeakMemoryUsage` , this can ensure the unit is displayed correctly



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,

Review Comment:
   I think those 4 metrics are not useful (maybe I don't understand some of them correctly and they are useful, this case let's add some comments)
   
   An alternative is we can further simplify all of them away, and only keep `BaselineMetrics`, later we might have better idea what metrics to add, and we could use a separate PR to add them back.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,

Review Comment:
   I think hash partitioning on the equality keys can still be useful in some workloads, even if another side is broadcasted, but I think this is not important at the moment, let's skip that.
   
   Is it the case the optimizer will insert round-robin repartition, if we declare this `UnspecifiedDistribution`? It should be fine if it's doing so, I was a little bit confused by this name 🤔 



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]

Review Comment:
   ```suggestion
       // Ensure the build-side memory usage equals the sum of all build-side input
       // batches, verifying that the build-side buffer is shared.
       #[tokio::test]
   ```



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(

Review Comment:
   I see, this makes sense.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(

Review Comment:
   Here is a reference to write assertions for similar tests easier:
   https://github.com/apache/datafusion/blob/308e21226ee4d96db4a5dc4778f99197d3eb3342/datafusion/physical-plan/src/joins/nested_loop_join.rs#L3350



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn shared_right_buffers_are_reserved_once() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![make_batch(
+                &left_schema,
+                vec![Some("A")],
+                vec![Some(4095)],
+                vec![0],
+            )?]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let row_count = 4096;
+        let parent = make_batch(
+            &right_schema,
+            vec![Some("A"); row_count],
+            (0..row_count).map(|value| Some(value as i64)).collect(),
+            (0..row_count as i32).collect(),
+        )?;
+        let mut memory_counter = RecordBatchMemoryCounter::new();
+        let retained_size = memory_counter.count_batch(&parent);
+        let right_batches = (0..16)
+            .map(|index| parent.slice(index * 256, 256))
+            .collect();
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let runtime = RuntimeEnvBuilder::new()
+            .with_memory_limit(retained_size, 1.0)
+            .build_arc()?;
+        let context = Arc::new(TaskContext::default().with_runtime(runtime));
+
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(prices, vec![Some(4095)]);
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_mem_used")
+                .map(|value| value.as_usize()),
+            Some(retained_size)
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn preserves_dictionary_outputs_across_large_flush() -> Result<()> {
+        let dictionary_type =
+            DataType::Dictionary(Box::new(DataType::Int8), Box::new(DataType::Utf8));
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("payload", dictionary_type.clone(), false),
+        ]));
+        let mut left_payload = StringDictionaryBuilder::<Int8Type>::new();
+        for _ in 0..129 {
+            left_payload.append_value("left");
+        }
+        let left_batch = RecordBatch::try_new(
+            Arc::clone(&left_schema),
+            vec![
+                Arc::new(StringArray::from(vec!["A"; 129])),
+                Arc::new(Int64Array::from_iter_values(-1..128)),
+                Arc::new(left_payload.finish()),
+            ],
+        )?;
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![left_batch]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("payload", dictionary_type.clone(), false),
+        ]));
+        let mut right_payload = StringDictionaryBuilder::<Int8Type>::new();
+        right_payload.append_value("right");
+        let right_batch = RecordBatch::try_new(
+            Arc::clone(&right_schema),
+            vec![
+                Arc::new(StringArray::from(vec!["A"])),
+                Arc::new(Int64Array::from(vec![0])),
+                Arc::new(right_payload.finish()),
+            ],
+        )?;
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![right_batch]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(256)),
+        );
+        let batches = collect(exec, context).await?;
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].num_rows(), 129);
+        assert_eq!(batches[0].column(2).data_type(), &dictionary_type);
+        assert_eq!(batches[0].column(3).data_type(), &dictionary_type);
+
+        let right_output = batches[0]
+            .column(3)
+            .as_any()
+            .downcast_ref::<DictionaryArray<Int8Type>>()
+            .expect("right output must remain Dictionary(Int8, Utf8)");
+        assert!(right_output.is_null(0));
+        assert_eq!(right_output.null_count(), 1);
+        let values = right_output
+            .values()
+            .as_any()
+            .downcast_ref::<StringArray>()
+            .expect("dictionary values must be Utf8");
+        for row in 1..129 {
+            assert_eq!(
+                values.value(right_output.keys().value(row) as usize),
+                "right"
+            );
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn rejects_volatile_physical_expressions() -> Result<()> {
+        let exec = test_exec()?;
+        let volatile = Arc::new(VolatileExpr) as PhysicalExprRef;
+        let match_error = AsOfJoinExec::try_new(
+            Arc::clone(&exec.left),
+            Arc::clone(&exec.right),
+            exec.on.clone(),
+            AsOfMatchExpr::new(
+                Arc::clone(&volatile),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )
+        .expect_err("volatile match expression must be rejected");
+        assert!(match_error.to_string().contains("must be deterministic"));
+
+        let equality_error = AsOfJoinExec::try_new(
+            Arc::clone(&exec.left),
+            Arc::clone(&exec.right),
+            vec![(volatile, Arc::new(PhysicalColumn::new("key", 0)))],
+            exec.match_condition.clone(),
+            vec![2],
+        )
+        .expect_err("volatile equality expression must be rejected");
+        assert!(equality_error.to_string().contains("must be deterministic"));
+        Ok(())
+    }
+
+    #[test]
+    fn properties_and_statistics_follow_left_preserving_contract() -> Result<()> {

Review Comment:
   Probably it's not necessary to assert the distribution and ordering properties here



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {

Review Comment:
   optional: It looks like if we unify `ensure_row()` and `advance()`, the state machine code can get simpler.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {

Review Comment:
   I think this test don't have a meaningful test goal right now, and it adds maintenance overhead.
   
   It would be better to test it by asserting the plan shape, after we have SQL integration. And I think we could remove it now.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {

Review Comment:
   This test name is a bit confusing, this test looks like a `simple_query()`



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn shared_right_buffers_are_reserved_once() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![make_batch(
+                &left_schema,
+                vec![Some("A")],
+                vec![Some(4095)],
+                vec![0],
+            )?]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let row_count = 4096;
+        let parent = make_batch(
+            &right_schema,
+            vec![Some("A"); row_count],
+            (0..row_count).map(|value| Some(value as i64)).collect(),
+            (0..row_count as i32).collect(),
+        )?;
+        let mut memory_counter = RecordBatchMemoryCounter::new();
+        let retained_size = memory_counter.count_batch(&parent);
+        let right_batches = (0..16)
+            .map(|index| parent.slice(index * 256, 256))
+            .collect();
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let runtime = RuntimeEnvBuilder::new()
+            .with_memory_limit(retained_size, 1.0)
+            .build_arc()?;
+        let context = Arc::new(TaskContext::default().with_runtime(runtime));
+
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(prices, vec![Some(4095)]);
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_mem_used")
+                .map(|value| value.as_usize()),
+            Some(retained_size)
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn preserves_dictionary_outputs_across_large_flush() -> Result<()> {

Review Comment:
   I don't know if we should make such guarantee 🤔 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701261299


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }

Review Comment:
   Removed.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3757466743


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {

Review Comment:
   I kept them separate for now: `ensure_row()` loads or peeks without movement, while `advance()` is called only after the state machine selects `Advance` or `Candidate`. That keeps the `Stop` path explicit. I would revisit this together with cursor fast-forwarding.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,

Review Comment:
   Agreed. I removed the four extra counters and kept only `BaselineMetrics` plus the build-side peak-memory metric.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,

Review Comment:
   Good catch. `MetricBuilder::peak_memory_usage` creates a `MetricValue::PeakMemoryUsage`; `Gauge` is only the update handle. I added a comment to make that explicit.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {

Review Comment:
   Renamed it to `simple_query`.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {

Review Comment:
   Removed. I agree that plan-shape coverage is better added with the SQL integration.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn shared_right_buffers_are_reserved_once() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![make_batch(
+                &left_schema,
+                vec![Some("A")],
+                vec![Some(4095)],
+                vec![0],
+            )?]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let row_count = 4096;
+        let parent = make_batch(
+            &right_schema,
+            vec![Some("A"); row_count],
+            (0..row_count).map(|value| Some(value as i64)).collect(),
+            (0..row_count as i32).collect(),
+        )?;
+        let mut memory_counter = RecordBatchMemoryCounter::new();
+        let retained_size = memory_counter.count_batch(&parent);
+        let right_batches = (0..16)
+            .map(|index| parent.slice(index * 256, 256))
+            .collect();
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let runtime = RuntimeEnvBuilder::new()
+            .with_memory_limit(retained_size, 1.0)
+            .build_arc()?;
+        let context = Arc::new(TaskContext::default().with_runtime(runtime));
+
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(prices, vec![Some(4095)]);
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_mem_used")
+                .map(|value| value.as_usize()),
+            Some(retained_size)
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn preserves_dictionary_outputs_across_large_flush() -> Result<()> {

Review Comment:
   Agreed — I removed this test rather than making dictionary preservation part of the initial ASOF contract.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3757467989


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn shared_right_buffers_are_reserved_once() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![make_batch(
+                &left_schema,
+                vec![Some("A")],
+                vec![Some(4095)],
+                vec![0],
+            )?]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let row_count = 4096;
+        let parent = make_batch(
+            &right_schema,
+            vec![Some("A"); row_count],
+            (0..row_count).map(|value| Some(value as i64)).collect(),
+            (0..row_count as i32).collect(),
+        )?;
+        let mut memory_counter = RecordBatchMemoryCounter::new();
+        let retained_size = memory_counter.count_batch(&parent);
+        let right_batches = (0..16)
+            .map(|index| parent.slice(index * 256, 256))
+            .collect();
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let runtime = RuntimeEnvBuilder::new()
+            .with_memory_limit(retained_size, 1.0)
+            .build_arc()?;
+        let context = Arc::new(TaskContext::default().with_runtime(runtime));
+
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(prices, vec![Some(4095)]);
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_mem_used")
+                .map(|value| value.as_usize()),
+            Some(retained_size)
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn preserves_dictionary_outputs_across_large_flush() -> Result<()> {
+        let dictionary_type =
+            DataType::Dictionary(Box::new(DataType::Int8), Box::new(DataType::Utf8));
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("payload", dictionary_type.clone(), false),
+        ]));
+        let mut left_payload = StringDictionaryBuilder::<Int8Type>::new();
+        for _ in 0..129 {
+            left_payload.append_value("left");
+        }
+        let left_batch = RecordBatch::try_new(
+            Arc::clone(&left_schema),
+            vec![
+                Arc::new(StringArray::from(vec!["A"; 129])),
+                Arc::new(Int64Array::from_iter_values(-1..128)),
+                Arc::new(left_payload.finish()),
+            ],
+        )?;
+        let left = TestMemoryExec::try_new_exec(
+            &[vec![left_batch]],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("payload", dictionary_type.clone(), false),
+        ]));
+        let mut right_payload = StringDictionaryBuilder::<Int8Type>::new();
+        right_payload.append_value("right");
+        let right_batch = RecordBatch::try_new(
+            Arc::clone(&right_schema),
+            vec![
+                Arc::new(StringArray::from(vec!["A"])),
+                Arc::new(Int64Array::from(vec![0])),
+                Arc::new(right_payload.finish()),
+            ],
+        )?;
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![right_batch]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![(
+                Arc::new(PhysicalColumn::new("key", 0)),
+                Arc::new(PhysicalColumn::new("key", 0)),
+            )],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(256)),
+        );
+        let batches = collect(exec, context).await?;
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].num_rows(), 129);
+        assert_eq!(batches[0].column(2).data_type(), &dictionary_type);
+        assert_eq!(batches[0].column(3).data_type(), &dictionary_type);
+
+        let right_output = batches[0]
+            .column(3)
+            .as_any()
+            .downcast_ref::<DictionaryArray<Int8Type>>()
+            .expect("right output must remain Dictionary(Int8, Utf8)");
+        assert!(right_output.is_null(0));
+        assert_eq!(right_output.null_count(), 1);
+        let values = right_output
+            .values()
+            .as_any()
+            .downcast_ref::<StringArray>()
+            .expect("dictionary values must be Utf8");
+        for row in 1..129 {
+            assert_eq!(
+                values.value(right_output.keys().value(row) as usize),
+                "right"
+            );
+        }
+        Ok(())
+    }
+
+    #[test]
+    fn rejects_volatile_physical_expressions() -> Result<()> {
+        let exec = test_exec()?;
+        let volatile = Arc::new(VolatileExpr) as PhysicalExprRef;
+        let match_error = AsOfJoinExec::try_new(
+            Arc::clone(&exec.left),
+            Arc::clone(&exec.right),
+            exec.on.clone(),
+            AsOfMatchExpr::new(
+                Arc::clone(&volatile),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )
+        .expect_err("volatile match expression must be rejected");
+        assert!(match_error.to_string().contains("must be deterministic"));
+
+        let equality_error = AsOfJoinExec::try_new(
+            Arc::clone(&exec.left),
+            Arc::clone(&exec.right),
+            vec![(volatile, Arc::new(PhysicalColumn::new("key", 0)))],
+            exec.match_condition.clone(),
+            vec![2],
+        )
+        .expect_err("volatile equality expression must be rejected");
+        assert!(equality_error.to_string().contains("must be deterministic"));
+        Ok(())
+    }
+
+    #[test]
+    fn properties_and_statistics_follow_left_preserving_contract() -> Result<()> {

Review Comment:
   Removed the distribution and ordering assertions. The remaining test now focuses only on the explicit statistics contract.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(

Review Comment:
   Thanks for the reference. The executor result tests now use `batches_to_sort_string` with inline snapshots.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    /// Materializes pending row references while preserving both cursors and the
+    /// current equality-group candidate for the next output batch.
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+/// Validates all invariants required by the forward-only ASOF state machine.
+fn validate_asof_join(
+    left: &dyn ExecutionPlan,
+    right: &dyn ExecutionPlan,
+    on: &JoinOn,
+    match_condition: &AsOfMatchExpr,
+    right_output_indices: &[usize],
+) -> Result<()> {
+    if !matches!(
+        match_condition.op,
+        Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+    ) {
+        return plan_err!(
+            "AsOfJoinExec requires <, <=, >, or >=, found {}",
+            match_condition.op
+        );
+    }
+    if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+        return plan_err!("AsOfJoinExec requires bounded inputs");
+    }
+    if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+        return plan_err!("AsOfJoinExec match expression must be deterministic");
+    }
+    if on
+        .iter()
+        .any(|(left, right)| is_volatile(left) || is_volatile(right))
+    {
+        return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+    }
+
+    let left_schema = left.schema();
+    let right_schema = right.schema();
+    validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+    validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+    for (left_expr, right_expr) in on {
+        validate_expr_side(left_expr, &left_schema, "left equality")?;
+        validate_expr_side(right_expr, &right_schema, "right equality")?;
+        let left_type = left_expr.data_type(&left_schema)?;
+        let right_type = right_expr.data_type(&right_schema)?;
+        if left_type != right_type {
+            return plan_err!(
+                "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+            );
+        }
+        if !datafusion_expr::utils::can_hash(&left_type) {
+            return plan_err!(
+                "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+            );
+        }
+    }
+    let left_match_type = match_condition.left.data_type(&left_schema)?;
+    let right_match_type = match_condition.right.data_type(&right_schema)?;
+    if left_match_type != right_match_type {
+        return plan_err!(
+            "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+        );
+    }
+    if let Some(index) = right_output_indices
+        .iter()
+        .find(|index| **index >= right_schema.fields().len())
+    {
+        return plan_err!(
+            "AsOfJoinExec right output index {index} is outside schema with {} fields",
+            right_schema.fields().len()
+        );
+    }
+    if !right_output_indices
+        .windows(2)
+        .all(|pair| pair[0] < pair[1])
+    {
+        return plan_err!(
+            "AsOfJoinExec right output indices must be strictly increasing"
+        );
+    }
+    Ok(())
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    // These tests cover physical-only contracts that SQL logic tests cannot
+    // observe, including batch-boundary state, shared build memory, Arrow type
+    // preservation, and execution properties. End-to-end SQL semantics live in
+    // the dependent SQL layer.
+
+    use super::*;
+    use crate::test::TestMemoryExec;
+    use crate::{collect, collect_partitioned};
+    use arrow::array::{
+        DictionaryArray, Int32Array, Int64Array, StringArray, StringDictionaryBuilder,
+    };
+    use arrow::datatypes::{DataType, Field, Int8Type};
+    use datafusion_execution::config::SessionConfig;
+    use datafusion_execution::runtime_env::RuntimeEnvBuilder;
+    use datafusion_expr::ColumnarValue;
+    use datafusion_physical_expr_common::metrics::MetricValue;
+    use datafusion_physical_expr_common::physical_expr::PhysicalExpr;
+
+    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
+    struct VolatileExpr;
+
+    impl std::fmt::Display for VolatileExpr {
+        fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile")
+        }
+    }
+
+    impl PhysicalExpr for VolatileExpr {
+        fn data_type(&self, _input_schema: &Schema) -> Result<DataType> {
+            Ok(DataType::Int64)
+        }
+
+        fn nullable(&self, _input_schema: &Schema) -> Result<bool> {
+            Ok(false)
+        }
+
+        fn evaluate(&self, _batch: &RecordBatch) -> Result<ColumnarValue> {
+            Ok(ColumnarValue::Scalar(ScalarValue::Int64(Some(1))))
+        }
+
+        fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+            vec![]
+        }
+
+        fn with_new_children(
+            self: Arc<Self>,
+            _children: Vec<Arc<dyn PhysicalExpr>>,
+        ) -> Result<Arc<dyn PhysicalExpr>> {
+            Ok(self)
+        }
+
+        fn is_volatile_node(&self) -> bool {
+            true
+        }
+
+        fn fmt_sql(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+            write!(f, "volatile()")
+        }
+    }
+
+    fn make_batch(
+        schema: &SchemaRef,
+        keys: Vec<Option<&str>>,
+        times: Vec<Option<i64>>,
+        values: Vec<i32>,
+    ) -> Result<RecordBatch> {
+        RecordBatch::try_new(
+            Arc::clone(schema),
+            vec![
+                Arc::new(StringArray::from(keys)),
+                Arc::new(Int64Array::from(times)),
+                Arc::new(Int32Array::from(values)),
+            ],
+        )
+        .map_err(Into::into)
+    }
+
+    fn test_exec() -> Result<Arc<AsOfJoinExec>> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&left_schema)),
+            make_batch(&left_schema, vec![None], vec![Some(3)], vec![0])?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![None, Some(1)],
+                vec![1, 2],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("A"), Some("A")],
+                vec![Some(4), Some(7)],
+                vec![3, 4],
+            )?,
+            make_batch(
+                &left_schema,
+                vec![Some("B"), Some("C")],
+                vec![Some(2), Some(3)],
+                vec![5, 6],
+            )?,
+        ];
+        let left = TestMemoryExec::try_new_exec(
+            &[left_batches],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, true),
+            Field::new("ts", DataType::Int64, true),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right_batches = vec![
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![None, Some("A")],
+                vec![Some(2), None],
+                vec![999, 777],
+            )?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(2)], vec![20])?,
+            make_batch(&right_schema, vec![Some("A")], vec![Some(4)], vec![40])?,
+            RecordBatch::new_empty(Arc::clone(&right_schema)),
+            make_batch(
+                &right_schema,
+                vec![Some("A"), Some("B")],
+                vec![Some(6), Some(1)],
+                vec![60, 101],
+            )?,
+        ];
+        let right = TestMemoryExec::try_new_exec(
+            &[right_batches],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+
+        let on: JoinOn = vec![(
+            Arc::new(PhysicalColumn::new("key", 0)),
+            Arc::new(PhysicalColumn::new("key", 0)),
+        )];
+        Ok(Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            on,
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?))
+    }
+
+    #[test]
+    fn eligibility_matches_public_semantics() -> Result<()> {
+        let left = ScalarValue::Int64(Some(10));
+        let lower = ScalarValue::Int64(Some(9));
+        let equal = ScalarValue::Int64(Some(10));
+        let higher = ScalarValue::Int64(Some(11));
+        assert!(is_eligible(Operator::Gt, &left, &lower)?);
+        assert!(!is_eligible(Operator::Gt, &left, &equal)?);
+        assert!(is_eligible(Operator::GtEq, &left, &equal)?);
+        assert!(is_eligible(Operator::Lt, &left, &higher)?);
+        assert!(!is_eligible(Operator::Lt, &left, &equal)?);
+        assert!(is_eligible(Operator::LtEq, &left, &equal)?);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn state_survives_empty_input_batches_and_output_flushes() -> Result<()> {
+        let exec = test_exec()?;
+        let context = Arc::new(
+            TaskContext::default()
+                .with_session_config(SessionConfig::new().with_batch_size(2)),
+        );
+        let batches = collect(Arc::clone(&exec) as _, context).await?;
+        assert_eq!(
+            batches
+                .iter()
+                .map(RecordBatch::num_rows)
+                .collect::<Vec<_>>(),
+            vec![2, 2, 2, 1]
+        );
+        let ids = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(2)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        let prices = batches
+            .iter()
+            .flat_map(|batch| {
+                batch
+                    .column(3)
+                    .as_any()
+                    .downcast_ref::<Int32Array>()
+                    .unwrap()
+                    .iter()
+            })
+            .collect::<Vec<_>>();
+        assert_eq!(
+            ids,
+            vec![
+                Some(0),
+                Some(1),
+                Some(2),
+                Some(3),
+                Some(4),
+                Some(5),
+                Some(6),
+            ]
+        );
+        assert_eq!(
+            prices,
+            vec![None, None, None, Some(40), Some(60), Some(101), None]
+        );
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(metrics.output_rows(), Some(7));
+        assert_eq!(
+            metrics
+                .sum_by_name("matched_rows")
+                .map(|value| value.as_usize()),
+            Some(3)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("unmatched_left_rows")
+                .map(|value| value.as_usize()),
+            Some(4)
+        );
+        assert!(metrics.elapsed_compute().is_some());
+        assert!(
+            metrics.iter().any(|metric| {
+                matches!(metric.value(), MetricValue::ElapsedCompute(_))
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn broadcasts_right_input_to_all_left_partitions() -> Result<()> {
+        let left_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("id", DataType::Int32, false),
+        ]));
+        let left = TestMemoryExec::try_new_exec(
+            &[
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(1), Some(4)],
+                    vec![0, 1],
+                )?],
+                vec![make_batch(
+                    &left_schema,
+                    vec![Some("A"), Some("A")],
+                    vec![Some(2), Some(5)],
+                    vec![2, 3],
+                )?],
+            ],
+            Arc::clone(&left_schema),
+            None,
+        )?;
+        let right_schema = Arc::new(Schema::new(vec![
+            Field::new("key", DataType::Utf8, false),
+            Field::new("ts", DataType::Int64, false),
+            Field::new("price", DataType::Int32, false),
+        ]));
+        let right = TestMemoryExec::try_new_exec(
+            &[vec![
+                make_batch(&right_schema, vec![Some("A")], vec![Some(1)], vec![10])?,
+                make_batch(&right_schema, vec![Some("A")], vec![Some(3)], vec![30])?,
+            ]],
+            Arc::clone(&right_schema),
+            None,
+        )?;
+        let exec = Arc::new(AsOfJoinExec::try_new(
+            left,
+            right,
+            vec![],
+            AsOfMatchExpr::new(
+                Arc::new(PhysicalColumn::new("ts", 1)),
+                Operator::GtEq,
+                Arc::new(PhysicalColumn::new("ts", 1)),
+            ),
+            vec![2],
+        )?);
+        assert_eq!(exec.properties().output_partitioning().partition_count(), 2);
+        assert!(matches!(
+            &exec.input_distribution_requirements().into_per_child()[..],
+            [
+                Distribution::UnspecifiedDistribution,
+                Distribution::SinglePartition
+            ]
+        ));
+
+        let partitions = collect_partitioned(
+            Arc::clone(&exec) as Arc<dyn ExecutionPlan>,
+            Arc::new(TaskContext::default()),
+        )
+        .await?;
+        assert_eq!(partitions.len(), 2);
+        for batches in partitions {
+            let prices = batches
+                .iter()
+                .flat_map(|batch| {
+                    batch
+                        .column(3)
+                        .as_any()
+                        .downcast_ref::<Int32Array>()
+                        .unwrap()
+                        .iter()
+                })
+                .collect::<Vec<_>>();
+            assert_eq!(prices, vec![Some(10), Some(30)]);
+        }
+
+        let metrics = exec.metrics().expect("ASOF metrics must be present");
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_batches")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(
+            metrics
+                .sum_by_name("build_input_rows")
+                .map(|value| value.as_usize()),
+            Some(2)
+        );
+        assert_eq!(metrics.output_rows(), Some(4));
+        Ok(())
+    }
+
+    #[tokio::test]

Review Comment:
   Applied, thanks!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5295197156

   > I'm not so sure if there is an easy fix, it it's hard we could first reject floats in the planning, and fix that in a separate PR.
   
   Checked a bit, seems to be a mid level fix. Let's fix that in a seperate PR. We can get this in first! 💌 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5291909130

   Great! I got one tricky bug found by AI, otherwise it should be good to go.
   
   ----
   Found one blocking correctness issue.
   
   - **[P1] Keep float equality groups contiguous under the declared ordering.** [`[try_new](https://github.com/apache/datafusion/blob/70b81458e96c5c5a7e18636b5f13638c19f92715/datafusion/physical-plan/src/joins/asof_join.rs#L187-L208)`](https://github.com/apache/datafusion/blob/70b81458e96c5c5a7e18636b5f13638c19f92715/datafusion/physical-plan/src/joins/asof_join.rs#L187-L208) sorts raw equality keys, where Arrow orders `-0.0` and `+0.0` separately. However, [`[JoinKeyComparator](https://github.com/apache/datafusion/blob/70b81458e96c5c5a7e18636b5f13638c19f92715/datafusion/physical-plan/src/joins/utils.rs#L2380-L2389)`](https://github.com/apache/datafusion/blob/70b81458e96c5c5a7e18636b5f13638c19f92715/datafusion/physical-plan/src/joins/utils.rs#L2380-L2389) normalizes them as SQL-equal. This can break the required secondary match ordering. For example, right rows `(-0, ts=10), (+0, ts=1)` sort in that order; left `(+0, ts=5)` stops at `ts=10` and never reaches the eligible `ts=1`, prod
 ucing NULL incorrectly. Normalize equality keys consistently for both sorting and comparison, or initially reject float equality keys, and add this regression case.
   ----
   
   I'm not so sure if there is an easy fix, it it's hard we could first reject floats in the planning, and fix that in a separate PR.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5357328404

   Thank you @2010YOUY01 again for getting this PR merged! Do you want to review the whole stack? Can I ping you on the PR while I'm ready?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "jayzhan211 (via GitHub)" <gi...@apache.org>.
jayzhan211 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3791821850


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    /// Standard output-row and elapsed-compute metrics.
+    baseline: BaselineMetrics,
+    /// Peak bytes retained for the shared right input.
+    ///
+    /// `peak_memory_usage` records this as `MetricValue::PeakMemoryUsage`; `Gauge`
+    /// is the handle used to update that metric.
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,

Review Comment:
   Do we need `Vec<Arc<RecordBatch>>` and not just `Vec<RecordBatch>`



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {

Review Comment:
   It seems similar to `poll_next` method from Stream what we have for other join like HashJoinStream
   
   Could we have Stream for AsofJoinStream as well, or is there any reason that current implementation is better for AsofJoin?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "alamb (via GitHub)" <gi...@apache.org>.
alamb commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5333311301

   > > cc @jayzhan211, @xudong963, and @alamb, would you like to take another look and move forward?
   > 
   > datafusion project typically wait for 24 hrs after approval to merge, so others can have a chance to look. This one is a larger PR, probably we could wait for 2 days, unless anyone need more time to review.
   > 
   > https://datafusion.apache.org/contributor-guide/pr_review.html#pr-review-mechanics
   
   Given @2010YOUY01 and @jayzhan211  have reviewed and approved I am happy to have this merged without my review (I am currently focusing a bit lower with arrow/parquet and trying to keep them going along)
   
   I did however add this feature to the list of things to list in the next release when we get there
   - https://github.com/apache/datafusion/issues/24461
   
   Nice work


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5316916155

   Got it, thank you @2010YOUY01 for the explanation 🙌


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701253784


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an

Review Comment:
   Good idea. updated.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3689151608


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an

Review Comment:
   Perhaps we could just link the snowflake doc here to explain the semantics



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left

Review Comment:
   I think there is real usage for either left input is larger than right input, or the else way. So both broadcasting left and right will be needed eventually.
   
   But still, it's a good idea to only implement one in this PR, to keep it simple.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec

Review Comment:
   Could you add some notes to explain how this plan shape is formed?
   
   The high-level idea I think, is declaring it in the `ExecutionPlan` (with something like `reuiqire_input_ordering()` API, and some optimizer passes insert them automatically.
   
   But it would be great to explain more details, it seems quite complex since multiple child operator will be inserted.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,

Review Comment:
   Those two orderings are a bit difficult to reason about. Perhaps we could add a few examples showing the query and the resulting planned ordering?



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(

Review Comment:
   It looks like this function has two parts 1. validate if the query is valid 2. construction
   
   Perhaps we can extract step 1 to a separate utility function, and specify the conditions that must pass so we can construct a valid `AsofJoinExec`



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(

Review Comment:
   Just an idea to make this PR smaller, could we use the default implementation here? We could implement it later in a follow-up PR.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {

Review Comment:
   Could you add more comments to its fields, and also for other similar structs.
   
   One trick I used a lot is documenting example data for those fields, otherwise sometime they might get hard to understand.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {
+    schema: SchemaRef,
+    left: InputCursor,
+    right: InputCursor,
+    op: Operator,
+    right_output_indices: Vec<usize>,
+    candidate: Option<Candidate>,
+    group_sort_options: Vec<SortOptions>,
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    pending_left: PendingRows,
+    pending_right: PendingRows,
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {

Review Comment:
   Let’s add more comments to key functions like this one.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(

Review Comment:
   Similarly here, could we use the default implementations for filter pushdown? This might need more tests, so we can put them in a separate PR.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,

Review Comment:
   it would be great to add some comments for this field



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }

Review Comment:
   Do we need them to be `pub`? If they're necessary I think we could doc the reason, otherwise it's preferred to make the public interface smaller.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,

Review Comment:
   Why is it `unspecified` instead of `KeyPartitioned`?



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]

Review Comment:
   I recommend to make them both `false` at first to be more conservative.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {
+    schema: SchemaRef,
+    left: InputCursor,
+    right: InputCursor,
+    op: Operator,
+    right_output_indices: Vec<usize>,
+    candidate: Option<Candidate>,
+    group_sort_options: Vec<SortOptions>,
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    pending_left: PendingRows,
+    pending_right: PendingRows,
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance
+                } else {
+                    match self.compare_input_groups()? {
+                        Ordering::Less => RightAction::Advance,
+                        Ordering::Greater => RightAction::Stop,
+                        Ordering::Equal => {
+                            let _timer = self.metrics.baseline.elapsed_compute().timer();
+                            let right_match = self.right.match_value()?;
+                            if right_match.is_null() {
+                                RightAction::Advance
+                            } else if is_eligible(self.op, &left_match, &right_match)? {
+                                let (batch, row) = self.right.batch_row()?;
+                                RightAction::Candidate(Candidate {
+                                    batch,
+                                    row,
+                                    key_arrays: Arc::clone(&self.right.key_arrays),
+                                    key_batch_id: self.right.key_batch_id,
+                                })
+                            } else {
+                                RightAction::Stop
+                            }
+                        }
+                    }
+                };
+                match action {
+                    RightAction::Advance => self.right.advance(),
+                    RightAction::Candidate(candidate) => {
+                        // Replacing the candidate selects the nearest eligible row.
+                        // Equal match values have no secondary ordering, so which
+                        // tied row wins is intentionally nondeterministic.
+                        self.candidate = Some(candidate);
+                        self.right.advance();
+                    }
+                    RightAction::Stop => break,
+                }
+            }
+
+            self.push_current_left(self.candidate.clone())?;
+            self.left.advance();
+        }
+    }
+
+    fn push_current_left(&mut self, candidate: Option<Candidate>) -> Result<()> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let (left_batch, left_row) = self.left.batch_row()?;
+        self.pending_left.push(left_batch, left_row);
+        match candidate {
+            Some(candidate) => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push(candidate.batch, candidate.row);
+                }
+                self.metrics.matched_rows.add(1);
+            }
+            None => {
+                if !self.right_output_indices.is_empty() {
+                    self.pending_right.push_null();
+                }
+                self.metrics.unmatched_left_rows.add(1);
+            }
+        }
+        Ok(())
+    }
+
+    fn flush(&mut self) -> Result<RecordBatch> {
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let left_len = self.schema.fields().len() - self.right_output_indices.len();
+        let mut arrays = Vec::with_capacity(self.schema.fields().len());
+        for index in 0..left_len {
+            arrays.push(
+                self.pending_left
+                    .materialize_column(index, self.schema.field(index).data_type())?,
+            );
+        }
+        for (offset, source_index) in self.right_output_indices.iter().enumerate() {
+            arrays.push(self.pending_right.materialize_column(
+                *source_index,
+                self.schema.field(left_len + offset).data_type(),
+            )?);
+        }
+        self.pending_left.clear();
+        self.pending_right.clear();
+        let batch = RecordBatch::try_new(Arc::clone(&self.schema), arrays)?;
+        (&batch).record_output(&self.metrics.baseline);
+        Ok(batch)
+    }
+}
+
+fn validate_expr_side(expr: &PhysicalExprRef, schema: &Schema, name: &str) -> Result<()> {
+    let columns = collect_columns(expr);
+    if columns.is_empty() {
+        return plan_err!("AsOfJoinExec {name} expression must reference its input");
+    }
+    if let Some(column) = columns.iter().find(|column| {
+        schema
+            .fields()
+            .get(column.index())
+            .is_none_or(|field| field.name() != column.name())
+    }) {
+        return plan_err!(
+            "AsOfJoinExec {name} expression references column {column} outside its input"
+        );
+    }
+    Ok(())
+}
+
+enum RightAction {
+    Advance,
+    Candidate(Candidate),
+    Stop,
+}
+
+fn is_eligible(op: Operator, left: &ScalarValue, right: &ScalarValue) -> Result<bool> {
+    let ordering = right.try_cmp(left)?;
+    Ok(match op {
+        Operator::Gt => ordering == Ordering::Less,
+        Operator::GtEq => ordering != Ordering::Greater,
+        Operator::Lt => ordering == Ordering::Greater,
+        Operator::LtEq => ordering != Ordering::Less,
+        _ => unreachable!("ASOF match operator is validated by try_new"),
+    })
+}
+
+#[cfg(test)]
+mod tests {

Review Comment:
   I haven't read it yet, but I think we could only do basic tests here, and leave the major test coverage, edge cases to `sqllogictests` after we have SQL support in the follow-up PR, since sql tests are stronger and easier to maintain.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701254555


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec

Review Comment:
   Agreed! 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5213359060

   > There is no new commits after the previous review, you may have forgotten to push the local changes 🤔 @Xuanwo
   
   Oh, sorry


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3747807261


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,

Review Comment:
   Is it the case the optimizer will insert round-robin repartition, if we declare this `UnspecifiedDistribution`? It should be fine if it's doing so, I was a little bit confused by this name 🤔 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5313673117

   > cc @jayzhan211, @xudong963, and @alamb, would you like to take another look and move forward?
   
   datafusion project typically wait for 24 hrs after approval to merge, so others can have a chance to look. This one is a larger PR, probably we could wait for 2 days, unless anyone need more time to review.
   
   https://datafusion.apache.org/contributor-guide/pr_review.html#pr-review-mechanics


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3792156253


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    /// Standard output-row and elapsed-compute metrics.
+    baseline: BaselineMetrics,
+    /// Peak bytes retained for the shared right input.
+    ///
+    /// `peak_memory_usage` records this as `MetricValue::PeakMemoryUsage`; `Gauge`
+    /// is the handle used to update that metric.
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,

Review Comment:
   Yep, Arc is intentional here: it keeps per-row clones O(1) and gives PendingRows a stable identity for deduplication. Added a short comment.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701259937


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,

Review Comment:
   Added examples for both `>=` and `<=` joins



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "jayzhan211 (via GitHub)" <gi...@apache.org>.
jayzhan211 commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3791875703


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1769 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is `AsOfJoinStreamState::next_batch`.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    ReplaceChildrenOptions, SendableRecordBatchStream, validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn apply_expressions(
+        &self,
+        f: &mut dyn FnMut(&Arc<dyn crate::PhysicalExpr>) -> Result<TreeNodeRecursion>,
+    ) -> Result<TreeNodeRecursion> {
+        let join_keys = self.on.iter().flat_map(|(left, right)| [left, right]);
+        crate::apply_expression_roots(
+            join_keys.chain([&self.match_condition.left, &self.match_condition.right]),
+            f,
+        )
+    }
+
+    fn replace_children(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+        options: ReplaceChildrenOptions,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        validate_child_count!(self, children);
+        let left = children.swap_remove(0);
+        let right = children.swap_remove(0);
+        match options.children_properties {
+            ChildrenPropertiesMode::Keep => Ok(Arc::new(Self {
+                left,
+                right,
+                on: self.on.clone(),
+                match_condition: self.match_condition.clone(),
+                join_schema: Arc::clone(&self.join_schema),
+                column_indices: self.column_indices.clone(),
+                projection: self.projection.clone(),
+                metrics: ExecutionPlanMetricsSet::new(),
+                left_ordering: self.left_ordering.clone(),
+                right_ordering: self.right_ordering.clone(),
+                right_fut: Default::default(),
+                cache: Arc::clone(&self.cache),
+            })),
+            ChildrenPropertiesMode::Recompute => Ok(Arc::new(Self::try_new(
+                left,
+                right,
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.projection.as_deref().map(<[usize]>::to_vec),
+            )?)),
+        }
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Recompute),
+        )
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        self.replace_children(
+            children,
+            ReplaceChildrenOptions::new(ChildrenPropertiesMode::Keep),
+        )
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = self.schema();
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let column_indices = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                column_indices,
+                batch_size,
+                metrics,
+            );
+            // `next_batch` is the key state-machine entry point. `try_unfold`
+            // preserves that state between emitted batches.
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let column_indices_after_projection = match self.projection.as_ref() {
+            Some(projection) => projection
+                .iter()
+                .map(|index| self.column_indices[*index].clone())
+                .collect(),
+            None => self.column_indices.clone(),
+        };
+        let column_statistics = column_indices_after_projection
+            .iter()
+            .map(|column| match column.side {
+                JoinSide::Left => left
+                    .column_statistics
+                    .get(column.index)
+                    .cloned()
+                    .unwrap_or_else(ColumnStatistics::new_unknown),
+                JoinSide::Right | JoinSide::None => ColumnStatistics::new_unknown(),
+            })
+            .collect();
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+/// Last eligible right row for the current left equality group.
+///
+/// The row and its evaluated keys survive right batch changes and output
+/// flushes. It belongs to the join state rather than `InputCursor` because its
+/// validity also depends on the current left equality group.
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    /// Standard output-row and elapsed-compute metrics.
+    baseline: BaselineMetrics,
+    /// Peak bytes retained for the shared right input.
+    ///
+    /// `peak_memory_usage` records this as `MetricValue::PeakMemoryUsage`; `Gauge`
+    /// is the handle used to update that metric.
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Projected output columns and their input sides.
+    column_indices: Vec<ColumnIndex>,
+    /// Whether any projected column needs a right row reference.
+    projects_right: bool,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        column_indices: Vec<ColumnIndex>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            projects_right: column_indices
+                .iter()
+                .any(|column| column.side == JoinSide::Right),
+            column_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    ///
+    /// ```text
+    /// while the output batch is not full:
+    ///   load the current left row, or flush/finish at left EOF
+    ///   if its match or equality key is NULL, emit it unmatched and advance left
+    ///   clear the candidate if the left equality group changed
+    ///   while the current right row is before the left group or is eligible:
+    ///     remember the nearest eligible row and advance right
+    ///   emit the left row with the candidate (or NULLs), then advance left
+    /// flush pending rows without resetting either cursor or the candidate
+    /// ```
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {
+        loop {
+            if self.pending_left.len() >= self.batch_size {
+                return self.flush().map(Some);
+            }
+            if !self
+                .left
+                .ensure_row(self.metrics.baseline.elapsed_compute())
+                .await?
+            {
+                if !self.pending_left.is_empty() {
+                    return self.flush().map(Some);
+                }
+                self.metrics.baseline.done();
+                return Ok(None);
+            }
+
+            let left_match = {
+                let _timer = self.metrics.baseline.elapsed_compute().timer();
+                self.left.match_value()?
+            };
+            if left_match.is_null() || self.left.group_has_null() {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+                self.push_current_left(None)?;
+                self.left.advance();
+                continue;
+            }
+            if self.candidate_is_other_group()? {
+                self.candidate = None;
+                self.candidate_group_comparator = None;
+            }
+
+            loop {
+                if !self
+                    .right
+                    .ensure_row(self.metrics.baseline.elapsed_compute())
+                    .await?
+                {
+                    break;
+                }
+                let action = if self.right.group_has_null() {
+                    RightAction::Advance

Review Comment:
   My understanding is that we keep finding the last eligible row for specific left side row, so we probably only need `Option<T>` for candidate, keep updating new candidate with the eligible row 🤔 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3809587813


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1780 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//! The key state-machine entry point is [`AsOfJoinStream::poll_next_impl`].
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::pin::Pin;
+use std::sync::Arc;
+use std::task::{Context, Poll};
+
+use arrow::array::{Array, ArrayRef, RecordBatch, RecordBatchOptions, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::tree_node::TreeNodeRecursion;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinSide, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err, project_schema,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::{ProjectionMapping, ProjectionRef};
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{Stream, StreamExt, TryStreamExt, future::poll_fn, ready, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    ColumnIndex, JoinKeyComparator, JoinOn, OnceAsync, build_join_schema,
+    matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, ExecutionPlanMetricsSet, Gauge, MetricBuilder, MetricsSet,
+    RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    ChildrenPropertiesMode, DisplayAs, DisplayFormatType, Distribution, ExecutionPlan,
+    ExecutionPlanProperties, InputDistributionRequirements, PlanProperties,
+    RecordBatchStream, ReplaceChildrenOptions, SendableRecordBatchStream,
+    validate_child_count,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Unprojected left-join schema used to interpret `projection`.
+    join_schema: SchemaRef,
+    /// Information of index and left/right placement of columns.
+    column_indices: Vec<ColumnIndex>,
+    /// Optional indices into the full left-then-right join schema.
+    projection: Option<ProjectionRef>,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing;
+    /// floating-point equality keys are not supported because Arrow sorting
+    /// distinguishes signed zero while SQL equality does not. Projection indices
+    /// refer to the full left-then-right join schema.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        projection: Option<Vec<usize>>,
+    ) -> Result<Self> {
+        validate_asof_join(left.as_ref(), right.as_ref(), &on, &match_condition)?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let (join_schema, column_indices) =
+            build_join_schema(&left_schema, &right_schema, &JoinType::Left);
+        let join_schema = Arc::new(join_schema);
+        let projection: Option<ProjectionRef> = projection.map(Into::into);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(
+            &left,
+            &join_schema,
+            projection.as_deref(),
+        )?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            join_schema,
+            column_indices,
+            projection,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        join_schema: &SchemaRef,
+        projection: Option<&[usize]>,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let mut eq_properties =
+            input_eq_properties.project(&mapping, Arc::clone(join_schema));
+        let mut output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        if let Some(projection) = projection {
+            let projection_mapping =
+                ProjectionMapping::from_indices(projection, join_schema)?;
+            let output_schema = project_schema(join_schema, Some(&projection))?;
+            output_partitioning =
+                output_partitioning.project(&projection_mapping, &eq_properties);
+            eq_properties = eq_properties.project(&projection_mapping, output_schema);
+        }
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        let projection = self
+            .projection
+            .as_ref()
+            .map(|projection| {
+                format!(
+                    ", projection=[{}]",
+                    projection
+                        .iter()
+                        .map(|index| format!(
+                            "{}@{}",
+                            self.join_schema.field(*index).name(),
+                            index
+                        ))
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                )
+            })
+            .unwrap_or_default();
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]{}",
+                Self::static_name(),
+                on,
+                match_condition,
+                projection
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        // `UnspecifiedDistribution` imposes no layout requirement; because this
+        // operator uses the default `benefits_from_input_partitioning`, the
+        // optimizer may still add round-robin repartitioning when it is useful.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {

Review Comment:
   updated.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "2010YOUY01 (via GitHub)" <gi...@apache.org>.
2010YOUY01 merged PR #23828:
URL: https://github.com/apache/datafusion/pull/23828


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3701265236


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(

Review Comment:
   DONE



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+
+    fn gather_filters_for_pushdown(
+        &self,
+        _phase: FilterPushdownPhase,
+        parent_filters: Vec<PhysicalExprRef>,
+        _config: &ConfigOptions,
+    ) -> Result<FilterDescription> {
+        let left_indices = (0..self.left.schema().fields().len()).collect::<HashSet<_>>();
+        let left = ChildFilterDescription::from_child_with_allowed_indices(
+            &parent_filters,
+            left_indices,
+            &self.left,
+        )?;
+        let right = ChildFilterDescription::all_unsupported(&parent_filters);
+        Ok(FilterDescription::new().with_child(left).with_child(right))
+    }
+
+    fn handle_child_pushdown_result(
+        &self,
+        _phase: FilterPushdownPhase,
+        child_pushdown_result: ChildPushdownResult,
+        _config: &ConfigOptions,
+    ) -> Result<FilterPushdownPropagation<Arc<dyn ExecutionPlan>>> {
+        Ok(FilterPushdownPropagation::if_any(child_pushdown_result))
+    }
+}
+
+struct BroadcastRightInput {
+    schema: SchemaRef,
+    batches: Vec<RecordBatch>,
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    batch: Arc<RecordBatch>,
+    row: usize,
+    key_arrays: Arc<[ArrayRef]>,
+    key_batch_id: usize,
+}
+
+struct InputCursor {
+    stream: SendableRecordBatchStream,
+    key_exprs: Vec<PhysicalExprRef>,
+    match_expr: PhysicalExprRef,
+    batch: Option<Arc<RecordBatch>>,
+    key_arrays: Arc<[ArrayRef]>,
+    key_validity: Option<NullBuffer>,
+    match_array: Option<ArrayRef>,
+    key_batch_id: usize,
+    row: usize,
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+#[derive(Default)]
+struct PendingRows {
+    sources: Vec<Arc<RecordBatch>>,
+    source_by_ptr: HashMap<usize, usize>,
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+struct AsOfJoinStreamState {

Review Comment:
   Added!



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5251996694

   <!-- semver-check-comment -->
   Thank you for opening this pull request!
   
   Reviewer note: [cargo-semver-checks](https://github.com/obi1kenobi/cargo-semver-checks) reported the current version number is not SemVer-compatible with the changes in this pull request (compared against the base branch).
   
   <details>
   <summary>Details</summary>
   
   ```
        Cloning apache/main
       Building datafusion-physical-plan v54.1.0 (current)
   error: running cargo-doc on crate 'datafusion-physical-plan' failed with output:
   -----
      Compiling proc-macro2 v1.0.107
      Compiling unicode-ident v1.0.24
      Compiling quote v1.0.47
      Compiling libc v0.2.189
       Checking cfg-if v1.0.4
      Compiling autocfg v1.5.1
      Compiling libm v0.2.16
      Compiling num-traits v0.2.19
       Checking memchr v2.8.3
      Compiling syn v2.0.119
      Compiling getrandom v0.3.4
      Compiling zerocopy v0.8.56
      Compiling syn v3.0.3
       Checking bytes v1.12.1
       Checking rand_core v0.9.5
       Checking once_cell v1.21.4
       Checking foldhash v0.2.0
       Checking itoa v1.0.18
       Checking equivalent v1.0.2
      Compiling serde_core v1.0.229
       Checking allocator-api2 v0.2.21
      Compiling zmij v1.0.23
       Checking hashbrown v0.17.1
       Checking indexmap v2.14.0
      Compiling serde_json v1.0.151
       Checking num-integer v0.1.46
       Checking siphasher v1.0.3
       Checking iana-time-zone v0.1.65
      Compiling version_check v0.9.5
      Compiling ahash v0.8.12
       Checking chrono v0.4.45
       Checking phf_shared v0.12.1
       Checking num-bigint v0.5.1
      Compiling chrono-tz v0.10.4
       Checking phf v0.12.1
       Checking arrow-schema v59.2.0
       Checking num-complex v0.4.6
       Checking lexical-util v1.0.7
      Compiling zerocopy-derive v0.8.56
      Compiling shlex v2.0.1
      Compiling find-msvc-tools v0.1.10
      Compiling synstructure v0.13.2
      Compiling jobserver v0.1.35
      Compiling cc v1.4.2
      Compiling pkg-config v0.3.33
       Checking pin-project-lite v0.2.17
      Compiling zerofrom-derive v0.1.7
      Compiling zstd-sys v2.0.16+zstd.1.5.7
       Checking lexical-parse-integer v1.0.6
       Checking lexical-write-integer v1.0.6
      Compiling semver v1.0.28
      Compiling rustc_version v0.4.1
       Checking lexical-write-float v1.0.6
       Checking lexical-parse-float v1.0.6
       Checking zerofrom v0.1.8
      Compiling yoke-derive v0.8.2
       Checking aho-corasick v1.1.5
       Checking ppv-lite86 v0.2.21
       Checking stable_deref_trait v1.2.1
       Checking ryu v1.0.23
      Compiling zstd-safe v7.2.4
       Checking unicode-segmentation v1.13.3
       Checking rand_chacha v0.9.0
       Checking bitflags v2.13.1
       Checking unicode-width v0.2.2
       Checking rand v0.9.5
       Checking regex-syntax v0.8.11
       Checking comfy-table v7.2.2
       Checking yoke v0.8.3
       Checking lexical-core v1.0.6
       Checking rand_distr v0.5.1
      Compiling flatbuffers v25.12.19
      Compiling tokio-macros v2.7.2
       Checking half v2.7.1
       Checking arrow-buffer v59.2.0
       Checking atoi v2.0.0
       Checking base64 v0.23.1
       Checking smallvec v1.15.2
       Checking regex-automata v0.4.18
      Compiling getrandom v0.4.3
       Checking arrow-data v59.2.0
       Checking tokio v1.53.1
       Checking arrow-array v59.2.0
       Checking regex v1.13.1
      Compiling zerovec-derive v0.11.3
       Checking arrow-select v59.2.0
       Checking csv-core v0.1.13
       Checking either v1.17.0
       Checking twox-hash v2.1.3
       Checking lz4_flex v0.14.0
       Checking csv v1.4.0
       Checking zerovec v0.11.6
       Checking arrow-ord v59.2.0
      Compiling displaydoc v0.2.7
      Compiling anyhow v1.0.104
       Checking arrow-cast v59.2.0
       Checking simdutf8 v0.1.5
       Checking arrow-string v59.2.0
       Checking arrow-arith v59.2.0
       Checking arrow-row v59.2.0
       Checking arrow-csv v59.2.0
       Checking arrow-json v59.2.0
      Compiling parking_lot_core v0.9.12
       Checking log v0.4.33
      Compiling itertools v0.14.0
       Checking uuid v1.24.0
       Checking itertools v0.15.0
       Checking scopeguard v1.2.0
       Checking lock_api v0.4.14
       Checking tinystr v0.8.3
       Checking litemap v0.8.2
       Checking writeable v0.6.3
       Checking icu_locale_core v2.2.0
      Compiling prost-derive v0.14.4
       Checking zerotrie v0.2.4
       Checking potential_utf v0.1.5
       Checking futures-sink v0.3.33
      Compiling icu_properties_data v2.2.0
       Checking utf8_iter v1.0.4
      Compiling icu_normalizer_data v2.2.0
       Checking futures-core v0.3.33
       Checking icu_collections v2.2.0
       Checking icu_provider v2.2.0
       Checking parking_lot v0.12.5
      Compiling pin-project-internal v1.1.13
       Checking futures-channel v0.3.33
      Compiling futures-macro v0.3.33
       Checking prost v0.14.4
       Checking pin-project v1.1.13
       Checking futures-io v0.3.33
       Checking futures-task v0.3.33
       Checking slab v0.4.12
       Checking icu_normalizer v2.2.0
       Checking icu_properties v2.2.0
       Checking futures-util v0.3.33
      Compiling async-trait v0.1.92
       Checking idna_adapter v1.2.2
      Compiling thiserror v2.0.20
      Compiling rustix v1.1.4
       Checking percent-encoding v2.3.2
      Compiling crossbeam-utils v0.8.22
       Checking form_urlencoded v1.2.2
       Checking idna v1.1.0
      Compiling tracing-attributes v0.1.31
      Compiling thiserror-impl v2.0.20
       Checking futures-executor v0.3.33
       Checking tracing-core v0.1.36
       Checking linux-raw-sys v0.12.1
       Checking datafusion-doc v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/doc)
       Checking same-file v1.0.6
       Checking walkdir v2.5.0
       Checking tracing v0.1.44
       Checking futures v0.3.33
       Checking url v2.5.8
       Checking http v1.5.0
       Checking zstd v0.13.3
       Checking arrow-ipc v59.2.0
       Checking hashbrown v0.14.5
       Checking foldhash v0.1.5
       Checking humantime v2.4.0
       Checking fastrand v2.5.0
       Checking dashmap v6.2.1
       Checking object_store v0.13.2
       Checking tempfile v3.27.0
       Checking hashbrown v0.15.5
       Checking tokio-util v0.7.19
       Checking arrow v59.2.0
       Checking fixedbitset v0.5.7
       Checking datafusion-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/common)
       Checking petgraph v0.8.3
      Compiling datafusion-macros v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/macros)
       Checking hex v0.4.3
       Checking datafusion-common-runtime v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/common-runtime)
       Checking datafusion-proto-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/proto-common)
       Checking datafusion-expr-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/expr-common)
       Checking datafusion-proto-models v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/proto-models)
       Checking datafusion-physical-expr-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/physical-expr-common)
       Checking datafusion-functions-window-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/functions-window-common)
       Checking datafusion-functions-aggregate-common v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/functions-aggregate-common)
       Checking datafusion-expr v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/expr)
       Checking datafusion-execution v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/execution)
       Checking datafusion-physical-expr v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/physical-expr)
       Checking datafusion-functions v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/functions)
    Documenting datafusion-physical-plan v54.1.0 (/home/runner/work/datafusion/datafusion/datafusion/physical-plan)
   error[E0046]: not all trait items implemented, missing: `apply_expressions`
      --> /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/joins/asof_join.rs:323:1
       |
   323 |   impl ExecutionPlan for AsOfJoinExec {
       |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `apply_expressions` in implementation
       |
      ::: /home/runner/work/datafusion/datafusion/datafusion/physical-plan/src/execution_plan.rs:329:5
       |
   329 | /     fn apply_expressions(
   330 | |         &self,
   331 | |         f: &mut dyn FnMut(&Arc<dyn PhysicalExpr>) -> Result<TreeNodeRecursion>,
   332 | |     ) -> Result<TreeNodeRecursion>;
       | |___________________________________- `apply_expressions` from trait
   
   For more information about this error, try `rustc --explain E0046`.
   error: could not document `datafusion-physical-plan`
   
   -----
   
   error: failed to build rustdoc for crate datafusion-physical-plan v54.1.0
   note: this is usually due to a compilation error in the crate,
         and is unlikely to be a bug in cargo-semver-checks
   note: the following command can be used to reproduce the error:
         cargo new --lib example &&
             cd example &&
             echo '[workspace]' >> Cargo.toml &&
             cargo add --path /home/runner/work/datafusion/datafusion/datafusion/physical-plan --features force_hash_collisions,proto,test_utils,tokio_coop,tokio_coop_fallback &&
             cargo check &&
             cargo doc
   
   error: aborting due to failure to build rustdoc for crate datafusion-physical-plan v54.1.0
   ```
   
   </details>


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on code in PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#discussion_r3757465670


##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,

Review Comment:
   Yes. `UnspecifiedDistribution` only means ASOF does not require a particular left-side layout. With the default `benefits_from_input_partitioning`, `EnforceDistribution` can still add round-robin repartitioning when it would increase useful parallelism. I clarified this inline.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1782 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input:
+//!
+//! ```text
+//! AsOfJoinExec
+//!   SortExec(left equality keys, left match key)
+//!     RepartitionExec(RoundRobinBatch)
+//!       left
+//!   SortExec(right equality keys, right match key)
+//!     CoalescePartitionsExec
+//!       right
+//! ```
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. Each left partition owns its cursors,
+//! equality-group state, and current candidate, while the collected right
+//! batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition, so a
+//! repartitioned streaming mode remains a useful future alternative for large
+//! right inputs.
+
+use std::cmp::Ordering;
+use std::collections::{HashMap, HashSet};
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::config::ConfigOptions;
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::filter_pushdown::{
+    ChildFilterDescription, ChildPushdownResult, FilterDescription, FilterPushdownPhase,
+    FilterPushdownPropagation,
+};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    left_ordering: LexOrdering,
+    right_ordering: LexOrdering,
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        if !matches!(
+            match_condition.op,
+            Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq
+        ) {
+            return plan_err!(
+                "AsOfJoinExec requires <, <=, >, or >=, found {}",
+                match_condition.op
+            );
+        }
+        if left.boundedness().is_unbounded() || right.boundedness().is_unbounded() {
+            return plan_err!("AsOfJoinExec requires bounded inputs");
+        }
+        if is_volatile(&match_condition.left) || is_volatile(&match_condition.right) {
+            return plan_err!("AsOfJoinExec match expression must be deterministic");
+        }
+        if on
+            .iter()
+            .any(|(left, right)| is_volatile(left) || is_volatile(right))
+        {
+            return plan_err!("AsOfJoinExec equality expressions must be deterministic");
+        }
+
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        validate_expr_side(&match_condition.left, &left_schema, "left match")?;
+        validate_expr_side(&match_condition.right, &right_schema, "right match")?;
+        for (left_expr, right_expr) in &on {
+            validate_expr_side(left_expr, &left_schema, "left equality")?;
+            validate_expr_side(right_expr, &right_schema, "right equality")?;
+            let left_type = left_expr.data_type(&left_schema)?;
+            let right_type = right_expr.data_type(&right_schema)?;
+            if left_type != right_type {
+                return plan_err!(
+                    "AsOfJoinExec equality expression types differ: {left_type} and {right_type}"
+                );
+            }
+            if !datafusion_expr::utils::can_hash(&left_type) {
+                return plan_err!(
+                    "AsOfJoinExec equality expressions have unsupported hash type {left_type}"
+                );
+            }
+        }
+        let left_match_type = match_condition.left.data_type(&left_schema)?;
+        let right_match_type = match_condition.right.data_type(&right_schema)?;
+        if left_match_type != right_match_type {
+            return plan_err!(
+                "AsOfJoinExec match expression types differ: {left_match_type} and {right_match_type}"
+            );
+        }
+        if let Some(index) = right_output_indices
+            .iter()
+            .find(|index| **index >= right_schema.fields().len())
+        {
+            return plan_err!(
+                "AsOfJoinExec right output index {index} is outside schema with {} fields",
+                right_schema.fields().len()
+            );
+        }
+        if !right_output_indices
+            .windows(2)
+            .all(|pair| pair[0] < pair[1])
+        {
+            return plan_err!(
+                "AsOfJoinExec right output indices must be strictly increasing"
+            );
+        }
+
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+
+    /// Equality expressions.
+    pub fn on(&self) -> &JoinOn {
+        &self.on
+    }
+
+    /// Ordered match expression.
+    pub fn match_condition(&self) -> &AsOfMatchExpr {
+        &self.match_condition
+    }
+
+    /// Indices of right input columns emitted after the left columns.
+    pub fn right_output_indices(&self) -> &[usize] {
+        &self.right_output_indices
+    }
+
+    /// Left input.
+    pub fn left(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.left
+    }
+
+    /// Right input.
+    pub fn right(&self) -> &Arc<dyn ExecutionPlan> {
+        &self.right
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![true, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(

Review Comment:
   Thanks! I also updated it to preserve the same contract through the general projection.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {
+    /// Right batch containing the nearest eligible row.
+    batch: Arc<RecordBatch>,
+    /// Row index within `batch`.
+    row: usize,
+    /// Evaluated equality keys retained when the right cursor changes batches.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Identity used to invalidate the cached candidate/left comparator.
+    key_batch_id: usize,
+}
+
+/// Cursor over one ordered input stream.
+///
+/// Expressions are evaluated once per non-empty batch. `key_batch_id` changes
+/// whenever a new batch is loaded so comparators cannot retain stale arrays.
+struct InputCursor {
+    /// Remaining input batches.
+    stream: SendableRecordBatchStream,
+    /// Equality expressions evaluated for each batch.
+    key_exprs: Vec<PhysicalExprRef>,
+    /// Ordered match expression evaluated for each batch.
+    match_expr: PhysicalExprRef,
+    /// Current non-empty batch.
+    batch: Option<Arc<RecordBatch>>,
+    /// Evaluated equality-key arrays for `batch`.
+    key_arrays: Arc<[ArrayRef]>,
+    /// Rows whose equality keys are all non-NULL.
+    key_validity: Option<NullBuffer>,
+    /// Evaluated match values for `batch`.
+    match_array: Option<ArrayRef>,
+    /// Monotonic identity of the current key arrays.
+    key_batch_id: usize,
+    /// Current row within `batch`.
+    row: usize,
+    /// Whether the input stream has returned EOF.
+    eof: bool,
+}
+
+impl InputCursor {
+    fn new(
+        stream: SendableRecordBatchStream,
+        key_exprs: Vec<PhysicalExprRef>,
+        match_expr: PhysicalExprRef,
+    ) -> Self {
+        Self {
+            stream,
+            key_exprs,
+            match_expr,
+            batch: None,
+            key_arrays: Arc::from([]),
+            key_validity: None,
+            match_array: None,
+            key_batch_id: 0,
+            row: 0,
+            eof: false,
+        }
+    }
+
+    async fn ensure_row(&mut self, elapsed_compute: &Time) -> Result<bool> {
+        loop {
+            if let Some(batch) = &self.batch
+                && self.row < batch.num_rows()
+            {
+                return Ok(true);
+            }
+            self.batch = None;
+            self.key_arrays = Arc::from([]);
+            self.key_validity = None;
+            self.match_array = None;
+            self.row = 0;
+            if self.eof {
+                return Ok(false);
+            }
+            let Some(batch) = self.stream.next().await.transpose()? else {
+                self.eof = true;
+                return Ok(false);
+            };
+            if batch.num_rows() == 0 {
+                continue;
+            }
+            let batch = Arc::new(batch);
+            let _timer = elapsed_compute.timer();
+            let key_arrays = self
+                .key_exprs
+                .iter()
+                .map(|expr| expr.evaluate(&batch)?.into_array(batch.num_rows()))
+                .collect::<Result<Vec<_>>>()?;
+            self.key_validity =
+                matchable_join_keys(&key_arrays, NullEquality::NullEqualsNothing);
+            self.key_arrays = key_arrays.into();
+            self.match_array = Some(
+                self.match_expr
+                    .evaluate(&batch)?
+                    .into_array(batch.num_rows())?,
+            );
+            self.key_batch_id += 1;
+            self.batch = Some(batch);
+        }
+    }
+
+    fn group_has_null(&self) -> bool {
+        self.key_validity
+            .as_ref()
+            .is_some_and(|validity| validity.is_null(self.row))
+    }
+
+    fn match_value(&self) -> Result<ScalarValue> {
+        let array = self.match_array.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF match array is missing")
+        })?;
+        ScalarValue::try_from_array(array, self.row).map(normalize_float_zero_scalar)
+    }
+
+    fn batch_row(&self) -> Result<(Arc<RecordBatch>, usize)> {
+        let batch = self.batch.as_ref().ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!("ASOF input batch is missing")
+        })?;
+        Ok((Arc::clone(batch), self.row))
+    }
+
+    fn advance(&mut self) {
+        self.row += 1;
+    }
+}
+
+#[derive(Clone)]
+struct AsOfJoinMetrics {
+    baseline: BaselineMetrics,
+    matched_rows: Count,
+    unmatched_left_rows: Count,
+    build_input_batches: Count,
+    build_input_rows: Count,
+    build_mem_used: Gauge,
+}
+
+impl AsOfJoinMetrics {
+    fn new(partition: usize, metrics: &ExecutionPlanMetricsSet) -> Self {
+        Self {
+            baseline: BaselineMetrics::new(metrics, partition),
+            matched_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("matched_rows", partition),
+            unmatched_left_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("unmatched_left_rows", partition),
+            build_input_batches: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_batches", partition),
+            build_input_rows: MetricBuilder::new(metrics)
+                .with_category(MetricCategory::Rows)
+                .counter("build_input_rows", partition),
+            build_mem_used: MetricBuilder::new(metrics)
+                .peak_memory_usage("build_mem_used", partition),
+        }
+    }
+}
+
+/// Row references accumulated for the next output batch.
+///
+/// For right output, `None` represents NULL padding for an unmatched left row.
+/// For example, indices `[Some((0, 2)), None, Some((1, 0))]` select row 2 from
+/// the first source batch, a NULL, and row 0 from the second source batch.
+#[derive(Default)]
+struct PendingRows {
+    /// Distinct source batches referenced by `indices`.
+    sources: Vec<Arc<RecordBatch>>,
+    /// Maps an `Arc<RecordBatch>` pointer to its index in `sources`.
+    source_by_ptr: HashMap<usize, usize>,
+    /// Per-output-row `(source, row)` references or NULL padding.
+    indices: Vec<Option<(usize, usize)>>,
+}
+
+impl PendingRows {
+    fn len(&self) -> usize {
+        self.indices.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.indices.is_empty()
+    }
+
+    fn push(&mut self, batch: Arc<RecordBatch>, row: usize) {
+        let ptr = Arc::as_ptr(&batch) as usize;
+        let source = *self.source_by_ptr.entry(ptr).or_insert_with(|| {
+            let source = self.sources.len();
+            self.sources.push(batch);
+            source
+        });
+        self.indices.push(Some((source, row)));
+    }
+
+    fn push_null(&mut self) {
+        self.indices.push(None);
+    }
+
+    fn materialize_column(
+        &self,
+        source_column: usize,
+        data_type: &arrow::datatypes::DataType,
+    ) -> Result<ArrayRef> {
+        if self.indices.is_empty() {
+            return internal_err!("ASOF output materialization has no pending rows");
+        }
+
+        if self.sources.len() == 1
+            && self.indices.iter().all(Option::is_some)
+            && let Some((0, first_row)) = self.indices[0]
+            && self
+                .indices
+                .iter()
+                .enumerate()
+                .all(|(offset, index)| *index == Some((0, first_row + offset)))
+        {
+            return Ok(self.sources[0]
+                .column(source_column)
+                .slice(first_row, self.indices.len()));
+        }
+
+        let has_null = self.indices.iter().any(Option::is_none);
+        let null_array = has_null.then(|| new_null_array(data_type, 1));
+        let mut source_arrays: Vec<&dyn Array> =
+            Vec::with_capacity(self.sources.len() + usize::from(has_null));
+        if let Some(null_array) = &null_array {
+            source_arrays.push(null_array.as_ref());
+        }
+        source_arrays.extend(
+            self.sources
+                .iter()
+                .map(|batch| batch.column(source_column).as_ref()),
+        );
+        let source_offset = usize::from(has_null);
+        let interleave_indices = self
+            .indices
+            .iter()
+            .map(|index| match index {
+                Some((source, row)) => (source + source_offset, *row),
+                None => (0, 0),
+            })
+            .collect::<Vec<_>>();
+        interleave(&source_arrays, &interleave_indices).map_err(Into::into)
+    }
+
+    fn clear(&mut self) {
+        self.sources.clear();
+        self.source_by_ptr.clear();
+        self.indices.clear();
+    }
+}
+
+/// Per-left-partition state for the monotonic ASOF scan.
+///
+/// For left rows `(A, 4), (A, 7)` and right rows `(A, 2), (A, 6)`, the
+/// candidate advances from `(A, 2)` to `(A, 6)` without rewinding the right
+/// cursor. Cursors and the candidate survive input batch changes and output
+/// flushes; a change of equality group clears the candidate before reuse.
+struct AsOfJoinStreamState {
+    /// Output schema used when pending row references are materialized.
+    schema: SchemaRef,
+    /// Cursor over the current left partition.
+    left: InputCursor,
+    /// Independent cursor over the shared, ordered right input.
+    right: InputCursor,
+    /// Validated ordered match operator.
+    op: Operator,
+    /// Right columns appended to each output row.
+    right_output_indices: Vec<usize>,
+    /// Nearest eligible right row for the current equality group.
+    candidate: Option<Candidate>,
+    /// Equality-key ordering shared by the comparator caches.
+    group_sort_options: Vec<SortOptions>,
+    /// Cached comparator for the current right and left input batches.
+    input_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Cached comparator for the candidate and current left batches.
+    candidate_group_comparator: Option<(usize, usize, JoinKeyComparator)>,
+    /// Left row references accumulated for the next output batch.
+    pending_left: PendingRows,
+    /// Matched right row references, aligned with `pending_left`.
+    pending_right: PendingRows,
+    /// Maximum number of pending rows before an output flush.
+    batch_size: usize,
+    metrics: AsOfJoinMetrics,
+}
+
+impl AsOfJoinStreamState {
+    fn new(
+        schema: SchemaRef,
+        left: InputCursor,
+        right: InputCursor,
+        op: Operator,
+        right_output_indices: Vec<usize>,
+        batch_size: usize,
+        metrics: AsOfJoinMetrics,
+    ) -> Self {
+        let group_sort_options = vec![
+            SortOptions {
+                descending: false,
+                nulls_first: true,
+            };
+            left.key_exprs.len()
+        ];
+        Self {
+            pending_left: PendingRows::default(),
+            pending_right: PendingRows::default(),
+            schema,
+            left,
+            right,
+            op,
+            right_output_indices,
+            candidate: None,
+            group_sort_options,
+            input_group_comparator: None,
+            candidate_group_comparator: None,
+            batch_size: batch_size.max(1),
+            metrics,
+        }
+    }
+
+    fn compare_input_groups(&mut self) -> Result<Ordering> {
+        if self.group_sort_options.is_empty() {
+            return Ok(Ordering::Equal);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let right_batch_id = self.right.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .input_group_comparator
+            .as_ref()
+            .is_none_or(|(right, left, _)| {
+                *right != right_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                self.right.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.input_group_comparator =
+                Some((right_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .input_group_comparator
+            .as_ref()
+            .expect("ASOF input group comparator must be initialized");
+        Ok(comparator.compare(self.right.row, self.left.row))
+    }
+
+    fn candidate_is_other_group(&mut self) -> Result<bool> {
+        let Some(candidate) = &self.candidate else {
+            return Ok(false);
+        };
+        if self.group_sort_options.is_empty() {
+            return Ok(false);
+        }
+        let _timer = self.metrics.baseline.elapsed_compute().timer();
+        let candidate_batch_id = candidate.key_batch_id;
+        let left_batch_id = self.left.key_batch_id;
+        if self
+            .candidate_group_comparator
+            .as_ref()
+            .is_none_or(|(candidate, left, _)| {
+                *candidate != candidate_batch_id || *left != left_batch_id
+            })
+        {
+            let comparator = JoinKeyComparator::new(
+                candidate.key_arrays.as_ref(),
+                self.left.key_arrays.as_ref(),
+                &self.group_sort_options,
+                NullEquality::NullEqualsNothing,
+            )?;
+            self.candidate_group_comparator =
+                Some((candidate_batch_id, left_batch_id, comparator));
+        }
+        let (_, _, comparator) = self
+            .candidate_group_comparator
+            .as_ref()
+            .expect("ASOF candidate group comparator must be initialized");
+        Ok(comparator.compare(candidate.row, self.left.row) != Ordering::Equal)
+    }
+
+    /// Produces the next output batch without resetting the merge state.
+    ///
+    /// Each left row first validates its equality group, then advances the right
+    /// cursor while right groups sort before it or right match values remain
+    /// eligible. The last eligible right row becomes the candidate. Empty input
+    /// batches are skipped. Right EOF preserves that candidate for later left
+    /// rows in the same group; left EOF flushes the final pending rows. NULL keys
+    /// and group changes clear the candidate, while output flushes only clear
+    /// pending row references.
+    async fn next_batch(&mut self) -> Result<Option<RecordBatch>> {

Review Comment:
   Added. The module docs and `execute()` now point to `next_batch()`, and the function documents the main loop, EOF behavior, candidate lifetime, and output flush semantics.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,

Review Comment:
   Agreed. I replaced the right-only indices with the same full join-schema `column_indices` plus optional `projection` convention used by `NestedLoopJoinExec`, including left/right selection and reordering.



##########
datafusion/physical-plan/src/joins/asof_join.rs:
##########
@@ -0,0 +1,1835 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Broadcast, left-preserving ASOF join execution.
+//!
+//! An ASOF join emits exactly one output row for every left row. Within an
+//! optional equality-key group, it selects the closest right row that satisfies
+//! one ordered comparison. This follows Snowflake's [ASOF JOIN] semantics:
+//!
+//! ```text
+//! left.ts >= right.ts  => greatest eligible right.ts
+//! left.ts <= right.ts  => smallest eligible right.ts
+//! ```
+//!
+//! The right input is collected and shared by all output partitions. The left
+//! input remains partitioned, and each partition performs an independent
+//! monotonic scan over the ordered right input.
+//!
+//! [`AsOfJoinExec::input_distribution_requirements`] requires a single right
+//! partition but leaves the left distribution unrestricted.
+//! [`AsOfJoinExec::required_input_ordering`] requires both inputs to be ordered.
+//! The physical optimizer satisfies these contracts by inserting operators such
+//! as `RepartitionExec`, `SortExec`, `CoalescePartitionsExec`, or
+//! `SortPreservingMergeExec`, depending on the input properties. The inserted
+//! plan shape is therefore not fixed by this operator.
+//!
+//! Both inputs must be ordered by their equality keys followed by the match
+//! key. For `<` and `<=`, the match ordering is reversed so all directions use
+//! the same forward-only state machine. For example:
+//!
+//! ```text
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts >= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts ASC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts ASC NULLS FIRST]
+//!
+//! ON left.symbol = right.symbol MATCH_CONDITION(left.ts <= right.ts)
+//!   left:  [left.symbol ASC NULLS FIRST, left.ts DESC NULLS FIRST]
+//!   right: [right.symbol ASC NULLS FIRST, right.ts DESC NULLS FIRST]
+//! ```
+//!
+//! Each left partition owns its cursors, equality-group state, and current
+//! candidate, while the collected right batches are immutable and shared.
+//!
+//! This mode preserves probe-side parallelism when there are no equality keys
+//! or when equality keys have low cardinality or skew. It retains the complete
+//! right input in the memory pool and may scan it once per left partition.
+//! Alternative strategies, including broadcasting the other side or
+//! repartitioning both inputs, remain future work for other input-size and
+//! key-distribution profiles.
+//!
+//! [ASOF JOIN]: https://docs.snowflake.com/en/sql-reference/constructs/asof-join
+
+use std::cmp::Ordering;
+use std::collections::HashMap;
+use std::fmt::Formatter;
+use std::sync::Arc;
+
+use arrow::array::{Array, ArrayRef, RecordBatch, new_null_array};
+use arrow::buffer::NullBuffer;
+use arrow::compute::{SortOptions, interleave};
+use arrow::datatypes::{Schema, SchemaRef};
+use datafusion_common::stats::Precision;
+use datafusion_common::utils::memory::RecordBatchMemoryCounter;
+use datafusion_common::utils::normalize_float_zero_scalar;
+use datafusion_common::{
+    ColumnStatistics, JoinType, NullEquality, Result, ScalarValue, Statistics,
+    assert_eq_or_internal_err, internal_err, plan_err,
+};
+use datafusion_execution::TaskContext;
+use datafusion_execution::memory_pool::{MemoryConsumer, MemoryReservation};
+use datafusion_expr::Operator;
+use datafusion_physical_expr::PhysicalSortExpr;
+use datafusion_physical_expr::expressions::Column as PhysicalColumn;
+use datafusion_physical_expr::projection::ProjectionMapping;
+use datafusion_physical_expr::utils::collect_columns;
+use datafusion_physical_expr_common::physical_expr::{
+    PhysicalExprRef, fmt_sql, is_volatile,
+};
+use datafusion_physical_expr_common::sort_expr::{LexOrdering, OrderingRequirements};
+use futures::{StreamExt, TryStreamExt, future::poll_fn, stream};
+
+use crate::execution_plan::{Boundedness, EmissionType};
+use crate::joins::utils::{
+    JoinKeyComparator, JoinOn, OnceAsync, build_join_schema, matchable_join_keys,
+};
+use crate::memory::MemoryStream;
+use crate::metrics::{
+    BaselineMetrics, Count, ExecutionPlanMetricsSet, Gauge, MetricBuilder,
+    MetricCategory, MetricsSet, RecordOutput, Time,
+};
+use crate::statistics::{ChildStats, StatisticsArgs};
+use crate::stream::RecordBatchStreamAdapter;
+use crate::{
+    DisplayAs, DisplayFormatType, Distribution, ExecutionPlan, ExecutionPlanProperties,
+    InputDistributionRequirements, PlanProperties, SendableRecordBatchStream,
+    check_if_same_properties,
+};
+
+/// Physical ordered comparison for an ASOF join.
+#[derive(Debug, Clone)]
+pub struct AsOfMatchExpr {
+    /// Expression evaluated against the left input.
+    pub left: PhysicalExprRef,
+    /// Ordered comparison operator.
+    pub op: Operator,
+    /// Expression evaluated against the right input.
+    pub right: PhysicalExprRef,
+}
+
+impl AsOfMatchExpr {
+    /// Creates a physical ASOF match expression.
+    pub fn new(left: PhysicalExprRef, op: Operator, right: PhysicalExprRef) -> Self {
+        Self { left, op, right }
+    }
+}
+
+/// A broadcast sort-merge ASOF join that emits one row for every left row.
+#[derive(Debug)]
+pub struct AsOfJoinExec {
+    left: Arc<dyn ExecutionPlan>,
+    right: Arc<dyn ExecutionPlan>,
+    on: JoinOn,
+    match_condition: AsOfMatchExpr,
+    /// Sorted, unique indices of right columns appended after all left columns.
+    right_output_indices: Vec<usize>,
+    schema: SchemaRef,
+    metrics: ExecutionPlanMetricsSet,
+    /// Required ordering for each left partition.
+    left_ordering: LexOrdering,
+    /// Required global ordering for the single right partition.
+    right_ordering: LexOrdering,
+    /// Shared collection future that materializes the right input only once.
+    right_fut: OnceAsync<BroadcastRightInput>,
+    cache: Arc<PlanProperties>,
+}
+
+impl AsOfJoinExec {
+    /// Creates a bounded ASOF join over sorted inputs.
+    ///
+    /// The match operator must be `<`, `<=`, `>`, or `>=`. Equality and match
+    /// expressions must be deterministic, reference only their corresponding
+    /// input, and have matching input types. Equality types must support hashing.
+    /// Right output indices must be in bounds, sorted, and unique.
+    pub fn try_new(
+        left: Arc<dyn ExecutionPlan>,
+        right: Arc<dyn ExecutionPlan>,
+        on: JoinOn,
+        match_condition: AsOfMatchExpr,
+        right_output_indices: Vec<usize>,
+    ) -> Result<Self> {
+        validate_asof_join(
+            left.as_ref(),
+            right.as_ref(),
+            &on,
+            &match_condition,
+            &right_output_indices,
+        )?;
+        let left_schema = left.schema();
+        let right_schema = right.schema();
+        let schema =
+            build_output_schema(&left_schema, &right_schema, &right_output_indices);
+        let descending = matches!(match_condition.op, Operator::Lt | Operator::LtEq);
+        let equality_options = SortOptions {
+            descending: false,
+            nulls_first: true,
+        };
+        let match_options = SortOptions {
+            descending,
+            nulls_first: true,
+        };
+        let mut left_sort_exprs = on
+            .iter()
+            .map(|(left, _)| PhysicalSortExpr {
+                expr: Arc::clone(left),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        left_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.left),
+            options: match_options,
+        });
+        let mut right_sort_exprs = on
+            .iter()
+            .map(|(_, right)| PhysicalSortExpr {
+                expr: Arc::clone(right),
+                options: equality_options,
+            })
+            .collect::<Vec<_>>();
+        right_sort_exprs.push(PhysicalSortExpr {
+            expr: Arc::clone(&match_condition.right),
+            options: match_options,
+        });
+        let left_ordering = LexOrdering::new(left_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF left ordering must not be empty"
+            )
+        })?;
+        let right_ordering = LexOrdering::new(right_sort_exprs).ok_or_else(|| {
+            datafusion_common::internal_datafusion_err!(
+                "ASOF right ordering must not be empty"
+            )
+        })?;
+        let cache = Arc::new(Self::compute_properties(&left, &schema)?);
+
+        Ok(Self {
+            left,
+            right,
+            on,
+            match_condition,
+            right_output_indices,
+            schema,
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering,
+            right_ordering,
+            right_fut: Default::default(),
+            cache,
+        })
+    }
+
+    fn compute_properties(
+        left: &Arc<dyn ExecutionPlan>,
+        schema: &SchemaRef,
+    ) -> Result<PlanProperties> {
+        let left_schema = left.schema();
+        let mapping = ProjectionMapping::try_new(
+            left_schema
+                .fields()
+                .iter()
+                .enumerate()
+                .map(|(index, field)| {
+                    (
+                        Arc::new(PhysicalColumn::new(field.name(), index))
+                            as PhysicalExprRef,
+                        field.name().to_string(),
+                    )
+                }),
+            &left_schema,
+        )?;
+        let input_eq_properties = left.equivalence_properties();
+        let eq_properties = input_eq_properties.project(&mapping, Arc::clone(schema));
+        let output_partitioning = left
+            .output_partitioning()
+            .project(&mapping, input_eq_properties);
+        Ok(PlanProperties::new(
+            eq_properties,
+            output_partitioning,
+            EmissionType::Incremental,
+            Boundedness::Bounded,
+        ))
+    }
+}
+
+fn build_output_schema(
+    left: &SchemaRef,
+    right: &SchemaRef,
+    right_output_indices: &[usize],
+) -> SchemaRef {
+    let full_schema = build_join_schema(left, right, &JoinType::Left).0;
+    let left_len = left.fields().len();
+    let fields = full_schema
+        .fields()
+        .iter()
+        .take(left_len)
+        .cloned()
+        .chain(
+            right_output_indices
+                .iter()
+                .map(|index| Arc::clone(&full_schema.fields()[left_len + *index])),
+        )
+        .collect::<Vec<_>>();
+    Arc::new(Schema::new_with_metadata(
+        fields,
+        full_schema.metadata().clone(),
+    ))
+}
+
+impl DisplayAs for AsOfJoinExec {
+    fn fmt_as(&self, t: DisplayFormatType, f: &mut Formatter<'_>) -> std::fmt::Result {
+        let on = self
+            .on
+            .iter()
+            .map(|(left, right)| {
+                format!("({} = {})", fmt_sql(left.as_ref()), fmt_sql(right.as_ref()))
+            })
+            .collect::<Vec<_>>()
+            .join(", ");
+        let match_condition = format!(
+            "{} {} {}",
+            fmt_sql(self.match_condition.left.as_ref()),
+            self.match_condition.op,
+            fmt_sql(self.match_condition.right.as_ref())
+        );
+        match t {
+            DisplayFormatType::Default | DisplayFormatType::Verbose => write!(
+                f,
+                "{}: on=[{}], match=[{}]",
+                Self::static_name(),
+                on,
+                match_condition
+            ),
+            DisplayFormatType::TreeRender => {
+                writeln!(f, "on={on}")?;
+                writeln!(f, "match={match_condition}")
+            }
+        }
+    }
+}
+
+impl ExecutionPlan for AsOfJoinExec {
+    fn name(&self) -> &'static str {
+        "AsOfJoinExec"
+    }
+
+    fn properties(&self) -> &Arc<PlanProperties> {
+        &self.cache
+    }
+
+    fn required_input_distribution(&self) -> Vec<Distribution> {
+        self.input_distribution_requirements().into_per_child()
+    }
+
+    fn input_distribution_requirements(&self) -> InputDistributionRequirements {
+        // Every left partition scans the complete broadcast right input, so
+        // equality keys do not require the inputs to be co-partitioned.
+        InputDistributionRequirements::new(vec![
+            Distribution::UnspecifiedDistribution,
+            Distribution::SinglePartition,
+        ])
+    }
+
+    fn required_input_ordering(&self) -> Vec<Option<OrderingRequirements>> {
+        vec![
+            Some(OrderingRequirements::from(self.left_ordering.clone())),
+            Some(OrderingRequirements::from(self.right_ordering.clone())),
+        ]
+    }
+
+    fn maintains_input_order(&self) -> Vec<bool> {
+        vec![false, false]
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn ExecutionPlan>> {
+        vec![&self.left, &self.right]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        check_if_same_properties!(self, children);
+        match &children[..] {
+            [left, right] => Ok(Arc::new(Self::try_new(
+                Arc::clone(left),
+                Arc::clone(right),
+                self.on.clone(),
+                self.match_condition.clone(),
+                self.right_output_indices.clone(),
+            )?)),
+            _ => internal_err!("AsOfJoinExec requires two children"),
+        }
+    }
+
+    fn with_new_children_and_same_properties(
+        self: Arc<Self>,
+        mut children: Vec<Arc<dyn ExecutionPlan>>,
+    ) -> Result<Arc<dyn ExecutionPlan>> {
+        assert_eq_or_internal_err!(
+            children.len(),
+            2,
+            "AsOfJoinExec requires two children"
+        );
+        let left = children.remove(0);
+        let right = children.remove(0);
+        Ok(Arc::new(Self {
+            left,
+            right,
+            on: self.on.clone(),
+            match_condition: self.match_condition.clone(),
+            right_output_indices: self.right_output_indices.clone(),
+            schema: Arc::clone(&self.schema),
+            metrics: ExecutionPlanMetricsSet::new(),
+            left_ordering: self.left_ordering.clone(),
+            right_ordering: self.right_ordering.clone(),
+            right_fut: Default::default(),
+            cache: Arc::clone(&self.cache),
+        }))
+    }
+
+    fn execute(
+        &self,
+        partition: usize,
+        context: Arc<TaskContext>,
+    ) -> Result<SendableRecordBatchStream> {
+        let right_partitions = self.right.output_partitioning().partition_count();
+        assert_eq_or_internal_err!(
+            right_partitions,
+            1,
+            "AsOfJoinExec requires one right partition, found {right_partitions}"
+        );
+        let left_stream = self.left.execute(partition, Arc::clone(&context))?;
+        let metrics = AsOfJoinMetrics::new(partition, &self.metrics);
+        let build_metrics = metrics.clone();
+        let right_fut = self.right_fut.try_once(|| {
+            let right_stream = self.right.execute(0, Arc::clone(&context))?;
+            let reservation =
+                MemoryConsumer::new("AsOfJoinInput").register(context.memory_pool());
+            Ok(collect_right_input(
+                right_stream,
+                reservation,
+                build_metrics,
+            ))
+        })?;
+        let (left_keys, right_keys) = self.on.iter().cloned().unzip();
+        let output_schema = Arc::clone(&self.schema);
+        let stream_schema = Arc::clone(&output_schema);
+        let left_match = Arc::clone(&self.match_condition.left);
+        let right_match = Arc::clone(&self.match_condition.right);
+        let match_op = self.match_condition.op;
+        let right_output_indices = self.right_output_indices.clone();
+        let batch_size = context.session_config().batch_size();
+        let stream = stream::once(async move {
+            let mut right_fut = right_fut;
+            let right_input = poll_fn(|cx| right_fut.get_shared(cx)).await?;
+            let right_stream = right_input.stream()?;
+            let state = AsOfJoinStreamState::new(
+                Arc::clone(&stream_schema),
+                InputCursor::new(left_stream, left_keys, left_match),
+                InputCursor::new(right_stream, right_keys, right_match),
+                match_op,
+                right_output_indices,
+                batch_size,
+                metrics,
+            );
+            let stream = stream::try_unfold(
+                (state, right_input),
+                |(mut state, right_input)| async {
+                    match state.next_batch().await? {
+                        Some(batch) => Ok(Some((batch, (state, right_input)))),
+                        None => Ok(None),
+                    }
+                },
+            );
+            Ok::<SendableRecordBatchStream, datafusion_common::DataFusionError>(Box::pin(
+                RecordBatchStreamAdapter::new(stream_schema, stream),
+            ))
+        })
+        .try_flatten();
+        Ok(Box::pin(RecordBatchStreamAdapter::new(
+            output_schema,
+            stream,
+        )))
+    }
+
+    fn metrics(&self) -> Option<MetricsSet> {
+        Some(self.metrics.clone_inner())
+    }
+
+    fn child_stats_requests(&self, partition: Option<usize>) -> Vec<ChildStats> {
+        vec![ChildStats::At(partition), ChildStats::Skip]
+    }
+
+    fn statistics_from_inputs(
+        &self,
+        input_stats: &[Arc<Statistics>],
+        _args: &StatisticsArgs,
+    ) -> Result<Arc<Statistics>> {
+        // The default is fully unknown, but ASOF emits exactly one output row
+        // per left row and preserves statistics for unmodified left columns.
+        let left = &input_stats[0];
+        let mut column_statistics = left.column_statistics.clone();
+        column_statistics.truncate(self.left.schema().fields().len());
+        column_statistics.resize_with(
+            self.left.schema().fields().len(),
+            ColumnStatistics::new_unknown,
+        );
+        column_statistics.extend(
+            self.right_output_indices
+                .iter()
+                .map(|_| ColumnStatistics::new_unknown()),
+        );
+        Ok(Arc::new(Statistics {
+            num_rows: left.num_rows,
+            total_byte_size: Precision::Absent,
+            column_statistics,
+        }))
+    }
+}
+
+/// Materialized right input shared by every left output partition.
+struct BroadcastRightInput {
+    /// Schema retained even when the input has no batches.
+    schema: SchemaRef,
+    /// Ordered right batches; their buffers are shared without copying.
+    batches: Vec<RecordBatch>,
+    /// Holds the memory-pool reservation for as long as the batches are shared.
+    _reservation: MemoryReservation,
+}
+
+impl BroadcastRightInput {
+    fn stream(&self) -> Result<SendableRecordBatchStream> {
+        Ok(Box::pin(MemoryStream::try_new(
+            self.batches.clone(),
+            Arc::clone(&self.schema),
+            None,
+        )?))
+    }
+}
+
+async fn collect_right_input(
+    input: SendableRecordBatchStream,
+    reservation: MemoryReservation,
+    metrics: AsOfJoinMetrics,
+) -> Result<BroadcastRightInput> {
+    let schema = input.schema();
+    let mut memory_counter = RecordBatchMemoryCounter::new();
+    let batches = input
+        .try_fold(Vec::new(), |mut batches, batch| {
+            let batch_size = memory_counter.count_batch(&batch);
+            futures::future::ready(reservation.try_grow(batch_size).map(|_| {
+                metrics.build_mem_used.add(batch_size);
+                metrics.build_input_batches.add(1);
+                metrics.build_input_rows.add(batch.num_rows());
+                batches.push(batch);
+                batches
+            }))
+        })
+        .await?;
+    Ok(BroadcastRightInput {
+        schema,
+        batches,
+        _reservation: reservation,
+    })
+}
+
+#[derive(Clone)]
+struct Candidate {

Review Comment:
   I added detailed comments, including its cross-batch lifetime. I kept `Candidate` in the join state because its validity depends on both the right row and the current left equality group; putting it inside `InputCursor` would hide that cross-input invariant.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org


Re: [PR] feat: add ASOF join physical operator [datafusion]

Posted by "Xuanwo (via GitHub)" <gi...@apache.org>.
Xuanwo commented on PR #23828:
URL: https://github.com/apache/datafusion/pull/23828#issuecomment-5252463782

   Thanks for the detailed review — this was very helpful. I added result-based coverage for no equality keys, both `>=` and `<`, and complex equality/match expressions. I also aligned projection with the existing join convention, simplified the metrics and tests, and documented the state-machine loop. I left the `PendingRows` redesign and right-cursor fast-forwarding for a benchmark-backed follow-up after the end-to-end SQL integration, as suggested.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org