Skip to main content

mito2/read/
range_cache.rs

1// Copyright 2023 Greptime Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Utilities for the partition range scan result cache.
16
17use std::mem;
18use std::sync::Arc;
19
20use async_stream::try_stream;
21use common_telemetry::warn;
22use common_time::Timestamp;
23use common_time::range::TimestampRange;
24use common_time::timestamp::TimeUnit;
25use datafusion_expr::expr::Expr;
26use datafusion_expr::{Between, BinaryExpr, Operator};
27use datatypes::arrow::compute::concat_batches;
28use datatypes::arrow::record_batch::RecordBatch;
29use datatypes::prelude::ConcreteDataType;
30use datatypes::value::scalar_value_to_timestamp;
31use futures::TryStreamExt;
32use snafu::ResultExt;
33use store_api::region_engine::PartitionRange;
34use store_api::storage::{FileId, RegionId, TimeSeriesRowSelector};
35use table::predicate::is_string_timestamp_literal;
36use tokio::sync::{mpsc, oneshot};
37
38use crate::cache::CacheStrategy;
39use crate::error::{ComputeArrowSnafu, Result};
40use crate::read::BoxedRecordBatchStream;
41use crate::read::read_columns::ReadColumns;
42use crate::read::scan_region::StreamContext;
43use crate::read::scan_util::PartitionMetrics;
44use crate::region::options::MergeMode;
45use crate::sst::parquet::DEFAULT_READ_BATCH_SIZE;
46
47const RANGE_CACHE_COMPACT_THRESHOLD_BYTES: usize = 8 * 1024 * 1024;
48
49/// Fingerprint of the scan request fields that affect partition range cache reuse.
50///
51/// It records a normalized view of the projected columns and filters, plus
52/// scan options that can change the returned rows. Schema-dependent metadata
53/// and the partition expression version are included so cached results are not
54/// reused across incompatible schema or partitioning changes.
55#[derive(Debug, Clone, PartialEq, Eq, Hash)]
56pub(crate) struct ScanRequestFingerprint {
57    /// Projection and filters without the time index and partition exprs.
58    inner: Arc<SharedScanRequestFingerprint>,
59    /// Filters with the time index column.
60    time_filters: Option<Arc<Vec<String>>>,
61    series_row_selector: Option<TimeSeriesRowSelector>,
62    append_mode: bool,
63    filter_deleted: bool,
64    merge_mode: MergeMode,
65    stage: RangeScanStage,
66    /// We keep the partition expr version to ensure we won't reuse the fingerprint after we change the partition expr.
67    /// We store the version instead of the whole partition expr or partition expr filters.
68    partition_expr_version: u64,
69}
70
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
72enum RangeScanStage {
73    Data,
74    CandidateSeries,
75}
76
77#[derive(Debug)]
78pub(crate) struct ScanRequestFingerprintBuilder {
79    pub(crate) read_columns: ReadColumns,
80    pub(crate) read_column_types: Vec<Option<ConcreteDataType>>,
81    pub(crate) filters: Vec<String>,
82    pub(crate) time_filters: Vec<String>,
83    pub(crate) series_row_selector: Option<TimeSeriesRowSelector>,
84    pub(crate) append_mode: bool,
85    pub(crate) filter_deleted: bool,
86    pub(crate) merge_mode: MergeMode,
87    pub(crate) partition_expr_version: u64,
88}
89
90impl ScanRequestFingerprintBuilder {
91    pub(crate) fn build(self) -> ScanRequestFingerprint {
92        let Self {
93            read_columns,
94            read_column_types,
95            filters,
96            time_filters,
97            series_row_selector,
98            append_mode,
99            filter_deleted,
100            merge_mode,
101            partition_expr_version,
102        } = self;
103
104        ScanRequestFingerprint {
105            inner: Arc::new(SharedScanRequestFingerprint {
106                read_columns,
107                read_column_types,
108                filters,
109            }),
110            time_filters: (!time_filters.is_empty()).then(|| Arc::new(time_filters)),
111            series_row_selector,
112            append_mode,
113            filter_deleted,
114            merge_mode,
115            stage: RangeScanStage::Data,
116            partition_expr_version,
117        }
118    }
119}
120
121/// Non-copiable struct of the fingerprint.
122#[derive(Debug, PartialEq, Eq, Hash)]
123struct SharedScanRequestFingerprint {
124    /// Logical columns of the projection.
125    read_columns: ReadColumns,
126    /// Column types of the projection.
127    /// We keep this to ensure we won't reuse the fingerprint after a schema change.
128    read_column_types: Vec<Option<ConcreteDataType>>,
129    /// Filters without the time index column and region partition exprs.
130    filters: Vec<String>,
131}
132
133impl ScanRequestFingerprint {
134    #[cfg(test)]
135    pub(crate) fn read_columns(&self) -> &ReadColumns {
136        &self.inner.read_columns
137    }
138
139    #[cfg(test)]
140    pub(crate) fn read_column_types(&self) -> &[Option<ConcreteDataType>] {
141        &self.inner.read_column_types
142    }
143
144    #[cfg(test)]
145    pub(crate) fn filters(&self) -> &[String] {
146        &self.inner.filters
147    }
148
149    #[cfg(test)]
150    pub(crate) fn time_filters(&self) -> &[String] {
151        self.time_filters
152            .as_deref()
153            .map(Vec::as_slice)
154            .unwrap_or(&[])
155    }
156
157    pub(crate) fn without_time_filters(&self) -> Self {
158        Self {
159            inner: Arc::clone(&self.inner),
160            time_filters: None,
161            series_row_selector: self.series_row_selector,
162            append_mode: self.append_mode,
163            filter_deleted: self.filter_deleted,
164            merge_mode: self.merge_mode,
165            stage: self.stage,
166            partition_expr_version: self.partition_expr_version,
167        }
168    }
169
170    fn for_candidate_series(&self) -> Self {
171        Self {
172            inner: Arc::clone(&self.inner),
173            time_filters: self.time_filters.clone(),
174            series_row_selector: self.series_row_selector,
175            append_mode: self.append_mode,
176            filter_deleted: self.filter_deleted,
177            merge_mode: self.merge_mode,
178            stage: RangeScanStage::CandidateSeries,
179            partition_expr_version: self.partition_expr_version,
180        }
181    }
182
183    pub(crate) fn estimated_size(&self) -> usize {
184        mem::size_of::<SharedScanRequestFingerprint>()
185            + self.inner.read_columns.estimated_size()
186            + self.inner.read_column_types.capacity() * mem::size_of::<Option<ConcreteDataType>>()
187            + self.inner.filters.capacity() * mem::size_of::<String>()
188            + self
189                .inner
190                .filters
191                .iter()
192                .map(|filter| filter.capacity())
193                .sum::<usize>()
194            + self.time_filters.as_ref().map_or(0, |filters| {
195                mem::size_of::<Vec<String>>()
196                    + filters.capacity() * mem::size_of::<String>()
197                    + filters
198                        .iter()
199                        .map(|filter| filter.capacity())
200                        .sum::<usize>()
201            })
202    }
203}
204
205/// Cache key for range scan outputs.
206#[derive(Debug, Clone, PartialEq, Eq, Hash)]
207pub(crate) struct RangeScanCacheKey {
208    pub(crate) region_id: RegionId,
209    /// Sorted (file_id, row_group_index) pairs that uniquely identify the data this range covers.
210    pub(crate) row_groups: Vec<(FileId, i64)>,
211    pub(crate) scan: ScanRequestFingerprint,
212}
213
214impl RangeScanCacheKey {
215    pub(crate) fn estimated_size(&self) -> usize {
216        mem::size_of::<Self>()
217            + self.row_groups.capacity() * mem::size_of::<(FileId, i64)>()
218            + self.scan.estimated_size()
219    }
220}
221
222/// Cached result for one range scan.
223#[derive(Debug)]
224pub(crate) struct CachedBatchSlice {
225    batch: RecordBatch,
226    slice_lengths: Vec<usize>,
227}
228
229impl CachedBatchSlice {
230    fn metadata_size(&self) -> usize {
231        self.slice_lengths.capacity() * mem::size_of::<usize>()
232    }
233}
234
235pub(crate) struct RangeScanCacheValue {
236    cached_batches: Vec<CachedBatchSlice>,
237    /// Precomputed size of all compacted batches.
238    estimated_batches_size: usize,
239}
240
241impl RangeScanCacheValue {
242    pub(crate) fn new(
243        cached_batches: Vec<CachedBatchSlice>,
244        estimated_batches_size: usize,
245    ) -> Self {
246        Self {
247            cached_batches,
248            estimated_batches_size,
249        }
250    }
251
252    pub(crate) fn estimated_size(&self) -> usize {
253        mem::size_of::<Self>()
254            + self.cached_batches.capacity() * mem::size_of::<CachedBatchSlice>()
255            + self
256                .cached_batches
257                .iter()
258                .map(CachedBatchSlice::metadata_size)
259                .sum::<usize>()
260            + self.estimated_batches_size
261    }
262}
263
264/// Row groups and whether all sources are file-only for a partition range.
265pub(crate) struct PartitionRangeRowGroups {
266    /// Sorted (file_id, row_group_index) pairs.
267    pub(crate) row_groups: Vec<(FileId, i64)>,
268    pub(crate) only_file_sources: bool,
269}
270
271/// Collects (file_id, row_group_index) pairs from a partition range's row group indices.
272pub(crate) fn collect_partition_range_row_groups(
273    stream_ctx: &StreamContext,
274    part_range: &PartitionRange,
275) -> PartitionRangeRowGroups {
276    let range_meta = &stream_ctx.ranges[part_range.identifier];
277    let mut row_groups = Vec::new();
278    let mut only_file_sources = true;
279
280    for index in &range_meta.row_group_indices {
281        if stream_ctx.is_file_range_index(*index) {
282            let file_id = stream_ctx.input.file_from_index(*index).file_id().file_id();
283            row_groups.push((file_id, index.row_group_index));
284        } else {
285            only_file_sources = false;
286        }
287    }
288
289    row_groups.sort_unstable_by(|a, b| a.0.as_bytes().cmp(b.0.as_bytes()).then(a.1.cmp(&b.1)));
290
291    PartitionRangeRowGroups {
292        row_groups,
293        only_file_sources,
294    }
295}
296
297/// Returns the timestamp range where all time-only predicates are guaranteed true.
298///
299/// Returns `Some(min_to_max)` for empty input (vacuously true everywhere).
300/// Returns `None` if any expression contains an unsupported shape: `OR`, `NOT`,
301/// `IN`, non-literal RHS, unsupported operator, column-name mismatch, an `=`
302/// literal that cannot be represented exactly in the column unit, or overflow
303/// during bound adjustment.
304///
305/// This is intentionally stricter than `extract_time_range_from_expr` in
306/// `table::predicate`: lower bounds round up and upper bounds round down. If a
307/// partition's file-time range is contained by the returned range, every row in
308/// that partition satisfies the original time predicates.
309///
310/// `IsNull`/`IsNotNull` on the time index are not routed into `time_filters`
311/// today. If that changes, handle them here before stripping time filters from
312/// the cache key.
313pub(crate) fn implied_time_range_from_exprs(
314    ts_col_name: &str,
315    ts_col_unit: TimeUnit,
316    exprs: &[&Expr],
317) -> Option<TimestampRange> {
318    let mut acc = TimestampRange::min_to_max();
319    for expr in exprs {
320        let r = implied_time_range_from_expr(ts_col_name, ts_col_unit, expr)?;
321        acc = acc.and(&r);
322    }
323    Some(acc)
324}
325
326fn implied_time_range_from_expr(
327    ts_col_name: &str,
328    ts_col_unit: TimeUnit,
329    expr: &Expr,
330) -> Option<TimestampRange> {
331    match expr {
332        Expr::BinaryExpr(BinaryExpr { left, op, right }) => match op {
333            Operator::And => {
334                let l = implied_time_range_from_expr(ts_col_name, ts_col_unit, left)?;
335                let r = implied_time_range_from_expr(ts_col_name, ts_col_unit, right)?;
336                Some(l.and(&r))
337            }
338            Operator::Eq | Operator::Lt | Operator::LtEq | Operator::Gt | Operator::GtEq => {
339                implied_from_cmp(ts_col_name, ts_col_unit, left, *op, right)
340            }
341            // `OR` would require a strict intersection over a union of half-planes
342            // (not the loose-span union provided by `TimestampRange::or`), so we
343            // refuse it. Any other operator is unsupported.
344            _ => None,
345        },
346        Expr::Between(Between {
347            expr,
348            negated,
349            low,
350            high,
351        }) => {
352            if *negated {
353                return None;
354            }
355            implied_from_between(ts_col_name, ts_col_unit, expr, low, high)
356        }
357        // Includes `IsNull`, `IsNotNull`, `Not`, `InList`, function calls, etc.
358        _ => None,
359    }
360}
361
362fn match_ts_column_literal<'a>(
363    ts_col_name: &str,
364    left: &'a Expr,
365    right: &'a Expr,
366) -> Option<(Timestamp, bool)> {
367    let (col, scalar, reverse) = match (left, right) {
368        (Expr::Column(c), Expr::Literal(s, _)) => (c, s, false),
369        (Expr::Literal(s, _), Expr::Column(c)) => (c, s, true),
370        _ => return None,
371    };
372    if col.name != ts_col_name {
373        return None;
374    }
375    // Reject string literals: their conversion needs a timezone we do not have,
376    // and the existing extractor in `table::predicate` rejects them too.
377    if is_string_timestamp_literal(scalar) {
378        return None;
379    }
380    scalar_value_to_timestamp(scalar, None).map(|t| (t, reverse))
381}
382
383fn implied_from_cmp(
384    ts_col_name: &str,
385    ts_col_unit: TimeUnit,
386    left: &Expr,
387    op: Operator,
388    right: &Expr,
389) -> Option<TimestampRange> {
390    let (ts, reverse) = match_ts_column_literal(ts_col_name, left, right)?;
391    // Normalize to "column OP literal".
392    let op = if reverse {
393        match op {
394            Operator::Lt => Operator::Gt,
395            Operator::LtEq => Operator::GtEq,
396            Operator::Gt => Operator::Lt,
397            Operator::GtEq => Operator::LtEq,
398            Operator::Eq => Operator::Eq,
399            _ => return None,
400        }
401    } else {
402        op
403    };
404
405    match op {
406        Operator::GtEq => {
407            // ts >= L. Round the lower bound up in the column unit.
408            let b = ts.convert_to_ceil(ts_col_unit)?;
409            Some(TimestampRange::from_start(b))
410        }
411        Operator::Gt => {
412            // ts > L. floor(L) + 1 is the tight lower bound in the column unit.
413            let v = ts.convert_to(ts_col_unit)?.value().checked_add(1)?;
414            Some(TimestampRange::from_start(Timestamp::new(v, ts_col_unit)))
415        }
416        Operator::LtEq => {
417            // ts <= L. Round the upper bound down in the column unit.
418            let b = ts.convert_to(ts_col_unit)?;
419            Some(TimestampRange::until_end(b, true))
420        }
421        Operator::Lt => {
422            // ts < L. `ts < ceil(L)` is the tight bound: equal to `ts < L` when
423            // L is exactly representable, and `ts <= floor(L)` otherwise.
424            let b = ts.convert_to_ceil(ts_col_unit)?;
425            Some(TimestampRange::until_end(b, false))
426        }
427        Operator::Eq => {
428            // ts = L. Only provable when L is exactly representable.
429            let f = ts.convert_to(ts_col_unit)?;
430            let c = ts.convert_to_ceil(ts_col_unit)?;
431            if f.value() != c.value() {
432                return None;
433            }
434            Some(TimestampRange::single(f))
435        }
436        _ => None,
437    }
438}
439
440fn implied_from_between(
441    ts_col_name: &str,
442    ts_col_unit: TimeUnit,
443    expr: &Expr,
444    low: &Expr,
445    high: &Expr,
446) -> Option<TimestampRange> {
447    let Expr::Column(c) = expr else {
448        return None;
449    };
450    if c.name != ts_col_name {
451        return None;
452    }
453    let (low_s, high_s) = match (low, high) {
454        (Expr::Literal(l, _), Expr::Literal(h, _)) => (l, h),
455        _ => return None,
456    };
457    if is_string_timestamp_literal(low_s) || is_string_timestamp_literal(high_s) {
458        return None;
459    }
460    let low_ts = scalar_value_to_timestamp(low_s, None)?;
461    let high_ts = scalar_value_to_timestamp(high_s, None)?;
462    // BETWEEN low AND high is equivalent to ts >= low AND ts <= high.
463    let lo = low_ts.convert_to_ceil(ts_col_unit)?;
464    let hi = high_ts.convert_to(ts_col_unit)?;
465    Some(TimestampRange::new_inclusive(Some(lo), Some(hi)))
466}
467
468/// Builds a cache key for the given partition range if it is eligible for caching.
469pub(crate) fn build_range_cache_key(
470    stream_ctx: &StreamContext,
471    part_range: &PartitionRange,
472) -> Option<RangeScanCacheKey> {
473    build_range_cache_key_inner(stream_ctx, part_range, false)
474}
475
476/// Builds a cache key for a candidate-series partition-range result.
477pub(crate) fn build_candidate_range_cache_key(
478    stream_ctx: &StreamContext,
479    part_range: &PartitionRange,
480) -> Option<RangeScanCacheKey> {
481    build_range_cache_key_inner(stream_ctx, part_range, true)
482}
483
484fn build_range_cache_key_inner(
485    stream_ctx: &StreamContext,
486    part_range: &PartitionRange,
487    candidate_series: bool,
488) -> Option<RangeScanCacheKey> {
489    if !stream_ctx.input.cache_strategy.has_range_result_cache() {
490        return None;
491    }
492
493    let fingerprint = stream_ctx.scan_fingerprint.as_ref()?;
494
495    // Dyn filters can change at runtime, so we can't cache when they're present.
496    let has_dyn_filters = stream_ctx
497        .input
498        .predicate_group()
499        .predicate_without_region()
500        .is_some_and(|p| !p.dyn_filters().is_empty());
501    if has_dyn_filters {
502        return None;
503    }
504
505    let rg = collect_partition_range_row_groups(stream_ctx, part_range);
506    if !rg.only_file_sources || rg.row_groups.is_empty() {
507        return None;
508    }
509
510    // If the implied range covers this partition's `FileTimeRange`, drop
511    // time-only predicates from the cache key so that queries with different
512    // but equally-covering time bounds share an entry. `None` means some
513    // time-only predicate had an unsupported shape (e.g. `OR`), so we keep
514    // them in the key.
515    let range_meta = &stream_ctx.ranges[part_range.identifier];
516    let (file_min, file_max) = range_meta.time_range;
517    let covers = match &stream_ctx.scan_implied_time_range {
518        // An empty implied range can never cover a non-empty file range, so
519        // short-circuit. We also skip the unit asserts because
520        // `TimestampRange::empty()` uses `Timestamp::default()` (millisecond),
521        // which would falsely trip the asserts for non-ms time index columns.
522        Some(implied) if !implied.is_empty() => {
523            // The `contains` check is sound only when `file_min`/`file_max`
524            // share the implied range's unit (the time index column's unit).
525            // Mito stores time index values in that unit; assert to catch any
526            // future drift.
527            if let Some(ts) = implied.start().as_ref().or(implied.end().as_ref()) {
528                assert_eq!(file_min.unit(), ts.unit());
529                assert_eq!(file_max.unit(), ts.unit());
530            }
531            implied.contains(&file_min) && implied.contains(&file_max)
532        }
533        _ => false,
534    };
535    let scan = if covers {
536        fingerprint.without_time_filters()
537    } else {
538        fingerprint.clone()
539    };
540    let scan = if candidate_series {
541        scan.for_candidate_series()
542    } else {
543        scan
544    };
545
546    Some(RangeScanCacheKey {
547        region_id: stream_ctx.input.region_metadata().region_id,
548        row_groups: rg.row_groups,
549        scan,
550    })
551}
552
553/// Returns a stream that replays cached record batches.
554pub(crate) fn cached_flat_range_stream(value: Arc<RangeScanCacheValue>) -> BoxedRecordBatchStream {
555    Box::pin(try_stream! {
556        for cached_batch in &value.cached_batches {
557            let mut offset = 0;
558            for &len in &cached_batch.slice_lengths {
559                yield cached_batch.batch.slice(offset, len);
560                offset += len;
561            }
562        }
563    })
564}
565
566enum CacheConcatCommand {
567    Compact(Vec<RecordBatch>),
568    Finish {
569        pending: Vec<RecordBatch>,
570        key: RangeScanCacheKey,
571        cache_strategy: CacheStrategy,
572        part_metrics: PartitionMetrics,
573        result_tx: Option<oneshot::Sender<Result<Arc<RangeScanCacheValue>>>>,
574    },
575}
576
577#[derive(Default)]
578struct CacheConcatState {
579    cached_batches: Vec<CachedBatchSlice>,
580    estimated_size: usize,
581}
582
583impl CacheConcatState {
584    async fn compact(
585        &mut self,
586        batches: Vec<RecordBatch>,
587        limiter: &crate::cache::RangeResultMemoryLimiter,
588    ) -> Result<()> {
589        if batches.is_empty() {
590            return Ok(());
591        }
592
593        let input_size = batches
594            .iter()
595            .map(RecordBatch::get_array_memory_size)
596            .sum::<usize>();
597        let _permit = limiter.acquire(input_size).await?;
598
599        let compacted = compact_record_batches(batches)?;
600        self.estimated_size += compacted.batch.get_array_memory_size();
601        self.cached_batches.push(compacted);
602        Ok(())
603    }
604
605    fn finish(self) -> RangeScanCacheValue {
606        RangeScanCacheValue::new(self.cached_batches, self.estimated_size)
607    }
608}
609
610fn compact_record_batches(batches: Vec<RecordBatch>) -> Result<CachedBatchSlice> {
611    debug_assert!(!batches.is_empty());
612
613    let slice_lengths = batches.iter().map(RecordBatch::num_rows).collect();
614    build_cached_batch_slice(batches, slice_lengths)
615}
616
617fn build_cached_batch_slice(
618    batches: Vec<RecordBatch>,
619    slice_lengths: Vec<usize>,
620) -> Result<CachedBatchSlice> {
621    let batch = if batches.len() == 1 {
622        batches.into_iter().next().unwrap()
623    } else {
624        let schema = batches[0].schema();
625        concat_batches(&schema, &batches).context(ComputeArrowSnafu)?
626    };
627
628    Ok(CachedBatchSlice {
629        batch,
630        slice_lengths,
631    })
632}
633
634async fn run_cache_concat_task(
635    mut rx: mpsc::UnboundedReceiver<CacheConcatCommand>,
636    limiter: Arc<crate::cache::RangeResultMemoryLimiter>,
637    skip_threshold_bytes: usize,
638) {
639    let mut state = CacheConcatState::default();
640
641    while let Some(cmd) = rx.recv().await {
642        match cmd {
643            CacheConcatCommand::Compact(batches) => {
644                if let Err(err) = state.compact(batches, &limiter).await {
645                    warn!(err; "Failed to compact range cache batches");
646                    return;
647                }
648                // Close the channel to stop further work as soon as the cached
649                // size exceeds the configured cache budget.
650                if state.estimated_size > skip_threshold_bytes {
651                    return;
652                }
653            }
654            CacheConcatCommand::Finish {
655                pending,
656                key,
657                cache_strategy,
658                part_metrics,
659                result_tx,
660            } => {
661                let compact_result = state
662                    .compact(pending, &limiter)
663                    .await
664                    .map(|()| state.finish());
665                let result = match compact_result {
666                    Ok(v) => {
667                        let value = Arc::new(v);
668                        part_metrics
669                            .inc_range_cache_size(key.estimated_size() + value.estimated_size());
670                        cache_strategy.put_range_result(key, value.clone());
671
672                        Ok(value)
673                    }
674                    Err(e) => {
675                        warn!(e; "Failed to finalize range cache batches");
676
677                        Err(e)
678                    }
679                };
680
681                if let Some(tx) = result_tx {
682                    let _ = tx.send(result);
683                }
684
685                break;
686            }
687        }
688    }
689}
690
691struct CacheBatchBuffer {
692    buffered_batches: Vec<RecordBatch>,
693    buffered_rows: usize,
694    buffered_size: usize,
695    sender: Option<mpsc::UnboundedSender<CacheConcatCommand>>,
696}
697
698impl CacheBatchBuffer {
699    fn new(cache_strategy: &CacheStrategy) -> Self {
700        let sender = cache_strategy.range_result_memory_limiter().map(|limiter| {
701            let skip_threshold_bytes = cache_strategy.range_result_cache_size().unwrap_or(0);
702            let (tx, rx) = mpsc::unbounded_channel();
703            common_runtime::spawn_query(run_cache_concat_task(
704                rx,
705                limiter.clone(),
706                skip_threshold_bytes,
707            ));
708            tx
709        });
710
711        Self {
712            buffered_batches: Vec::new(),
713            buffered_rows: 0,
714            buffered_size: 0,
715            sender,
716        }
717    }
718
719    fn push(&mut self, batch: RecordBatch) -> Result<()> {
720        if self.sender.is_none() {
721            return Ok(());
722        }
723
724        self.buffered_rows += batch.num_rows();
725        self.buffered_size += batch.get_array_memory_size();
726        self.buffered_batches.push(batch);
727
728        if self.buffered_batches.len() > 1
729            && (self.buffered_rows > DEFAULT_READ_BATCH_SIZE
730                || self.buffered_size > RANGE_CACHE_COMPACT_THRESHOLD_BYTES)
731        {
732            self.notify_compact();
733        }
734
735        Ok(())
736    }
737
738    fn notify_compact(&mut self) {
739        if self.buffered_batches.is_empty() || self.sender.is_none() {
740            return;
741        }
742
743        let batches = mem::take(&mut self.buffered_batches);
744        self.buffered_rows = 0;
745        self.buffered_size = 0;
746
747        let Some(sender) = &self.sender else {
748            return;
749        };
750        if sender.send(CacheConcatCommand::Compact(batches)).is_err() {
751            self.sender = None;
752        }
753    }
754
755    fn finish(
756        mut self,
757        key: RangeScanCacheKey,
758        cache_strategy: CacheStrategy,
759        part_metrics: PartitionMetrics,
760        result_tx: Option<oneshot::Sender<Result<Arc<RangeScanCacheValue>>>>,
761    ) {
762        let Some(sender) = self.sender.take() else {
763            return;
764        };
765
766        if sender
767            .send(CacheConcatCommand::Finish {
768                pending: mem::take(&mut self.buffered_batches),
769                key,
770                cache_strategy,
771                part_metrics,
772                result_tx,
773            })
774            .is_err()
775        {
776            self.sender = None;
777        }
778    }
779}
780
781/// Wraps a stream to cache its output for future range cache hits.
782pub(crate) fn cache_flat_range_stream(
783    mut stream: BoxedRecordBatchStream,
784    cache_strategy: CacheStrategy,
785    key: RangeScanCacheKey,
786    part_metrics: PartitionMetrics,
787) -> BoxedRecordBatchStream {
788    Box::pin(try_stream! {
789        let mut buffer = CacheBatchBuffer::new(&cache_strategy);
790        while let Some(batch) = stream.try_next().await? {
791            buffer.push(batch.clone())?;
792            yield batch;
793        }
794
795        buffer.finish(key, cache_strategy, part_metrics, None);
796    })
797}
798
799/// Creates a `cache_flat_range_stream` with dummy internals for benchmarking.
800///
801/// This avoids exposing `RangeScanCacheKey`, `ScanRequestFingerprint`, and
802/// `PartitionMetrics` publicly.
803#[cfg(feature = "test")]
804pub fn bench_cache_flat_range_stream(
805    stream: BoxedRecordBatchStream,
806    cache_size_bytes: u64,
807    region_id: RegionId,
808) -> BoxedRecordBatchStream {
809    use std::time::Instant;
810
811    use datafusion::physical_plan::metrics::ExecutionPlanMetricsSet;
812
813    use crate::region::options::MergeMode;
814
815    let cache_manager = Arc::new(
816        crate::cache::CacheManager::builder()
817            .range_result_cache_size(cache_size_bytes)
818            .build(),
819    );
820    let cache_strategy = CacheStrategy::EnableAll(cache_manager);
821
822    let fingerprint = ScanRequestFingerprintBuilder {
823        read_columns: ReadColumns::from_deduped_column_ids(std::iter::empty()),
824        read_column_types: vec![],
825        filters: vec![],
826        time_filters: vec![],
827        series_row_selector: None,
828        append_mode: false,
829        filter_deleted: false,
830        merge_mode: MergeMode::LastRow,
831        partition_expr_version: 0,
832    }
833    .build();
834
835    let key = RangeScanCacheKey {
836        region_id,
837        row_groups: vec![],
838        scan: fingerprint,
839    };
840
841    let metrics_set = ExecutionPlanMetricsSet::new();
842    let part_metrics =
843        PartitionMetrics::new(region_id, 0, "bench", Instant::now(), false, &metrics_set);
844
845    cache_flat_range_stream(stream, cache_strategy, key, part_metrics)
846}
847
848#[cfg(test)]
849mod tests {
850    use std::sync::Arc;
851    use std::time::Instant;
852
853    use common_time::Timestamp;
854    use common_time::range::TimestampRange;
855    use common_time::timestamp::TimeUnit;
856    use datafusion::physical_plan::metrics::ExecutionPlanMetricsSet;
857    use datafusion_common::ScalarValue;
858    use datafusion_expr::{Expr, col, lit};
859    use smallvec::smallvec;
860    use store_api::storage::{FileId, RegionId};
861
862    use super::*;
863    use crate::cache::CacheManager;
864    use crate::read::flat_projection::FlatProjectionMapper;
865    use crate::read::range::{RangeMeta, RowGroupIndex, SourceIndex};
866    use crate::read::scan_region::{PredicateGroup, ScanInput};
867    use crate::sst::file::FileTimeRange;
868    use crate::test_util::memtable_util::metadata_with_primary_key;
869    use crate::test_util::scheduler_util::SchedulerEnv;
870    use crate::test_util::sst_util::sst_file_handle_with_file_id;
871
872    fn test_cache_strategy() -> CacheStrategy {
873        CacheStrategy::EnableAll(Arc::new(
874            CacheManager::builder()
875                .range_result_cache_size(1024 * 1024)
876                .build(),
877        ))
878    }
879
880    fn test_scan_fingerprint(
881        filters: Vec<String>,
882        time_filters: Vec<String>,
883        series_row_selector: Option<TimeSeriesRowSelector>,
884        filter_deleted: bool,
885        partition_expr_version: u64,
886    ) -> ScanRequestFingerprint {
887        let read_columns = ReadColumns::from_deduped_column_ids([1, 2]);
888        ScanRequestFingerprintBuilder {
889            read_columns,
890            read_column_types: vec![None, None],
891            filters,
892            time_filters,
893            series_row_selector,
894            append_mode: false,
895            filter_deleted,
896            merge_mode: MergeMode::LastRow,
897            partition_expr_version,
898        }
899        .build()
900    }
901
902    fn test_cache_context(strategy: &CacheStrategy) -> (RangeScanCacheKey, PartitionMetrics) {
903        let region_id = RegionId::new(1, 1);
904        let key = RangeScanCacheKey {
905            region_id,
906            row_groups: vec![],
907            scan: test_scan_fingerprint(vec![], vec![], None, false, 0),
908        };
909
910        let metrics_set = ExecutionPlanMetricsSet::new();
911        let part_metrics =
912            PartitionMetrics::new(region_id, 0, "test", Instant::now(), false, &metrics_set);
913
914        assert!(strategy.get_range_result(&key).is_none());
915        (key, part_metrics)
916    }
917
918    async fn finish_cache_batch_buffer(
919        buffer: CacheBatchBuffer,
920        key: RangeScanCacheKey,
921        cache_strategy: CacheStrategy,
922        part_metrics: PartitionMetrics,
923    ) -> Result<Arc<RangeScanCacheValue>> {
924        let (tx, rx) = oneshot::channel();
925        common_telemetry::info!("finish start");
926        buffer.finish(key, cache_strategy, part_metrics, Some(tx));
927        common_telemetry::info!("finish end");
928        rx.await.context(crate::error::RecvSnafu)?
929    }
930
931    async fn new_stream_context(
932        filters: Vec<Expr>,
933        query_time_range: Option<TimestampRange>,
934        partition_time_range: FileTimeRange,
935    ) -> (StreamContext, PartitionRange) {
936        let env = SchedulerEnv::new().await;
937        let metadata = Arc::new(metadata_with_primary_key(vec![0, 1], false));
938        let mapper = FlatProjectionMapper::new(&metadata, [0, 2, 3]).unwrap();
939        let predicate = PredicateGroup::new(metadata.as_ref(), &filters).unwrap();
940        let file_id = FileId::random();
941        let file = sst_file_handle_with_file_id(
942            file_id,
943            partition_time_range.0.value(),
944            partition_time_range.1.value(),
945        );
946        let input = ScanInput::new(env.access_layer.clone(), mapper)
947            .with_predicate(predicate)
948            .with_time_range(query_time_range)
949            .with_files(vec![file])
950            .with_cache(test_cache_strategy());
951        let range_meta = RangeMeta {
952            time_range: partition_time_range,
953            indices: smallvec![SourceIndex {
954                index: 0,
955                num_row_groups: 1,
956            }],
957            row_group_indices: smallvec![RowGroupIndex {
958                index: 0,
959                row_group_index: 0,
960            }],
961            num_rows: 10,
962        };
963        let partition_range = range_meta.new_partition_range(0);
964        let (scan_fingerprint, scan_implied_time_range) =
965            match crate::read::scan_region::build_scan_fingerprint(&input) {
966                Some(b) => (Some(b.fingerprint), b.implied_time_range),
967                None => (None, None),
968            };
969        let stream_ctx = StreamContext {
970            input,
971            ranges: vec![range_meta],
972            scan_fingerprint,
973            scan_implied_time_range,
974            query_start: Instant::now(),
975        };
976
977        (stream_ctx, partition_range)
978    }
979
980    /// Helper to create a timestamp millisecond literal.
981    fn ts_lit(val: i64) -> Expr {
982        lit(ScalarValue::TimestampMillisecond(Some(val), None))
983    }
984
985    fn normalized_exprs(exprs: impl IntoIterator<Item = Expr>) -> Vec<String> {
986        let mut exprs = exprs
987            .into_iter()
988            .map(|expr| expr.to_string())
989            .collect::<Vec<_>>();
990        exprs.sort_unstable();
991        exprs
992    }
993
994    async fn assert_range_cache_filters(
995        filters: Vec<Expr>,
996        query_time_range: Option<TimestampRange>,
997        partition_time_range: FileTimeRange,
998        expected_filters: Vec<Expr>,
999        expected_time_filters: Vec<Expr>,
1000    ) {
1001        let (stream_ctx, part_range) =
1002            new_stream_context(filters, query_time_range, partition_time_range).await;
1003
1004        let key = build_range_cache_key(&stream_ctx, &part_range).unwrap();
1005
1006        assert_eq!(
1007            key.scan.filters(),
1008            normalized_exprs(expected_filters).as_slice()
1009        );
1010        assert_eq!(
1011            key.scan.time_filters(),
1012            normalized_exprs(expected_time_filters).as_slice()
1013        );
1014    }
1015
1016    #[tokio::test]
1017    async fn range_cache_time_filter_key_cases() {
1018        let partition = (
1019            Timestamp::new_millisecond(1000),
1020            Timestamp::new_millisecond(2000),
1021        );
1022
1023        struct Case {
1024            filters: Vec<Expr>,
1025            query_time_range: Option<TimestampRange>,
1026            expected_filters: Vec<Expr>,
1027            expected_time_filters: Vec<Expr>,
1028        }
1029
1030        // Time filters are stripped only when their implied range fully covers
1031        // the partition's file-time range. `is_not_null(ts)` stays in regular
1032        // filters because it is not routed into `time_filters`.
1033        for case in [
1034            Case {
1035                filters: vec![
1036                    col("ts").gt_eq(ts_lit(1000)),
1037                    col("ts").lt(ts_lit(2001)),
1038                    col("ts").is_not_null(),
1039                    col("k0").eq(lit("foo")),
1040                ],
1041                query_time_range: TimestampRange::with_unit(1000, 2002, TimeUnit::Millisecond),
1042                expected_filters: vec![col("k0").eq(lit("foo")), col("ts").is_not_null()],
1043                expected_time_filters: vec![],
1044            },
1045            Case {
1046                filters: vec![
1047                    col("ts").gt_eq(ts_lit(500)),
1048                    col("ts").lt(ts_lit(3000)),
1049                    col("k0").eq(lit("foo")),
1050                ],
1051                query_time_range: TimestampRange::with_unit(500, 3000, TimeUnit::Millisecond),
1052                expected_filters: vec![col("k0").eq(lit("foo"))],
1053                expected_time_filters: vec![],
1054            },
1055            Case {
1056                filters: vec![
1057                    col("ts").gt_eq(ts_lit(1000)),
1058                    col("ts").lt_eq(ts_lit(2000)),
1059                    col("k0").eq(lit("foo")),
1060                ],
1061                query_time_range: TimestampRange::with_unit(1000, 2001, TimeUnit::Millisecond),
1062                expected_filters: vec![col("k0").eq(lit("foo"))],
1063                expected_time_filters: vec![],
1064            },
1065            Case {
1066                filters: vec![
1067                    col("ts").between(ts_lit(1000), ts_lit(2000)),
1068                    col("k0").eq(lit("foo")),
1069                ],
1070                query_time_range: TimestampRange::with_unit(1000, 2001, TimeUnit::Millisecond),
1071                expected_filters: vec![col("k0").eq(lit("foo"))],
1072                expected_time_filters: vec![],
1073            },
1074            Case {
1075                filters: vec![col("ts").gt_eq(ts_lit(1200)), col("k0").eq(lit("foo"))],
1076                query_time_range: TimestampRange::with_unit(1200, 2001, TimeUnit::Millisecond),
1077                expected_filters: vec![col("k0").eq(lit("foo"))],
1078                expected_time_filters: vec![col("ts").gt_eq(ts_lit(1200))],
1079            },
1080            Case {
1081                filters: vec![
1082                    col("ts").gt_eq(ts_lit(1500)),
1083                    col("ts").is_not_null(),
1084                    col("k0").eq(lit("foo")),
1085                ],
1086                query_time_range: None,
1087                expected_filters: vec![col("k0").eq(lit("foo")), col("ts").is_not_null()],
1088                expected_time_filters: vec![col("ts").gt_eq(ts_lit(1500))],
1089            },
1090        ] {
1091            assert_range_cache_filters(
1092                case.filters,
1093                case.query_time_range,
1094                partition,
1095                case.expected_filters,
1096                case.expected_time_filters,
1097            )
1098            .await;
1099        }
1100    }
1101
1102    #[tokio::test]
1103    async fn two_distinct_queries_share_cache_key_when_both_cover() {
1104        let partition_range = (
1105            Timestamp::new_millisecond(1000),
1106            Timestamp::new_millisecond(2000),
1107        );
1108
1109        let (ctx_a, part_a) = new_stream_context(
1110            vec![
1111                col("ts").gt_eq(ts_lit(500)),
1112                col("ts").lt(ts_lit(3000)),
1113                col("k0").eq(lit("foo")),
1114            ],
1115            TimestampRange::with_unit(500, 3000, TimeUnit::Millisecond),
1116            partition_range,
1117        )
1118        .await;
1119        let (ctx_b, part_b) = new_stream_context(
1120            vec![
1121                col("ts").gt_eq(ts_lit(100)),
1122                col("ts").lt(ts_lit(5000)),
1123                col("k0").eq(lit("foo")),
1124            ],
1125            TimestampRange::with_unit(100, 5000, TimeUnit::Millisecond),
1126            partition_range,
1127        )
1128        .await;
1129
1130        let key_a = build_range_cache_key(&ctx_a, &part_a).unwrap();
1131        let key_b = build_range_cache_key(&ctx_b, &part_b).unwrap();
1132        assert_eq!(key_a.scan, key_b.scan);
1133        assert!(key_a.scan.time_filters().is_empty());
1134    }
1135
1136    #[tokio::test]
1137    async fn candidate_series_cache_key_is_separate_from_data() {
1138        let partition_range = (
1139            Timestamp::new_millisecond(1000),
1140            Timestamp::new_millisecond(2000),
1141        );
1142        let (ctx, part_range) =
1143            new_stream_context(vec![col("k0").eq(lit("foo"))], None, partition_range).await;
1144
1145        let data_key = build_range_cache_key(&ctx, &part_range).unwrap();
1146        let candidate_key = build_candidate_range_cache_key(&ctx, &part_range).unwrap();
1147
1148        assert_ne!(data_key.scan, candidate_key.scan);
1149        assert_eq!(data_key.row_groups, candidate_key.row_groups);
1150    }
1151
1152    #[tokio::test]
1153    async fn disables_optimization_on_or_clause() {
1154        let partition_range = (
1155            Timestamp::new_millisecond(1000),
1156            Timestamp::new_millisecond(2000),
1157        );
1158
1159        let or_a = col("ts").gt_eq(ts_lit(1000)).or(col("ts").lt(ts_lit(500)));
1160        let or_b = col("ts").gt_eq(ts_lit(900)).or(col("ts").lt(ts_lit(400)));
1161
1162        let (ctx_a, part_a) = new_stream_context(
1163            vec![or_a.clone(), col("k0").eq(lit("foo"))],
1164            None,
1165            partition_range,
1166        )
1167        .await;
1168        let (ctx_b, part_b) = new_stream_context(
1169            vec![or_b.clone(), col("k0").eq(lit("foo"))],
1170            None,
1171            partition_range,
1172        )
1173        .await;
1174
1175        assert!(ctx_a.scan_implied_time_range.is_none());
1176        let key_a = build_range_cache_key(&ctx_a, &part_a).unwrap();
1177        let key_b = build_range_cache_key(&ctx_b, &part_b).unwrap();
1178        assert_ne!(key_a.scan, key_b.scan);
1179        assert_eq!(
1180            key_a.scan.time_filters(),
1181            normalized_exprs([or_a]).as_slice()
1182        );
1183    }
1184
1185    #[tokio::test]
1186    async fn empty_implied_range_does_not_panic_on_non_ms_file_range() {
1187        // Contradictory time predicates make the implied range empty. The
1188        // empty range's sentinel timestamps use `Timestamp::default()` (ms),
1189        // so without the `is_empty()` short-circuit the unit asserts would
1190        // panic against a non-ms `range_meta.time_range`.
1191        let partition = (
1192            Timestamp::new_millisecond(1000),
1193            Timestamp::new_millisecond(2000),
1194        );
1195
1196        let (mut ctx, part_range) = new_stream_context(
1197            vec![col("ts").gt_eq(ts_lit(1500)), col("k0").eq(lit("foo"))],
1198            TimestampRange::with_unit(1500, 3000, TimeUnit::Millisecond),
1199            partition,
1200        )
1201        .await;
1202
1203        ctx.scan_implied_time_range = Some(TimestampRange::empty());
1204        ctx.ranges[0].time_range = (
1205            Timestamp::new(1_000_000_000, TimeUnit::Nanosecond),
1206            Timestamp::new(2_000_000_000, TimeUnit::Nanosecond),
1207        );
1208
1209        let key = build_range_cache_key(&ctx, &part_range).unwrap();
1210        // Empty implied range cannot cover, so time filters stay in the key.
1211        assert!(!key.scan.time_filters().is_empty());
1212    }
1213
1214    fn ms_ts(v: i64) -> Timestamp {
1215        Timestamp::new_millisecond(v)
1216    }
1217
1218    fn implied_ms(expr: Expr) -> Option<TimestampRange> {
1219        implied_time_range_from_exprs("ts", TimeUnit::Millisecond, &[&expr])
1220    }
1221
1222    #[test]
1223    fn implied_time_range_supported_exprs() {
1224        for (expr, expected) in [
1225            (
1226                col("ts").gt_eq(ts_lit(1000)),
1227                Some(TimestampRange::from_start(ms_ts(1000))),
1228            ),
1229            (
1230                col("ts").gt(ts_lit(1000)),
1231                Some(TimestampRange::from_start(ms_ts(1001))),
1232            ),
1233            (
1234                col("ts").lt_eq(ts_lit(2000)),
1235                Some(TimestampRange::until_end(ms_ts(2000), true)),
1236            ),
1237            (
1238                col("ts").lt(ts_lit(2000)),
1239                Some(TimestampRange::until_end(ms_ts(2000), false)),
1240            ),
1241            (
1242                col("ts").eq(ts_lit(1500)),
1243                Some(TimestampRange::single(ms_ts(1500))),
1244            ),
1245            (
1246                ts_lit(1000).lt_eq(col("ts")),
1247                Some(TimestampRange::from_start(ms_ts(1000))),
1248            ),
1249            (
1250                col("ts").between(ts_lit(1000), ts_lit(2000)),
1251                Some(TimestampRange::new_inclusive(
1252                    Some(ms_ts(1000)),
1253                    Some(ms_ts(2000)),
1254                )),
1255            ),
1256            (
1257                col("ts")
1258                    .gt_eq(ts_lit(1000))
1259                    .and(col("ts").lt(ts_lit(2000))),
1260                TimestampRange::with_unit(1000, 2000, TimeUnit::Millisecond),
1261            ),
1262            (
1263                col("ts")
1264                    .gt_eq(ts_lit(1000))
1265                    .and(col("ts").lt(ts_lit(5000)))
1266                    .and(col("ts").lt_eq(ts_lit(3000))),
1267                TimestampRange::with_unit(1000, 3001, TimeUnit::Millisecond),
1268            ),
1269        ] {
1270            assert_eq!(implied_ms(expr), expected);
1271        }
1272
1273        assert_eq!(
1274            implied_time_range_from_exprs("ts", TimeUnit::Millisecond, &[]),
1275            Some(TimestampRange::min_to_max())
1276        );
1277    }
1278
1279    #[test]
1280    fn implied_time_range_unsupported_exprs() {
1281        let not_between = Expr::Between(Between {
1282            expr: Box::new(col("ts")),
1283            negated: true,
1284            low: Box::new(ts_lit(1000)),
1285            high: Box::new(ts_lit(2000)),
1286        });
1287
1288        for expr in [
1289            not_between,
1290            col("ts").gt_eq(ts_lit(1000)).or(col("ts").lt(ts_lit(500))),
1291            Expr::Not(Box::new(col("ts").gt_eq(ts_lit(1000)))),
1292            col("ts").in_list(vec![ts_lit(1000), ts_lit(2000)], false),
1293            col("ts").gt_eq(col("other")),
1294            col("other_ts").gt_eq(ts_lit(1000)),
1295        ] {
1296            assert!(implied_ms(expr).is_none());
1297        }
1298    }
1299
1300    #[test]
1301    fn implied_time_range_unit_conversion() {
1302        let second_1 = lit(ScalarValue::TimestampSecond(Some(1), None));
1303        let ns_1500 = lit(ScalarValue::TimestampNanosecond(Some(1_500_000_000), None));
1304        let ns_1500_5 = lit(ScalarValue::TimestampNanosecond(Some(1_500_500_000), None));
1305
1306        for (expr, expected) in [
1307            (
1308                col("ts").gt_eq(second_1.clone()),
1309                Some(TimestampRange::from_start(ms_ts(1000))),
1310            ),
1311            (
1312                col("ts").lt_eq(second_1),
1313                Some(TimestampRange::until_end(ms_ts(1000), true)),
1314            ),
1315            (
1316                col("ts").eq(ns_1500),
1317                Some(TimestampRange::single(ms_ts(1500))),
1318            ),
1319            (col("ts").eq(ns_1500_5.clone()), None),
1320            (
1321                col("ts").gt_eq(ns_1500_5.clone()),
1322                Some(TimestampRange::from_start(ms_ts(1501))),
1323            ),
1324            (
1325                col("ts").lt_eq(ns_1500_5.clone()),
1326                Some(TimestampRange::until_end(ms_ts(1500), true)),
1327            ),
1328            (
1329                col("ts").gt(ns_1500_5.clone()),
1330                Some(TimestampRange::from_start(ms_ts(1501))),
1331            ),
1332            (
1333                col("ts").lt(ns_1500_5),
1334                Some(TimestampRange::until_end(ms_ts(1501), false)),
1335            ),
1336        ] {
1337            assert_eq!(implied_ms(expr), expected);
1338        }
1339    }
1340
1341    #[test]
1342    fn normalizes_and_clears_time_filters() {
1343        let normalized =
1344            test_scan_fingerprint(vec!["k0 = 'foo'".to_string()], vec![], None, true, 0);
1345
1346        assert!(normalized.time_filters().is_empty());
1347
1348        let fingerprint = test_scan_fingerprint(
1349            vec!["k0 = 'foo'".to_string()],
1350            vec!["ts >= 1000".to_string()],
1351            Some(TimeSeriesRowSelector::LastRow),
1352            true,
1353            7,
1354        );
1355
1356        let reset = fingerprint.without_time_filters();
1357
1358        assert_eq!(reset.read_columns(), fingerprint.read_columns());
1359        assert_eq!(reset.read_column_types(), fingerprint.read_column_types());
1360        assert_eq!(reset.filters(), fingerprint.filters());
1361        assert!(reset.time_filters().is_empty());
1362        assert_eq!(reset.series_row_selector, fingerprint.series_row_selector);
1363        assert_eq!(reset.append_mode, fingerprint.append_mode);
1364        assert_eq!(reset.filter_deleted, fingerprint.filter_deleted);
1365        assert_eq!(reset.merge_mode, fingerprint.merge_mode);
1366        assert_eq!(
1367            reset.partition_expr_version,
1368            fingerprint.partition_expr_version
1369        );
1370    }
1371
1372    fn test_schema() -> Arc<datatypes::arrow::datatypes::Schema> {
1373        use datatypes::arrow::datatypes::{DataType as ArrowDataType, Field, Schema};
1374
1375        Arc::new(Schema::new(vec![Field::new(
1376            "value",
1377            ArrowDataType::Int64,
1378            false,
1379        )]))
1380    }
1381
1382    fn make_batch(values: &[i64]) -> RecordBatch {
1383        use datatypes::arrow::array::Int64Array;
1384
1385        RecordBatch::try_new(
1386            test_schema(),
1387            vec![Arc::new(Int64Array::from(values.to_vec()))],
1388        )
1389        .unwrap()
1390    }
1391
1392    fn make_large_binary_batch(rows: usize, bytes_per_row: usize) -> RecordBatch {
1393        use datatypes::arrow::array::BinaryArray;
1394        use datatypes::arrow::datatypes::{DataType as ArrowDataType, Field, Schema};
1395
1396        let schema = Arc::new(Schema::new(vec![Field::new(
1397            "value",
1398            ArrowDataType::Binary,
1399            false,
1400        )]));
1401        let payload = vec![b'x'; bytes_per_row];
1402        let values = (0..rows).map(|_| payload.as_slice()).collect::<Vec<_>>();
1403
1404        RecordBatch::try_new(schema, vec![Arc::new(BinaryArray::from_vec(values))]).unwrap()
1405    }
1406
1407    #[test]
1408    fn compact_record_batches_keeps_original_boundaries() {
1409        let batches = vec![make_batch(&[1, 2]), make_batch(&[3]), make_batch(&[4, 5])];
1410
1411        let compacted = compact_record_batches(batches).unwrap();
1412
1413        assert_eq!(compacted.batch.num_rows(), 5);
1414        assert_eq!(compacted.slice_lengths, vec![2, 1, 2]);
1415    }
1416
1417    #[tokio::test]
1418    async fn cached_flat_range_stream_replays_original_batches() {
1419        let value = Arc::new(RangeScanCacheValue::new(
1420            vec![CachedBatchSlice {
1421                batch: make_batch(&[1, 2, 3]),
1422                slice_lengths: vec![2, 1],
1423            }],
1424            make_batch(&[1, 2, 3]).get_array_memory_size(),
1425        ));
1426
1427        let replayed = cached_flat_range_stream(value)
1428            .try_collect::<Vec<_>>()
1429            .await
1430            .unwrap();
1431
1432        assert_eq!(replayed.len(), 2);
1433        assert_eq!(replayed[0].num_rows(), 2);
1434        assert_eq!(replayed[1].num_rows(), 1);
1435    }
1436
1437    #[tokio::test]
1438    async fn cache_batch_buffer_finishes_pending_batches() {
1439        let strategy = test_cache_strategy();
1440        let batch = make_batch(&[1, 2, 3]);
1441        let expected_size = batch.get_array_memory_size();
1442        let (key, part_metrics) = test_cache_context(&strategy);
1443
1444        let mut buffer = CacheBatchBuffer::new(&strategy);
1445        buffer.push(batch).unwrap();
1446
1447        let value = finish_cache_batch_buffer(buffer, key.clone(), strategy.clone(), part_metrics)
1448            .await
1449            .unwrap();
1450        assert_eq!(value.cached_batches.len(), 1);
1451        assert_eq!(value.cached_batches[0].slice_lengths, vec![3]);
1452        assert_eq!(value.estimated_batches_size, expected_size);
1453        assert!(Arc::ptr_eq(
1454            &value,
1455            &strategy.get_range_result(&key).unwrap()
1456        ));
1457    }
1458
1459    #[tokio::test]
1460    async fn cache_batch_buffer_compacts_when_rows_exceed_default_batch_size() {
1461        let strategy = test_cache_strategy();
1462        let batch = make_batch(&vec![1; DEFAULT_READ_BATCH_SIZE / 2 + 1]);
1463        let (key, part_metrics) = test_cache_context(&strategy);
1464
1465        let mut buffer = CacheBatchBuffer::new(&strategy);
1466        buffer.push(batch.clone()).unwrap();
1467        buffer.push(batch).unwrap();
1468
1469        assert_eq!(buffer.buffered_rows, 0);
1470        assert!(buffer.buffered_batches.is_empty());
1471
1472        let value = finish_cache_batch_buffer(buffer, key, strategy, part_metrics)
1473            .await
1474            .unwrap();
1475        assert_eq!(value.cached_batches.len(), 1);
1476        assert_eq!(
1477            value.cached_batches[0].slice_lengths,
1478            vec![
1479                DEFAULT_READ_BATCH_SIZE / 2 + 1,
1480                DEFAULT_READ_BATCH_SIZE / 2 + 1
1481            ]
1482        );
1483    }
1484
1485    #[tokio::test]
1486    async fn cache_batch_buffer_compacts_when_buffered_size_exceeds_threshold() {
1487        let large_batch = make_large_binary_batch(DEFAULT_READ_BATCH_SIZE, 4096);
1488        let strategy = CacheStrategy::EnableAll(Arc::new(
1489            CacheManager::builder()
1490                .range_result_cache_size((large_batch.get_array_memory_size() * 3) as u64)
1491                .build(),
1492        ));
1493        let (key, part_metrics) = test_cache_context(&strategy);
1494
1495        let mut buffer = CacheBatchBuffer::new(&strategy);
1496        buffer.push(large_batch.clone()).unwrap();
1497
1498        assert_eq!(buffer.buffered_rows, large_batch.num_rows());
1499        assert_eq!(buffer.buffered_batches.len(), 1);
1500
1501        buffer.push(large_batch.clone()).unwrap();
1502
1503        assert_eq!(buffer.buffered_rows, 0);
1504        assert!(buffer.buffered_batches.is_empty());
1505
1506        let value = finish_cache_batch_buffer(buffer, key, strategy, part_metrics)
1507            .await
1508            .unwrap();
1509        assert_eq!(value.cached_batches.len(), 1);
1510        assert_eq!(
1511            value.cached_batches[0].slice_lengths,
1512            vec![large_batch.num_rows(), large_batch.num_rows()]
1513        );
1514    }
1515
1516    #[tokio::test]
1517    async fn cache_batch_buffer_skips_cache_when_compacted_size_exceeds_limit() {
1518        let large_batch = make_large_binary_batch(DEFAULT_READ_BATCH_SIZE / 2 + 1, 4096);
1519        // Budget only fits two large batches.
1520        let budget = (large_batch.get_array_memory_size() as u64) * 2 + 1;
1521        let strategy = CacheStrategy::EnableAll(Arc::new(
1522            CacheManager::builder()
1523                .range_result_cache_size(budget)
1524                .build(),
1525        ));
1526        let (key, part_metrics) = test_cache_context(&strategy);
1527
1528        let mut buffer = CacheBatchBuffer::new(&strategy);
1529        for _ in 0..4 {
1530            buffer.push(large_batch.clone()).unwrap();
1531        }
1532        assert!(
1533            finish_cache_batch_buffer(buffer, key.clone(), strategy.clone(), part_metrics)
1534                .await
1535                .is_err()
1536        );
1537        assert!(strategy.get_range_result(&key).is_none());
1538    }
1539}