Skip to main content

mito2/compaction/
compactor.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
15use std::collections::HashSet;
16use std::num::NonZeroU64;
17use std::sync::Arc;
18use std::time::Duration;
19
20use common_base::Plugins;
21use common_meta::key::SchemaMetadataManagerRef;
22use common_telemetry::{info, warn};
23use common_time::TimeToLive;
24use either::Either;
25use futures::{StreamExt, stream};
26use itertools::Itertools;
27use object_store::manager::ObjectStoreManagerRef;
28use partition::expr::PartitionExpr;
29use serde::{Deserialize, Serialize};
30use snafu::{OptionExt, ResultExt, ensure};
31use store_api::ManifestVersion;
32use store_api::metadata::RegionMetadataRef;
33use store_api::region_request::PathType;
34use store_api::storage::{RegionId, SequenceNumber};
35use tokio_util::sync::CancellationToken;
36
37use crate::access_layer::{
38    AccessLayer, AccessLayerRef, Metrics, OperationType, SstWriteRequest, WriteType,
39};
40use crate::cache::{CacheManager, CacheManagerRef};
41use crate::compaction::picker::PickerOutput;
42use crate::compaction::reader::{CompactionSstReaderBuilder, spawn_merge};
43use crate::compaction::unit::CompactionUnit;
44use crate::compaction::{CompactionOutput, find_dynamic_options};
45use crate::config::MitoConfig;
46use crate::engine::region_hook::{RegionHookRef, SstFileInfo};
47use crate::error;
48use crate::error::{
49    EmptyRegionDirSnafu, InvalidPartitionExprSnafu, ObjectStoreNotFoundSnafu, Result,
50};
51use crate::manifest::action::{RegionEdit, RegionMetaAction, RegionMetaActionList};
52use crate::manifest::manager::{RegionManifestManager, RegionManifestOptions};
53use crate::region::options::{MergeMode, RegionOptions};
54use crate::region::version::VersionRef;
55use crate::region::{ManifestContext, RegionLeaderState, RegionRoleState};
56use crate::schedule::scheduler::LocalScheduler;
57use crate::sst::FormatType;
58use crate::sst::file::{self, FileHandle, FileMeta, RegionFileId, UncommittedSsts};
59use crate::sst::file_metadata::{FileMetadataInterner, FileMetadataInternerRef};
60use crate::sst::file_purger::LocalFilePurger;
61use crate::sst::index::IndexBuildType;
62use crate::sst::index::build::IndexBuildInputs;
63use crate::sst::index::handler::{IndexKindProviderRef, PlanContext};
64use crate::sst::index::intermediate::IntermediateManager;
65use crate::sst::index::puffin_manager::PuffinManagerFactory;
66use crate::sst::index::registry::{IndexBuildPlan, IndexRegistry};
67use crate::sst::location::region_dir_from_table_dir;
68use crate::sst::parquet::metadata::extract_primary_key_range;
69use crate::sst::parquet::parallel_writer::EncodeRuntime;
70use crate::sst::parquet::writer::SstWriteContext;
71use crate::sst::parquet::{SstInfo, WriteOptions};
72use crate::sst::version::{SstVersion, SstVersionRef};
73
74/// Region version for compaction that does not hold memtables.
75#[derive(Clone)]
76pub struct CompactionVersion {
77    /// Metadata of the region.
78    ///
79    /// Altering metadata isn't frequent, storing metadata in Arc to allow sharing
80    /// metadata and reuse metadata when creating a new `Version`.
81    pub(crate) metadata: RegionMetadataRef,
82    /// Options of the region.
83    pub(crate) options: RegionOptions,
84    /// SSTs of the region.
85    pub(crate) ssts: SstVersionRef,
86    /// Lower bound of pending memtable sequences from the same Version as `ssts`.
87    /// None means no barrier; Some(0) conservatively represents an unknown bound.
88    /// Keep only the value so background compaction cannot pin flushed memtables.
89    pub(crate) memtable_min_sequence: Option<SequenceNumber>,
90    /// Inferred compaction time window.
91    pub(crate) compaction_time_window: Option<Duration>,
92}
93
94impl From<VersionRef> for CompactionVersion {
95    fn from(value: VersionRef) -> Self {
96        Self {
97            metadata: value.metadata.clone(),
98            options: value.options.clone(),
99            ssts: value.ssts.clone(),
100            memtable_min_sequence: if value.options.merge_mode() == MergeMode::LastNonNull {
101                value.memtables.min_sequence()
102            } else {
103                None
104            },
105            compaction_time_window: value.compaction_time_window,
106        }
107    }
108}
109
110/// CompactionRegion represents a region that needs to be compacted.
111/// It's the subset of MitoRegion.
112#[derive(Clone)]
113pub struct CompactionRegion {
114    pub region_id: RegionId,
115    pub region_options: RegionOptions,
116
117    pub(crate) engine_config: Arc<MitoConfig>,
118    pub(crate) region_metadata: RegionMetadataRef,
119    pub(crate) cache_manager: CacheManagerRef,
120    /// Access layer to get the table path and path type.
121    pub access_layer: AccessLayerRef,
122    pub(crate) manifest_ctx: Arc<ManifestContext>,
123    pub(crate) current_version: CompactionVersion,
124    pub(crate) file_purger: Option<Arc<LocalFilePurger>>,
125    pub(crate) ttl: Option<TimeToLive>,
126
127    /// Controls the parallelism of this compaction task. Default is 1.
128    ///
129    /// The parallel is inside this compaction task, not across different compaction tasks.
130    /// It can be different windows of the same compaction task or something like this.
131    pub max_parallelism: usize,
132
133    pub(crate) plugins: Plugins,
134}
135
136/// Execution resources for compaction, without a region-wide SST snapshot.
137///
138/// Inputs are owned by each output or unit so a slow sibling cannot retain
139/// files that another unit has already replaced.
140#[derive(Clone)]
141pub struct CompactionContext {
142    /// Region whose files are being compacted.
143    pub region_id: RegionId,
144    /// Region options including resolved dynamic compaction options.
145    pub region_options: RegionOptions,
146    /// Options from the version used to plan the merge.
147    version_options: RegionOptions,
148    pub(crate) engine_config: Arc<MitoConfig>,
149    region_metadata: RegionMetadataRef,
150    pub(crate) cache_manager: CacheManagerRef,
151    pub(crate) access_layer: AccessLayerRef,
152    manifest_ctx: Arc<ManifestContext>,
153    plugins: Plugins,
154    index_plan: Arc<IndexBuildPlan>,
155    index_registry: Arc<IndexRegistry>,
156    existing_index_inputs: Option<Arc<HashSet<RegionFileId>>>,
157}
158
159impl TryFrom<&CompactionRegion> for CompactionContext {
160    type Error = error::Error;
161
162    fn try_from(region: &CompactionRegion) -> Result<Self> {
163        let registry = IndexRegistry::from_config(
164            &region.engine_config,
165            region.plugins.get::<IndexKindProviderRef>(),
166        )?;
167        let index_plan = Arc::new(registry.plan(&PlanContext {
168            metadata: &region.region_metadata,
169            index_options: &region.current_version.options.index_options,
170            build_type: IndexBuildType::Compact,
171            existing_indexes: &[],
172        }));
173        Ok(Self {
174            region_id: region.region_id,
175            region_options: region.region_options.clone(),
176            version_options: region.current_version.options.clone(),
177            engine_config: region.engine_config.clone(),
178            region_metadata: region.region_metadata.clone(),
179            cache_manager: region.cache_manager.clone(),
180            access_layer: region.access_layer.clone(),
181            manifest_ctx: region.manifest_ctx.clone(),
182            plugins: region.plugins.clone(),
183            index_plan,
184            index_registry: Arc::new(registry),
185            existing_index_inputs: None,
186        })
187    }
188}
189
190/// Builds a minimal [`CompactionRegion`] for tests that do not touch the access layer.
191#[cfg(test)]
192pub(crate) async fn new_test_compaction_region() -> CompactionRegion {
193    let env = crate::test_util::scheduler_util::SchedulerEnv::new().await;
194    let metadata = crate::test_util::memtable_util::metadata_for_test();
195    let manifest_ctx = env.mock_manifest_context(metadata.clone()).await;
196    CompactionRegion {
197        region_id: RegionId::new(1, 1),
198        region_options: RegionOptions::default(),
199        engine_config: Arc::new(MitoConfig::default()),
200        region_metadata: metadata.clone(),
201        cache_manager: Arc::new(CacheManager::default()),
202        access_layer: env.access_layer.clone(),
203        manifest_ctx,
204        current_version: CompactionVersion {
205            metadata: metadata.clone(),
206            options: RegionOptions::default(),
207            ssts: Arc::new(SstVersion::new(metadata)),
208            memtable_min_sequence: None,
209            compaction_time_window: None,
210        },
211        file_purger: None,
212        ttl: None,
213        max_parallelism: 1,
214        plugins: Plugins::new(),
215    }
216}
217
218/// OpenCompactionRegionRequest represents the request to open a compaction region.
219#[derive(Clone)]
220pub struct OpenCompactionRegionRequest {
221    pub region_id: RegionId,
222    pub table_dir: String,
223    pub path_type: PathType,
224    pub region_options: RegionOptions,
225    pub max_parallelism: usize,
226    /// Plugins for the compaction region, used to look up the [`RegionHook`](crate::engine::region_hook::RegionHook).
227    pub plugins: Plugins,
228}
229
230/// Opens manifest-backed compaction regions using executor-owned index resources.
231///
232/// Create one opener per auxiliary directory before accepting jobs and reuse it
233/// for the executor's lifetime. Initialization recovers staging files and removes
234/// stale intermediate files, so repeating it can delete another job's live files.
235#[derive(Clone)]
236pub struct CompactionRegionOpener {
237    file_metadata_interner: FileMetadataInternerRef,
238    mito_config: Arc<MitoConfig>,
239    object_store_manager: ObjectStoreManagerRef,
240    puffin_manager_factory: PuffinManagerFactory,
241    intermediate_manager: IntermediateManager,
242}
243
244impl CompactionRegionOpener {
245    /// Initializes the executor's index resources. The config must be sanitized
246    /// and its auxiliary directory must not be owned by another engine or opener.
247    pub async fn new(
248        mito_config: MitoConfig,
249        object_store_manager: ObjectStoreManagerRef,
250    ) -> Result<Self> {
251        let puffin_manager_factory = PuffinManagerFactory::new(
252            &mito_config.index.aux_path,
253            mito_config.index.staging_size.as_bytes(),
254            Some(mito_config.index.write_buffer_size.as_bytes() as _),
255            mito_config.index.staging_ttl,
256        )
257        .await?;
258        let intermediate_manager =
259            IntermediateManager::init_fs(&mito_config.index.aux_path).await?;
260
261        Ok(Self {
262            file_metadata_interner: FileMetadataInterner::new(),
263            mito_config: Arc::new(mito_config),
264            object_store_manager,
265            puffin_manager_factory,
266            intermediate_manager,
267        })
268    }
269
270    /// Opens a region without reinitializing or cleaning shared index resources.
271    pub async fn open(
272        &self,
273        req: &OpenCompactionRegionRequest,
274        ttl_provider: Either<TimeToLive, SchemaMetadataManagerRef>,
275    ) -> Result<CompactionRegion> {
276        let mito_config = &self.mito_config;
277        let object_store = {
278            let name = &req.region_options.storage;
279            if let Some(name) = name {
280                self.object_store_manager
281                    .find(name)
282                    .with_context(|| ObjectStoreNotFoundSnafu {
283                        object_store: name.clone(),
284                    })?
285            } else {
286                self.object_store_manager.default_object_store()
287            }
288        };
289
290        let access_layer = Arc::new(AccessLayer::new(
291            &req.table_dir,
292            req.path_type,
293            object_store.clone(),
294            self.puffin_manager_factory.clone(),
295            self.intermediate_manager.clone(),
296        ));
297
298        let manifest_manager = {
299            let region_dir =
300                region_dir_from_table_dir(&req.table_dir, req.region_id, req.path_type);
301            let region_manifest_options = RegionManifestOptions::new(
302                mito_config,
303                &region_dir,
304                object_store,
305                self.file_metadata_interner.clone(),
306            );
307
308            RegionManifestManager::open(region_manifest_options, &Default::default())
309                .await?
310                .with_context(|| EmptyRegionDirSnafu {
311                    region_id: req.region_id,
312                    region_dir: region_dir_from_table_dir(
313                        &req.table_dir,
314                        req.region_id,
315                        req.path_type,
316                    ),
317                })?
318        };
319
320        let manifest = manifest_manager.manifest();
321        let region_metadata = manifest.metadata.clone();
322        let hook: Option<RegionHookRef> = req.plugins.get();
323        let manifest_ctx = Arc::new(ManifestContext::new(
324            manifest_manager,
325            RegionRoleState::Leader(RegionLeaderState::Writable),
326            hook,
327            Default::default(),
328        ));
329
330        let file_purger = {
331            let purge_scheduler = Arc::new(LocalScheduler::new(mito_config.max_background_purges));
332            Arc::new(LocalFilePurger::new(
333                purge_scheduler.clone(),
334                access_layer.clone(),
335                None,
336            ))
337        };
338
339        let current_version = {
340            let mut ssts = SstVersion::new(region_metadata.clone());
341            ssts.add_files(file_purger.clone(), manifest.files.values().cloned());
342            CompactionVersion {
343                metadata: region_metadata.clone(),
344                options: req.region_options.clone(),
345                ssts: Arc::new(ssts),
346                // Remote execution uses an already picked output. A manifest-only
347                // opener cannot prove that a new LastNonNull pick is memtable-safe.
348                memtable_min_sequence: Some(0),
349                compaction_time_window: manifest.compaction_time_window,
350            }
351        };
352
353        let ttl = match ttl_provider {
354            // Use the specified ttl.
355            Either::Left(ttl) => ttl,
356            // Get the ttl from the schema metadata manager.
357            Either::Right(schema_metadata_manager) => {
358                let (_, ttl) = find_dynamic_options(
359                    req.region_id,
360                    &req.region_options,
361                    &schema_metadata_manager,
362                )
363                .await
364                .unwrap_or_else(|e| {
365                    warn!(e; "Failed to get ttl for region: {}", region_metadata.region_id);
366                    (
367                        crate::region::options::CompactionOptions::default(),
368                        TimeToLive::default(),
369                    )
370                });
371                ttl
372            }
373        };
374
375        Ok(CompactionRegion {
376            region_id: req.region_id,
377            region_options: req.region_options.clone(),
378            engine_config: self.mito_config.clone(),
379            region_metadata: region_metadata.clone(),
380            // Lets the scan reuse the input footers read while planning the merge.
381            cache_manager: Arc::new(
382                CacheManager::builder()
383                    .sst_meta_cache_size(mito_config.sst_meta_cache_size.as_bytes())
384                    // This per-job cache has no readers for the newly written outputs.
385                    .disable_sst_meta_cache_on_write()
386                    .build(),
387            ),
388            access_layer,
389            manifest_ctx,
390            current_version,
391            file_purger: Some(file_purger),
392            ttl: Some(ttl),
393            max_parallelism: req.max_parallelism,
394            plugins: req.plugins.clone(),
395        })
396    }
397}
398
399impl CompactionRegion {
400    /// Get the file purger of the compaction region.
401    pub fn file_purger(&self) -> Option<Arc<LocalFilePurger>> {
402        self.file_purger.clone()
403    }
404
405    /// Stop the file purger scheduler of the compaction region.
406    pub async fn stop_purger_scheduler(&self) -> Result<()> {
407        if let Some(file_purger) = &self.file_purger {
408            file_purger.stop_scheduler().await
409        } else {
410            Ok(())
411        }
412    }
413
414    /// Fires [`RegionHook::on_sst_files_written`] for the freshly-merged SST
415    /// files in `merge_output`. Shared by both compaction paths, it must run
416    /// before this unit's [`Compactor::update_manifest`] so its committed edit
417    /// can be associated with the SST metadata reported here.
418    pub async fn invoke_sst_hook(&self, merge_output: &MergeOutput) {
419        invoke_sst_hook(
420            &self.plugins,
421            self.region_id,
422            &self.region_metadata,
423            merge_output,
424        )
425        .await;
426    }
427}
428
429async fn invoke_sst_hook(
430    plugins: &Plugins,
431    region_id: RegionId,
432    metadata: &RegionMetadataRef,
433    merge_output: &MergeOutput,
434) {
435    let Some(hook) = plugins.get::<RegionHookRef>() else {
436        return;
437    };
438
439    // Remote compaction deserializes `MergeOutput` over gRPC, where
440    // `sst_infos` is `#[serde(skip)]`. Rebuild each `SstInfo` from the
441    // matching `FileMeta` so the hook observes real ids/rows/sizes rather
442    // than zeros — see [`sst_info_from_file_meta`] for what stays default.
443    let synthesized: Vec<SstInfo>;
444    let infos: &[SstInfo] = if merge_output.sst_infos.is_empty() {
445        synthesized = merge_output
446            .files_to_add
447            .iter()
448            .map(sst_info_from_file_meta)
449            .collect();
450        &synthesized
451    } else {
452        // `sst_infos` and `files_to_add` are documented as 1:1. If they
453        // ever diverge, `zip` below would silently truncate; warn so the
454        // mismatch is observable rather than dropping files from the hook.
455        if merge_output.sst_infos.len() != merge_output.files_to_add.len() {
456            warn!(
457                "sst_infos length ({}) does not match files_to_add length ({}) for region {}",
458                merge_output.sst_infos.len(),
459                merge_output.files_to_add.len(),
460                region_id
461            );
462        }
463        &merge_output.sst_infos
464    };
465
466    let files: Vec<SstFileInfo<'_>> = merge_output
467        .files_to_add
468        .iter()
469        .zip(infos)
470        .map(|(meta, info)| SstFileInfo {
471            sst_info_ref: info,
472            file_meta: meta,
473        })
474        .collect();
475    hook.on_sst_files_written(region_id, metadata, &files).await;
476}
477
478impl CompactionContext {
479    /// Missing sketch implementations must not block compaction after a downgrade.
480    fn warn_missing_index_handlers<'a>(&self, inputs: impl Iterator<Item = &'a FileHandle>) {
481        self.index_registry.warn_missing_compaction_handlers(
482            &self.region_metadata,
483            inputs.map(FileHandle::meta_ref),
484        );
485    }
486
487    /// Checks each physical input once before output tasks begin. Missing inputs
488    /// disable imported summaries without changing the reader's tolerant behavior.
489    async fn prepare_index_inputs<'a>(
490        &mut self,
491        inputs: impl Iterator<Item = &'a FileHandle>,
492        cancellation: &CancellationToken,
493    ) -> Result<()> {
494        if !self.index_plan.needs_input_reuse() {
495            return Ok(());
496        }
497        let ids: HashSet<_> = inputs.map(FileHandle::file_id).collect();
498        let access_layer = &self.access_layer;
499        let existing = stream::iter(ids)
500            .map(|id| async move {
501                let path = crate::sst::location::sst_file_path(
502                    access_layer.table_dir(),
503                    id,
504                    access_layer.path_type(),
505                );
506                matches!(access_layer.object_store().exists(&path).await, Ok(true)).then_some(id)
507            })
508            .buffer_unordered(8)
509            .filter_map(|id| async move { id })
510            .collect::<HashSet<_>>();
511        // Read-only probes can be dropped without waiting for writer cleanup.
512        let existing = tokio::select! {
513            biased;
514            _ = cancellation.cancelled() => return error::CompactionCancelledSnafu.fail(),
515            existing = existing => existing,
516        };
517        // FileHandles protect ordinary purge; external object-store deletion can race.
518        self.existing_index_inputs = Some(Arc::new(existing));
519        Ok(())
520    }
521
522    /// Reports this unit's output metadata before publishing its manifest edit.
523    pub(crate) async fn invoke_sst_hook(&self, merge_output: &MergeOutput) {
524        invoke_sst_hook(
525            &self.plugins,
526            self.region_id,
527            &self.region_metadata,
528            merge_output,
529        )
530        .await;
531    }
532
533    /// Publishes outputs through the existing manifest validation and hook path.
534    pub(crate) async fn update_manifest(
535        &self,
536        merge_output: MergeOutput,
537    ) -> Result<(RegionEdit, ManifestVersion)> {
538        let edit = RegionEdit {
539            files_to_add: merge_output.files_to_add,
540            files_to_remove: merge_output.files_to_remove,
541            timestamp_ms: Some(chrono::Utc::now().timestamp_millis()),
542            compaction_time_window: merge_output
543                .compaction_time_window
544                .map(|seconds| Duration::from_secs(seconds as u64)),
545            flushed_entry_id: None,
546            flushed_sequence: None,
547            committed_sequence: None,
548            wal_recovery: Default::default(),
549        };
550
551        let action_list = RegionMetaActionList::with_action(RegionMetaAction::Edit(edit.clone()));
552        let manifest_version = self
553            .manifest_ctx
554            .update_manifest_for_compaction(action_list)
555            .await?;
556
557        Ok((edit, manifest_version))
558    }
559}
560
561/// Builds an [`SstInfo`] for the remote-compaction path by copying the scalar
562/// fields that [`FileMeta`] also carries.
563///
564/// Remote compaction runs off-process and ships `MergeOutput` over the wire;
565/// [`MergeOutput::sst_infos`] is `#[serde(skip)]` because the parquet footer
566/// (`ParquetMetaData`) is not serde-serializable. To avoid feeding the hook
567/// default (zero) values for real SSTs, this rebuilds the seven fields `FileMeta`
568/// and `SstInfo` share: `file_id`, `time_range`, `file_size`,
569/// `max_row_group_uncompressed_size`, `num_rows`, `num_row_groups`, `num_series`.
570///
571/// Two fields stay default and **cannot be recovered on the datanode**:
572/// - `file_metadata` — the parquet footer, whose column min/max/null-count
573///   statistics are required by hooks building richer artifacts (e.g. an Iceberg
574///   manifest). That data is produced by the compactor's writer and exists only
575///   in the freshly-written SST on object storage.
576/// - `index_metadata` — `FileMeta` tracks indexes via `available_indexes` /
577///   `indexes`, not as an [`IndexOutput`].
578///
579/// A hook that needs column stats must fetch the footer from object storage
580/// (the [`CompactionRegion`]'s `access_layer` reaches the store), or the footer
581/// must be shipped over the wire (revisit the `#[serde(skip)]` on `sst_infos`).
582/// `num_rows` may read `0` for legacy `FileMeta`s where the count is unknown.
583fn sst_info_from_file_meta(meta: &FileMeta) -> SstInfo {
584    SstInfo {
585        file_id: meta.file_id,
586        time_range: meta.time_range,
587        file_size: meta.file_size,
588        max_row_group_uncompressed_size: meta.max_row_group_uncompressed_size,
589        num_rows: meta.num_rows as usize,
590        num_row_groups: meta.num_row_groups,
591        num_series: meta.num_series,
592        ..Default::default()
593    }
594}
595
596/// `[MergeOutput]` represents the output of merging SST files.
597#[derive(Default, Debug, Serialize, Deserialize)]
598pub struct MergeOutput {
599    pub files_to_add: Vec<FileMeta>,
600    pub files_to_remove: Vec<FileMeta>,
601    pub compaction_time_window: Option<i64>,
602    #[serde(skip)]
603    pub sst_infos: Vec<SstInfo>,
604}
605
606impl MergeOutput {
607    pub fn is_empty(&self) -> bool {
608        self.files_to_add.is_empty() && self.files_to_remove.is_empty()
609    }
610
611    pub fn input_file_size(&self) -> u64 {
612        self.files_to_remove.iter().map(|f| f.file_size).sum()
613    }
614
615    pub fn output_file_size(&self) -> u64 {
616        self.files_to_add.iter().map(|f| f.file_size).sum()
617    }
618}
619
620/// Compactor is the trait that defines the compaction logic.
621#[async_trait::async_trait]
622pub trait Compactor: Send + Sync + 'static {
623    /// Merge SST files for a region.
624    async fn merge_ssts(
625        &self,
626        compaction_region: &CompactionRegion,
627        picker_output: PickerOutput,
628    ) -> Result<MergeOutput>;
629
630    /// Update the manifest after merging SST files.
631    async fn update_manifest(
632        &self,
633        compaction_region: &CompactionRegion,
634        merge_output: MergeOutput,
635    ) -> Result<(RegionEdit, ManifestVersion)>;
636}
637
638/// Trait for merging a single compaction output into SST files.
639///
640/// This is extracted from `DefaultCompactor` to allow injecting mock
641/// implementations in tests.
642#[async_trait::async_trait]
643pub trait SstMerger: Send + Sync + 'static {
644    /// Merges an output, observing cancellation at safe boundaries and draining
645    /// in-flight writers before returning.
646    async fn merge_single_output(
647        &self,
648        context: CompactionContext,
649        output: CompactionOutput,
650        write_opts: WriteOptions,
651        cancellation: CancellationToken,
652    ) -> Result<(Vec<FileMeta>, Vec<SstInfo>)>;
653}
654
655/// The production [`SstMerger`] that reads, merges, and writes SST files.
656#[derive(Clone)]
657pub struct DefaultSstMerger;
658
659/// File-level sequence metadata is independent of physical row encoding.
660struct OutputSequenceMetadata {
661    file_sequence: Option<NonZeroU64>,
662    exact_sequence_trusted: bool,
663}
664
665/// Compaction does not admit new data, so it inherits the input sequence bounds
666/// without allocating a new admission marker. Retaining physical row sequences
667/// does not by itself restore exact-read capability for untrusted inputs.
668fn output_sequence_metadata(
669    context: &CompactionContext,
670    inputs: &[FileHandle],
671) -> OutputSequenceMetadata {
672    let exact_sequence_trusted = context.region_options.preserve_row_sequence
673        && inputs
674            .iter()
675            .all(|f| f.is_effective_target_sequence_trusted(context.region_id));
676    OutputSequenceMetadata {
677        file_sequence: known_max_input_sequence(inputs),
678        exact_sequence_trusted,
679    }
680}
681
682/// Computes the maximum target-domain sequence bound of the output of merging
683/// `inputs`.
684fn known_max_input_sequence(inputs: &[FileHandle]) -> Option<NonZeroU64> {
685    crate::sst::file::known_max_input_sequence(inputs.iter().map(FileHandle::meta_ref))
686}
687
688/// Whole-input summaries require a complete output without file rollover.
689fn can_reuse_output_inputs(output: &CompactionOutput, has_rollover: bool) -> bool {
690    !has_rollover && output.output_time_range.is_none()
691}
692
693/// Whole-file summaries are usable only when reading needs no partition filtering.
694fn output_matches_partition(
695    output: &CompactionOutput,
696    partition_expr: Option<&PartitionExpr>,
697) -> bool {
698    partition_expr.is_none()
699        || output
700            .inputs
701            .iter()
702            .all(|input| input.meta_ref().partition_expr.as_deref() == partition_expr)
703}
704
705fn reusable_index_inputs(
706    outputs: &[CompactionOutput],
707    has_rollover: bool,
708) -> impl Iterator<Item = &FileHandle> {
709    outputs
710        .iter()
711        .filter(move |output| can_reuse_output_inputs(output, has_rollover))
712        .flat_map(|output| output.inputs.iter())
713}
714
715fn validate_region_compaction_output(region_id: RegionId, output: &CompactionOutput) -> Result<()> {
716    ensure!(
717        output.output_level < file::LEVEL_SHARED
718            && output
719                .inputs
720                .iter()
721                .all(|file| file.level() < file::LEVEL_SHARED),
722        error::InvalidRequestSnafu {
723            region_id,
724            reason: "Region compaction cannot consume or produce shared SSTs",
725        }
726    );
727    Ok(())
728}
729
730#[async_trait::async_trait]
731impl SstMerger for DefaultSstMerger {
732    async fn merge_single_output(
733        &self,
734        context: CompactionContext,
735        output: CompactionOutput,
736        write_opts: WriteOptions,
737        cancellation: CancellationToken,
738    ) -> Result<(Vec<FileMeta>, Vec<SstInfo>)> {
739        let uncommitted = UncommittedSsts::new(
740            context.region_id,
741            context.access_layer.clone(),
742            Some(context.cache_manager.clone()),
743        );
744        let result = self
745            .merge_output(context, output, write_opts, &uncommitted, cancellation)
746            .await;
747        if result.is_err() {
748            uncommitted.cleanup().await;
749        } else {
750            // Successful outputs are transferred to the caller for publication.
751            uncommitted.disarm_cleanup();
752        }
753        match result {
754            Err(error::Error::SstWriteCancelled { .. }) => error::CompactionCancelledSnafu.fail(),
755            result => result,
756        }
757    }
758}
759
760impl DefaultSstMerger {
761    async fn merge_output(
762        &self,
763        context: CompactionContext,
764        output: CompactionOutput,
765        write_opts: WriteOptions,
766        uncommitted: &UncommittedSsts,
767        cancellation: CancellationToken,
768    ) -> Result<(Vec<FileMeta>, Vec<SstInfo>)> {
769        let region_id = context.region_id;
770        validate_region_compaction_output(region_id, &output)?;
771        let index_options = context.version_options.index_options.clone();
772        let append_mode = context.version_options.append_mode;
773        let merge_mode = context.version_options.merge_mode();
774        let flat_format = context
775            .region_options
776            .sst_format
777            .map(|format| format == FormatType::Flat)
778            .unwrap_or(context.engine_config.default_flat_format);
779
780        let index_config = context.engine_config.index.clone();
781        let inverted_index_config = context.engine_config.inverted_index.clone();
782        let fulltext_index_config = context.engine_config.fulltext_index.clone();
783        let bloom_filter_index_config = context.engine_config.bloom_filter_index.clone();
784
785        let input_file_names = output
786            .inputs
787            .iter()
788            .map(|f| f.file_id().to_string())
789            .join(",");
790        let sequence_metadata = output_sequence_metadata(&context, &output.inputs);
791        let builder = CompactionSstReaderBuilder {
792            metadata: context.region_metadata.clone(),
793            sst_layer: context.access_layer.clone(),
794            cache: context.cache_manager.clone(),
795            inputs: &output.inputs,
796            append_mode,
797            filter_deleted: output.filter_deleted,
798            time_range: output.output_time_range,
799            merge_mode,
800            read_parallelism: write_opts.encode_parallelism,
801        };
802        // Matching file scopes need no additional region filtering. Rollover and
803        // time slicing still require output-scoped accumulation.
804        let partition_expr = match context.region_metadata.partition_expr.as_deref() {
805            None | Some("") => None,
806            Some(expr) => {
807                PartitionExpr::from_json_str(expr).with_context(|_| InvalidPartitionExprSnafu {
808                    expr: expr.to_string(),
809                })?
810            }
811        };
812        let can_merge_inputs = can_reuse_output_inputs(&output, write_opts.max_file_size.is_some())
813            && output_matches_partition(&output, partition_expr.as_ref())
814            && context
815                .existing_index_inputs
816                .as_ref()
817                .is_some_and(|existing| {
818                    output
819                        .inputs
820                        .iter()
821                        .all(|input| existing.contains(&input.file_id()))
822                });
823        let index_build_inputs = Some(IndexBuildInputs {
824            output_rows: None,
825            plan: context.index_plan.clone(),
826            memory_limit: None,
827            inputs: if context.index_plan.needs_input_reuse() {
828                output.inputs.clone().into()
829            } else {
830                Arc::from([])
831            },
832            input_puffin_manager: context
833                .access_layer
834                .build_puffin_manager()
835                .with_puffin_metadata_cache(context.cache_manager.puffin_metadata_cache().cloned()),
836            can_merge_inputs,
837        });
838        let source = tokio::select! {
839            biased;
840            _ = cancellation.cancelled() => return error::CompactionCancelledSnafu.fail(),
841            source = builder.build_flat_sst_reader() => source?,
842        };
843        let source = spawn_merge(source);
844
845        let mut metrics = Metrics::new(WriteType::Compaction);
846        let region_metadata = context.region_metadata.clone();
847        let sst_infos = context
848            .access_layer
849            .write_sst_with_context(
850                SstWriteRequest {
851                    index_build_inputs,
852                    op_type: OperationType::Compact,
853                    metadata: region_metadata.clone(),
854                    source,
855                    cache_manager: context.cache_manager.clone(),
856                    // Readers resolve file overrides before merge/dedup. Replacing
857                    // their effective sequences here could promote old rows above
858                    // versions in SSTs that were not part of this merge.
859                    max_sequence: None,
860                    sst_write_format: if flat_format {
861                        FormatType::Flat
862                    } else {
863                        FormatType::PrimaryKey
864                    },
865                    preserve_row_sequence: sequence_metadata.exact_sequence_trusted,
866                    index_options,
867                    index_config,
868                    inverted_index_config,
869                    fulltext_index_config,
870                    bloom_filter_index_config,
871                },
872                &write_opts,
873                &mut metrics,
874                SstWriteContext {
875                    guard: Some(Arc::new(uncommitted.clone())),
876                    cancellation: Some(cancellation),
877                    ..Default::default()
878                },
879            )
880            .await?;
881        let output_files = sst_infos
882            .iter()
883            .map(|sst_info| {
884                let pk_range = sst_info
885                    .file_metadata
886                    .as_ref()
887                    .and_then(|meta| extract_primary_key_range(meta, &region_metadata));
888                let (primary_key_min, primary_key_max) = match pk_range {
889                    Some((min, max)) => (Some(min), Some(max)),
890                    None => (None, None),
891                };
892
893                Ok(FileMeta {
894                    region_id,
895                    file_id: sst_info.file_id,
896                    time_range: sst_info.time_range,
897                    level: output.output_level,
898                    file_size: sst_info.file_size,
899                    max_row_group_uncompressed_size: sst_info.max_row_group_uncompressed_size,
900                    available_indexes: sst_info.index_metadata.build_available_indexes(),
901                    indexes: sst_info.index_metadata.build_indexes()?,
902                    index_file_size: sst_info.index_metadata.file_size,
903                    index_version: 0,
904                    num_rows: sst_info.num_rows as u64,
905                    num_row_groups: sst_info.num_row_groups,
906                    sequence: sequence_metadata.file_sequence,
907                    partition_expr: partition_expr.clone().map(Into::into),
908                    num_series: sst_info.num_series,
909                    primary_key_min,
910                    primary_key_max,
911                    preserve_row_sequence: sequence_metadata.exact_sequence_trusted,
912                })
913            })
914            .collect::<Result<Vec<_>>>()?;
915        let output_file_names = output_files.iter().map(|f| f.file_id.to_string()).join(",");
916        info!(
917            "Region {} compaction inputs: [{}], outputs: [{}], flat_format: {}, metrics: {:?}",
918            region_id, input_file_names, output_file_names, flat_format, metrics
919        );
920        metrics.observe();
921        Ok((output_files, sst_infos.into_iter().collect()))
922    }
923}
924
925/// DefaultCompactor is the default implementation of Compactor.
926///
927/// It is parameterized by an [`SstMerger`] to allow injecting mock
928/// implementations in tests.
929pub struct DefaultCompactor<M = DefaultSstMerger> {
930    merger: M,
931    cancel_token: CancellationToken,
932    uncommitted: Option<UncommittedSsts>,
933}
934
935#[cfg(test)]
936impl<M: SstMerger> DefaultCompactor<M> {
937    pub fn with_merger(merger: M) -> Self {
938        Self {
939            merger,
940            cancel_token: CancellationToken::new(),
941            uncommitted: None,
942        }
943    }
944}
945
946impl DefaultCompactor {
947    /// Creates a new `DefaultCompactor` with the given cancellation token and no
948    /// uncommitted SSTs tracking.
949    ///
950    /// This is the public entry point for external crates that want a
951    /// cancellable compactor without opting into uncommitted-SST tracking.
952    ///
953    /// Cancellation stops new output batches and interrupts active outputs at
954    /// batch and upload-chunk boundaries. Successful complete outputs remain in
955    /// the returned [`MergeOutput`]; incomplete outputs are cleaned up.
956    pub fn new_with_cancel_token(cancel_token: CancellationToken) -> Self {
957        Self {
958            merger: DefaultSstMerger,
959            cancel_token,
960            uncommitted: None,
961        }
962    }
963
964    pub(crate) fn with_cancel_token(
965        cancel_token: CancellationToken,
966        uncommitted: UncommittedSsts,
967    ) -> Self {
968        Self {
969            merger: DefaultSstMerger,
970            cancel_token,
971            uncommitted: Some(uncommitted),
972        }
973    }
974}
975
976impl<M: SstMerger> DefaultCompactor<M> {
977    /// Merges a complete atomic unit. No partial input replacement is returned.
978    pub(crate) async fn merge_unit(
979        &self,
980        context: &CompactionContext,
981        unit: &CompactionUnit,
982    ) -> Result<MergeOutput> {
983        context.warn_missing_index_handlers(unit.inputs.iter());
984        let mut context = context.clone();
985        context
986            .prepare_index_inputs(
987                reusable_index_inputs(&unit.outputs, unit.max_file_size.is_some()),
988                &self.cancel_token,
989            )
990            .await?;
991        let mut result = MergeOutput {
992            files_to_remove: unit.inputs.iter().map(|f| f.meta_ref().clone()).collect(),
993            compaction_time_window: Some(unit.time_window_size),
994            ..Default::default()
995        };
996        for output in &unit.outputs {
997            if self.cancel_token.is_cancelled() {
998                return error::CompactionCancelledSnafu.fail();
999            }
1000            // The merger observes cancellation and drains its writers before returning.
1001            // Keep awaiting it so cleanup cannot race with a late finalized SST.
1002            let (files, infos) = self
1003                .merger
1004                .merge_single_output(
1005                    context.clone(),
1006                    output.clone(),
1007                    WriteOptions {
1008                        write_buffer_size: context.engine_config.sst_write_buffer_size,
1009                        max_file_size: unit.max_file_size,
1010                        row_group_size: context.region_options.row_group_size(),
1011                        float_field_encoding: context.region_options.float_field_encoding,
1012                        encode_parallelism: context
1013                            .region_options
1014                            .compaction_output_parallelism_or(
1015                                context
1016                                    .engine_config
1017                                    .experimental_compaction_output_parallelism,
1018                            ),
1019                        encode_runtime: EncodeRuntime::Compact,
1020                    },
1021                    self.cancel_token.clone(),
1022                )
1023                .await?;
1024            if let Some(uncommitted) = &self.uncommitted {
1025                uncommitted.track(&infos);
1026            }
1027            result.files_to_add.extend(files);
1028            result.sst_infos.extend(infos);
1029        }
1030        if self.cancel_token.is_cancelled() {
1031            return error::CompactionCancelledSnafu.fail();
1032        }
1033        Ok(result)
1034    }
1035}
1036
1037#[async_trait::async_trait]
1038impl<M: SstMerger> Compactor for DefaultCompactor<M>
1039where
1040    M: Clone,
1041{
1042    async fn merge_ssts(
1043        &self,
1044        compaction_region: &CompactionRegion,
1045        mut picker_output: PickerOutput,
1046    ) -> Result<MergeOutput> {
1047        for output in &picker_output.outputs {
1048            validate_region_compaction_output(compaction_region.region_id, output)?;
1049        }
1050        ensure!(
1051            picker_output
1052                .expired_ssts
1053                .iter()
1054                .all(|file| file.level() < file::LEVEL_SHARED),
1055            error::InvalidRequestSnafu {
1056                region_id: compaction_region.region_id,
1057                reason: "Region compaction cannot expire shared SSTs",
1058            }
1059        );
1060        let internal_parallelism = compaction_region.max_parallelism.max(1);
1061        let compaction_time_window = picker_output.time_window_size;
1062        let region_id = compaction_region.region_id;
1063        let mut context = CompactionContext::try_from(compaction_region)?;
1064        context.warn_missing_index_handlers(
1065            picker_output
1066                .outputs
1067                .iter()
1068                .flat_map(|output| output.inputs.iter()),
1069        );
1070        context
1071            .prepare_index_inputs(
1072                reusable_index_inputs(
1073                    &picker_output.outputs,
1074                    picker_output.max_file_size.is_some(),
1075                ),
1076                &self.cancel_token,
1077            )
1078            .await?;
1079
1080        // Build tasks along with their input file metas so we can track which
1081        // inputs correspond to each task.
1082        let mut tasks: Vec<(Vec<FileMeta>, _)> = Vec::with_capacity(picker_output.outputs.len());
1083
1084        for output in picker_output.outputs.drain(..) {
1085            let inputs_to_remove: Vec<_> =
1086                output.inputs.iter().map(|f| f.meta_ref().clone()).collect();
1087            let write_opts = WriteOptions {
1088                write_buffer_size: compaction_region.engine_config.sst_write_buffer_size,
1089                max_file_size: picker_output.max_file_size,
1090                row_group_size: compaction_region.region_options.row_group_size(),
1091                float_field_encoding: compaction_region.region_options.float_field_encoding,
1092                encode_parallelism: compaction_region
1093                    .region_options
1094                    .compaction_output_parallelism_or(
1095                        compaction_region
1096                            .engine_config
1097                            .experimental_compaction_output_parallelism,
1098                    ),
1099                encode_runtime: EncodeRuntime::Compact,
1100            };
1101            let merger = self.merger.clone();
1102            let context = context.clone();
1103            let uncommitted = self.uncommitted.clone();
1104            let cancellation = self.cancel_token.clone();
1105            let fut = async move {
1106                let result = merger
1107                    .merge_single_output(context, output, write_opts, cancellation)
1108                    .await;
1109                if let (Some(uncommitted), Ok((_, infos))) = (&uncommitted, &result) {
1110                    uncommitted.track(infos);
1111                }
1112                result
1113            };
1114            tasks.push((inputs_to_remove, fut));
1115        }
1116
1117        let hook: Option<RegionHookRef> = compaction_region.plugins.get();
1118        let mut output_files = Vec::with_capacity(tasks.len());
1119        let mut all_sst_infos: Vec<SstInfo> = Vec::new();
1120        let mut compacted_inputs = Vec::with_capacity(
1121            tasks.iter().map(|(inputs, _)| inputs.len()).sum::<usize>()
1122                + picker_output.expired_ssts.len(),
1123        );
1124
1125        while !tasks.is_empty() && !self.cancel_token.is_cancelled() {
1126            let mut chunk: Vec<(Vec<FileMeta>, _)> = Vec::with_capacity(internal_parallelism);
1127            for _ in 0..internal_parallelism {
1128                if let Some(task) = tasks.pop() {
1129                    chunk.push(task);
1130                }
1131            }
1132            let mut spawned: Vec<_> = chunk
1133                .into_iter()
1134                .map(|(inputs, fut)| {
1135                    let handle = common_runtime::spawn_compact(fut);
1136                    (inputs, handle)
1137                })
1138                .collect();
1139
1140            // Each merger cancels cooperatively and owns its incomplete outputs.
1141            // Join every sibling before returning so writers and cleanup cannot race.
1142            let mut join_error = None;
1143            while let Some((inputs, handle)) = spawned.pop() {
1144                match handle.await {
1145                    Ok(Ok((files, infos))) => {
1146                        output_files.extend(files);
1147                        if hook.is_some() {
1148                            all_sst_infos.extend(infos);
1149                        }
1150                        compacted_inputs.extend(inputs);
1151                    }
1152                    Ok(Err(error::Error::CompactionCancelled { .. })) => {}
1153                    Ok(Err(e)) => {
1154                        warn!(
1155                            e; "Failed to merge compaction output for region: {}, inputs: [{}]",
1156                            region_id,
1157                            inputs.iter().map(|f| f.file_id.to_string()).join(",")
1158                        );
1159                    }
1160                    Err(e) => {
1161                        warn!(
1162                            "Region {} compaction task join error for inputs: [{}]: {}",
1163                            region_id,
1164                            inputs.iter().map(|f| f.file_id.to_string()).join(","),
1165                            e
1166                        );
1167                        // Drain siblings before propagating the first join error.
1168                        join_error.get_or_insert(e);
1169                    }
1170                }
1171            }
1172            if let Some(e) = join_error {
1173                return Err(e).context(error::JoinSnafu);
1174            }
1175
1176            if self.cancel_token.is_cancelled() {
1177                info!("Compaction merge cancelled for region: {}", region_id);
1178                break;
1179            }
1180        }
1181
1182        // Include expired SSTs in removals — these don't depend on merge success.
1183        compacted_inputs.extend(
1184            picker_output
1185                .expired_ssts
1186                .iter()
1187                .map(|f| f.meta_ref().clone()),
1188        );
1189
1190        Ok(MergeOutput {
1191            files_to_add: output_files,
1192            files_to_remove: compacted_inputs,
1193            compaction_time_window: Some(compaction_time_window),
1194            sst_infos: all_sst_infos,
1195        })
1196    }
1197
1198    async fn update_manifest(
1199        &self,
1200        compaction_region: &CompactionRegion,
1201        merge_output: MergeOutput,
1202    ) -> Result<(RegionEdit, ManifestVersion)> {
1203        CompactionContext::try_from(compaction_region)?
1204            .update_manifest(merge_output)
1205            .await
1206    }
1207}
1208
1209#[cfg(test)]
1210mod tests {
1211    use std::sync::atomic::{AtomicUsize, Ordering};
1212    use std::sync::{Arc, Mutex, Weak};
1213    use std::time::Duration;
1214
1215    use common_error::ext::BoxedError;
1216    use common_time::Timestamp;
1217    use common_time::range::TimestampRange;
1218    use datatypes::arrow::record_batch::RecordBatch;
1219    use object_store::ObjectStore;
1220    use object_store::layers::mock::{self, MockLayerBuilder};
1221    use object_store::services::Memory;
1222    use parquet::arrow::ArrowWriter;
1223    use store_api::storage::{FileId, RegionId};
1224    use tokio::sync::{Notify, mpsc, oneshot};
1225    use tokio::time::timeout;
1226
1227    use super::{DefaultCompactor, *};
1228    use crate::compaction::memory_manager::new_compaction_memory_manager;
1229    use crate::compaction::picker::PickerOutput;
1230    use crate::error::Result;
1231    use crate::sst::file::FileHandle;
1232    use crate::sst::file_purger::NoopFilePurger;
1233    use crate::sst::index::handler::{
1234        BuildContext, IndexCreator, IndexKindHandler, IndexKindProvider, PlanEntry, PlannedIndex,
1235    };
1236    use crate::sst::index::kind::{ExtensionIndexKind, IndexKind};
1237    use crate::test_util::sst_util::new_record_batch_by_range;
1238
1239    fn dummy_file_meta() -> FileMeta {
1240        FileMeta {
1241            region_id: RegionId::new(1, 1),
1242            file_id: FileId::random(),
1243            file_size: 100,
1244            ..Default::default()
1245        }
1246    }
1247
1248    fn new_file_handle(meta: FileMeta) -> FileHandle {
1249        FileHandle::new(meta, Arc::new(NoopFilePurger))
1250    }
1251
1252    struct PendingCompactionReader {
1253        started: Arc<Notify>,
1254    }
1255
1256    impl mock::oio::Read for PendingCompactionReader {
1257        async fn open(
1258            &self,
1259            _: mock::BytesRange,
1260        ) -> object_store::Result<(mock::RpRead, Box<dyn mock::oio::ReadStreamDyn>)> {
1261            self.started.notify_one();
1262            std::future::pending().await
1263        }
1264
1265        async fn read(
1266            &self,
1267            _: mock::BytesRange,
1268        ) -> object_store::Result<(mock::RpRead, object_store::Buffer)> {
1269            self.started.notify_one();
1270            std::future::pending().await
1271        }
1272    }
1273
1274    #[rstest::rstest]
1275    #[case::unit(true)]
1276    #[case::outputs(false)]
1277    #[tokio::test]
1278    async fn test_default_merger_observes_compactor_cancellation(#[case] merge_unit: bool) {
1279        let mut region = new_test_compaction_region().await;
1280        let started = Arc::new(Notify::new());
1281        let signal = started.clone();
1282        let layer = MockLayerBuilder::default()
1283            .reader_factory(Arc::new(move |_, _, _| {
1284                Box::new(PendingCompactionReader {
1285                    started: signal.clone(),
1286                })
1287            }))
1288            .build()
1289            .unwrap();
1290        let store = ObjectStore::new(Memory::default()).unwrap().layer(layer);
1291        let access = &region.access_layer;
1292        region.access_layer = Arc::new(AccessLayer::new(
1293            access.table_dir(),
1294            access.path_type(),
1295            store.clone(),
1296            access.puffin_manager_factory().clone(),
1297            access.intermediate_manager().clone(),
1298        ));
1299        let input = new_file_handle(dummy_file_meta());
1300        store
1301            .write(
1302                &input.file_path(
1303                    region.access_layer.table_dir(),
1304                    region.access_layer.path_type(),
1305                ),
1306                vec![0; input.meta_ref().file_size as usize],
1307            )
1308            .await
1309            .unwrap();
1310        let picker_output = PickerOutput {
1311            outputs: vec![CompactionOutput {
1312                output_level: 1,
1313                inputs: vec![input],
1314                filter_deleted: false,
1315                output_time_range: None,
1316            }],
1317            ..Default::default()
1318        };
1319        let compactor = DefaultCompactor::with_merger(DefaultSstMerger);
1320        let context = CompactionContext::try_from(&region).unwrap();
1321        let mut merge = Box::pin(async {
1322            if merge_unit {
1323                let unit = CompactionUnit::from_picker(picker_output)
1324                    .unwrap()
1325                    .pop()
1326                    .unwrap();
1327                compactor.merge_unit(&context, &unit).await
1328            } else {
1329                compactor.merge_ssts(&region, picker_output).await
1330            }
1331        });
1332        tokio::select! {
1333            _ = started.notified() => {},
1334            result = &mut merge => panic!("merge returned before cancellation: {result:?}"),
1335            _ = tokio::time::sleep(Duration::from_secs(10)) => panic!("merge did not reach the reader"),
1336        }
1337        compactor.cancel_token.cancel();
1338        let result = timeout(Duration::from_secs(10), merge).await.unwrap();
1339        if merge_unit {
1340            assert!(matches!(
1341                result,
1342                Err(error::Error::CompactionCancelled { .. })
1343            ));
1344        } else {
1345            let result = result.unwrap();
1346            assert!(result.files_to_add.is_empty());
1347            assert!(result.files_to_remove.is_empty());
1348        }
1349    }
1350
1351    #[derive(Debug)]
1352    struct InputReusePlan;
1353
1354    impl IndexKindHandler for InputReusePlan {
1355        fn validate(&self, _context: &PlanContext<'_>) -> std::result::Result<(), BoxedError> {
1356            Ok(())
1357        }
1358
1359        fn kinds(&self) -> &[IndexKind] {
1360            &[IndexKind::Extension(ExtensionIndexKind::Hll)]
1361        }
1362
1363        fn plan(
1364            &self,
1365            _context: &PlanContext<'_>,
1366        ) -> std::result::Result<Option<Arc<dyn PlannedIndex>>, BoxedError> {
1367            Ok(Some(Arc::new(Self)))
1368        }
1369    }
1370
1371    #[async_trait::async_trait]
1372    impl PlannedIndex for InputReusePlan {
1373        fn kinds(&self) -> &[IndexKind] {
1374            IndexKindHandler::kinds(self)
1375        }
1376
1377        fn entries(&self) -> &[PlanEntry] {
1378            &[]
1379        }
1380
1381        fn needs_input_reuse(&self) -> bool {
1382            true
1383        }
1384
1385        async fn build(
1386            &self,
1387            _context: &BuildContext<'_>,
1388        ) -> std::result::Result<Option<Box<dyn IndexCreator>>, BoxedError> {
1389            Ok(None)
1390        }
1391
1392        fn is_current(&self, _file: &FileMeta, _context: &PlanContext<'_>) -> bool {
1393            true
1394        }
1395    }
1396
1397    impl IndexKindProvider for InputReusePlan {
1398        fn handlers(&self) -> Vec<Arc<dyn IndexKindHandler>> {
1399            vec![Arc::new(Self)]
1400        }
1401    }
1402
1403    #[rstest::rstest]
1404    #[case::unit(true)]
1405    #[case::outputs(false)]
1406    #[tokio::test]
1407    async fn test_index_input_probes_observe_cancellation(
1408        #[case] merge_unit: bool,
1409        #[values(false, true)] cancelled_before_start: bool,
1410    ) {
1411        let mut region = new_test_compaction_region().await;
1412        region
1413            .plugins
1414            .insert::<IndexKindProviderRef>(Arc::new(InputReusePlan));
1415        let started = Arc::new(Notify::new());
1416        let probes = Arc::new(AtomicUsize::new(0));
1417        let signal = started.clone();
1418        let observed = probes.clone();
1419        let layer = MockLayerBuilder::default()
1420            .stat_interceptor(Arc::new(move |_| {
1421                let signal = signal.clone();
1422                let observed = observed.clone();
1423                Box::pin(async move {
1424                    observed.fetch_add(1, Ordering::Relaxed);
1425                    signal.notify_one();
1426                    std::future::pending().await
1427                })
1428            }))
1429            .build()
1430            .unwrap();
1431        let store = ObjectStore::new(Memory::default()).unwrap().layer(layer);
1432        let access = &region.access_layer;
1433        region.access_layer = Arc::new(AccessLayer::new(
1434            access.table_dir(),
1435            access.path_type(),
1436            store,
1437            access.puffin_manager_factory().clone(),
1438            access.intermediate_manager().clone(),
1439        ));
1440        let picker_output = PickerOutput {
1441            outputs: vec![CompactionOutput {
1442                output_level: 1,
1443                inputs: vec![new_file_handle(dummy_file_meta())],
1444                filter_deleted: false,
1445                output_time_range: None,
1446            }],
1447            ..Default::default()
1448        };
1449        let compactor = DefaultCompactor::with_merger(DefaultSstMerger);
1450        let context = CompactionContext::try_from(&region).unwrap();
1451        let mut merge = Box::pin(async {
1452            if merge_unit {
1453                let unit = CompactionUnit::from_picker(picker_output)
1454                    .unwrap()
1455                    .pop()
1456                    .unwrap();
1457                compactor.merge_unit(&context, &unit).await
1458            } else {
1459                compactor.merge_ssts(&region, picker_output).await
1460            }
1461        });
1462        if !cancelled_before_start {
1463            tokio::select! {
1464                _ = started.notified() => {},
1465                result = &mut merge => panic!("merge returned before cancellation: {result:?}"),
1466                _ = tokio::time::sleep(Duration::from_secs(10)) => panic!("merge did not reach input probes"),
1467            }
1468        }
1469        compactor.cancel_token.cancel();
1470        let result = timeout(Duration::from_secs(10), merge).await.unwrap();
1471        assert!(matches!(
1472            result,
1473            Err(error::Error::CompactionCancelled { .. })
1474        ));
1475        assert_eq!(
1476            probes.load(Ordering::Relaxed),
1477            usize::from(!cancelled_before_start)
1478        );
1479        assert!(context.existing_index_inputs.is_none());
1480    }
1481
1482    #[derive(Debug)]
1483    struct DuplicateIndexProvider;
1484
1485    impl IndexKindProvider for DuplicateIndexProvider {
1486        fn handlers(&self) -> Vec<Arc<dyn IndexKindHandler>> {
1487            vec![Arc::new(InputReusePlan), Arc::new(InputReusePlan)]
1488        }
1489    }
1490
1491    #[tokio::test]
1492    async fn test_context_rejects_duplicate_provider_before_merge() {
1493        let region = new_test_compaction_region().await;
1494        region
1495            .plugins
1496            .insert::<IndexKindProviderRef>(Arc::new(DuplicateIndexProvider));
1497        assert!(CompactionContext::try_from(&region).is_err());
1498    }
1499
1500    #[test]
1501    fn test_reusable_inputs_exclude_sliced_outputs_and_rollover() {
1502        let whole = new_file_handle(dummy_file_meta());
1503        let sliced = new_file_handle(dummy_file_meta());
1504        let outputs = vec![
1505            CompactionOutput {
1506                output_level: 1,
1507                inputs: vec![whole.clone()],
1508                filter_deleted: true,
1509                output_time_range: None,
1510            },
1511            CompactionOutput {
1512                output_level: 1,
1513                inputs: vec![sliced],
1514                filter_deleted: false,
1515                output_time_range: TimestampRange::new(
1516                    Timestamp::new_second(0),
1517                    Timestamp::new_second(1),
1518                ),
1519            },
1520        ];
1521        assert_eq!(
1522            reusable_index_inputs(&outputs, false)
1523                .map(FileHandle::file_id)
1524                .collect::<Vec<_>>(),
1525            vec![whole.file_id()],
1526        );
1527        assert_eq!(reusable_index_inputs(&outputs, true).count(), 0);
1528    }
1529
1530    #[test]
1531    fn test_reuse_requires_all_input_partition_scopes_to_match() {
1532        use datatypes::value::Value;
1533        use partition::expr::{RestrictedOp, col};
1534
1535        let scope = PartitionExpr::new(col("tag_0"), RestrictedOp::GtEq, Value::UInt32(10).into());
1536        let other = PartitionExpr::new(col("tag_0"), RestrictedOp::GtEq, Value::UInt32(20).into());
1537        for (scopes, expected) in [
1538            (vec![Some(scope.clone()), Some(scope.clone())], true),
1539            (vec![Some(scope.clone()), None], false),
1540            (vec![Some(scope.clone()), Some(other)], false),
1541        ] {
1542            let output = CompactionOutput {
1543                output_level: 1,
1544                inputs: scopes
1545                    .into_iter()
1546                    .map(|partition_expr| {
1547                        let mut meta = dummy_file_meta();
1548                        meta.partition_expr = partition_expr.map(Into::into);
1549                        new_file_handle(meta)
1550                    })
1551                    .collect(),
1552                filter_deleted: true,
1553                output_time_range: None,
1554            };
1555            assert_eq!(output_matches_partition(&output, Some(&scope)), expected);
1556            assert!(output_matches_partition(&output, None));
1557        }
1558    }
1559
1560    #[tokio::test]
1561    async fn test_index_input_preparation_tracks_physical_files() {
1562        let mut region = new_test_compaction_region().await;
1563        Arc::make_mut(&mut region.region_metadata).column_metadatas[0]
1564            .column_schema
1565            .set_inverted_index(true);
1566        let mut context = CompactionContext::try_from(&region).unwrap();
1567        assert!(context.existing_index_inputs.is_none());
1568        // Builtin plans do not probe physical inputs solely for optional reuse.
1569        context
1570            .prepare_index_inputs(std::iter::empty(), &CancellationToken::new())
1571            .await
1572            .unwrap();
1573        assert!(context.existing_index_inputs.is_none());
1574        let mut registry =
1575            IndexRegistry::new(Default::default(), Default::default(), Default::default());
1576        registry.register(Arc::new(InputReusePlan)).unwrap();
1577        context.index_plan = Arc::new(registry.plan(&PlanContext {
1578            metadata: &context.region_metadata,
1579            index_options: &context.version_options.index_options,
1580            build_type: IndexBuildType::Compact,
1581            existing_indexes: &[],
1582        }));
1583        let present = new_file_handle(dummy_file_meta());
1584        let missing = new_file_handle(dummy_file_meta());
1585        let path = crate::sst::location::sst_file_path(
1586            context.access_layer.table_dir(),
1587            present.file_id(),
1588            context.access_layer.path_type(),
1589        );
1590        context
1591            .access_layer
1592            .object_store()
1593            .write(&path, vec![1])
1594            .await
1595            .unwrap();
1596        // Duplicate references are checked as one physical input. Only successfully
1597        // probed files can contribute imported summaries to an output.
1598        context
1599            .prepare_index_inputs(
1600                [&present, &missing, &present].into_iter(),
1601                &CancellationToken::new(),
1602            )
1603            .await
1604            .unwrap();
1605        assert_eq!(
1606            context.existing_index_inputs.as_deref(),
1607            Some(&HashSet::from([present.file_id()]))
1608        );
1609        let prepared = context.clone();
1610        assert!(Arc::ptr_eq(
1611            context.existing_index_inputs.as_ref().unwrap(),
1612            prepared.existing_index_inputs.as_ref().unwrap()
1613        ));
1614        assert!(Arc::ptr_eq(&context.index_plan, &prepared.index_plan));
1615    }
1616
1617    #[test]
1618    fn test_effective_target_trust_and_max_sequence() {
1619        let target = RegionId::new(1, 1);
1620        let local_trusted = new_file_handle(FileMeta {
1621            region_id: target,
1622            sequence: NonZeroU64::new(3),
1623            preserve_row_sequence: true,
1624            ..dummy_file_meta()
1625        });
1626        let foreign_untrusted_marker = new_file_handle(FileMeta {
1627            region_id: RegionId::new(1, 2),
1628            sequence: NonZeroU64::new(9),
1629            preserve_row_sequence: false,
1630            ..dummy_file_meta()
1631        });
1632        let local_untrusted = new_file_handle(FileMeta {
1633            region_id: target,
1634            sequence: NonZeroU64::new(11),
1635            preserve_row_sequence: false,
1636            ..dummy_file_meta()
1637        });
1638        assert!(local_trusted.is_effective_target_sequence_trusted(target));
1639        assert!(foreign_untrusted_marker.is_effective_target_sequence_trusted(target));
1640        assert!(!local_untrusted.is_effective_target_sequence_trusted(target));
1641        assert_eq!(
1642            NonZeroU64::new(9),
1643            known_max_input_sequence(&[local_trusted, foreign_untrusted_marker])
1644        );
1645    }
1646
1647    #[test]
1648    fn test_known_max_input_sequence() {
1649        let meta_with = |sequence| FileMeta {
1650            sequence,
1651            ..dummy_file_meta()
1652        };
1653
1654        let inputs = vec![
1655            new_file_handle(meta_with(NonZeroU64::new(3))),
1656            new_file_handle(meta_with(NonZeroU64::new(9))),
1657            new_file_handle(meta_with(NonZeroU64::new(5))),
1658        ];
1659        assert_eq!(NonZeroU64::new(9), known_max_input_sequence(&inputs));
1660
1661        let inputs = vec![
1662            new_file_handle(meta_with(NonZeroU64::new(9))),
1663            new_file_handle(meta_with(None)),
1664        ];
1665        assert_eq!(None, known_max_input_sequence(&inputs));
1666
1667        assert_eq!(None, known_max_input_sequence(&[]));
1668    }
1669
1670    #[tokio::test]
1671    async fn test_output_sequence_metadata_preserves_trust_and_unknown_bounds() {
1672        let mut region = new_test_compaction_region().await;
1673        let local = region.region_id;
1674        let foreign = RegionId::new(1, 2);
1675        let file = |region_id, sequence: Option<u64>, preserve_row_sequence| {
1676            new_file_handle(FileMeta {
1677                region_id,
1678                sequence: sequence.and_then(NonZeroU64::new),
1679                preserve_row_sequence,
1680                ..dummy_file_meta()
1681            })
1682        };
1683        // Bounds are independent of row trust: known, mixed trust, unknown in
1684        // either sequence domain, empty inputs, and the largest possible bound.
1685        let cases = [
1686            (
1687                vec![file(local, Some(3), true), file(foreign, Some(9), false)],
1688                Some(9),
1689                true,
1690            ),
1691            (
1692                vec![file(local, Some(3), true), file(local, Some(6), false)],
1693                Some(6),
1694                false,
1695            ),
1696            (
1697                vec![file(foreign, Some(9), false), file(foreign, Some(11), true)],
1698                Some(11),
1699                true,
1700            ),
1701            (
1702                vec![file(local, Some(3), true), file(local, None, true)],
1703                None,
1704                true,
1705            ),
1706            (
1707                vec![file(local, None, false), file(local, Some(6), true)],
1708                None,
1709                false,
1710            ),
1711            (
1712                vec![file(local, Some(3), true), file(foreign, None, true)],
1713                None,
1714                false,
1715            ),
1716            (vec![], None, true),
1717            (
1718                vec![file(local, Some(u64::MAX), false)],
1719                Some(u64::MAX),
1720                false,
1721            ),
1722        ];
1723        for committed_sequence in [100, 101] {
1724            region
1725                .manifest_ctx
1726                .manifest_manager
1727                .write()
1728                .await
1729                .update(
1730                    RegionMetaActionList::with_action(RegionMetaAction::Edit(RegionEdit {
1731                        committed_sequence: Some(committed_sequence),
1732                        files_to_add: vec![],
1733                        files_to_remove: vec![],
1734                        timestamp_ms: None,
1735                        compaction_time_window: None,
1736                        flushed_entry_id: None,
1737                        flushed_sequence: None,
1738                        wal_recovery: Default::default(),
1739                    })),
1740                    false,
1741                )
1742                .await
1743                .unwrap();
1744            for preserve in [false, true] {
1745                region.region_options.preserve_row_sequence = preserve;
1746                for (inputs, known_bound, inputs_trusted) in &cases {
1747                    let metadata = output_sequence_metadata(
1748                        &CompactionContext::try_from(&region).unwrap(),
1749                        inputs,
1750                    );
1751                    let trusted = preserve && *inputs_trusted;
1752                    assert_eq!(trusted, metadata.exact_sequence_trusted);
1753                    assert_eq!(
1754                        known_bound.and_then(NonZeroU64::new),
1755                        metadata.file_sequence
1756                    );
1757                }
1758            }
1759        }
1760    }
1761
1762    /// Independent outputs must be safe in either visibility order, including when
1763    /// only one output succeeds. Merely committing both outputs together is not a
1764    /// substitute for preserving version order across their separate merge streams.
1765    #[rstest::rstest]
1766    #[case(true)]
1767    #[case(false)]
1768    #[tokio::test]
1769    async fn test_independent_outputs_preserve_delete_in_every_visibility_state(
1770        #[case] flat_format: bool,
1771        #[values(false, true)] unknown_put_bound: bool,
1772    ) {
1773        use datatypes::arrow::array::AsArray;
1774        use datatypes::arrow::datatypes::TimestampMillisecondType;
1775        use store_api::region_engine::RegionEngine;
1776        use store_api::region_request::RegionRequest;
1777
1778        use crate::compaction::CompactionOutput;
1779        use crate::compaction::compactor::{CompactionRegion, Compactor, DefaultCompactor};
1780        use crate::compaction::picker::PickerOutput;
1781        use crate::compaction::reader::CompactionSstReaderBuilder;
1782        use crate::engine::compaction_test::{delete_and_flush, put_and_flush};
1783        use crate::region::options::MergeMode;
1784        use crate::sst::file::FileHandle;
1785        use crate::sst::file_purger::NoopFilePurger;
1786        use crate::test_util::{CreateRequestBuilder, TestEnv, rows_schema};
1787
1788        let mut env = TestEnv::new().await;
1789        let region_id = RegionId::new(1, 1);
1790        let config = MitoConfig {
1791            default_flat_format: flat_format,
1792            min_compaction_interval: Duration::from_secs(3600),
1793            ..Default::default()
1794        };
1795        let engine = env.create_engine(config).await;
1796        let request = CreateRequestBuilder::new().build();
1797        let columns = rows_schema(&request);
1798        engine
1799            .handle_request(region_id, RegionRequest::Create(request))
1800            .await
1801            .unwrap();
1802        put_and_flush(&engine, region_id, &columns, 0..1).await;
1803        delete_and_flush(&engine, region_id, &columns, 0..1).await;
1804        put_and_flush(&engine, region_id, &columns, 10..11).await;
1805        let region = engine.get_region(region_id).unwrap();
1806        let version = region.version();
1807        let mut files: Vec<_> = version
1808            .ssts
1809            .levels()
1810            .iter()
1811            .flat_map(|level| level.files())
1812            .cloned()
1813            .collect();
1814        assert_eq!(3, files.len());
1815        files.sort_unstable_by_key(|file| file.meta_ref().sequence);
1816        if unknown_put_bound {
1817            // Model a legacy SST whose physical rows are readable but whose
1818            // file-level boundary is unknown. Merging cannot invent that bound.
1819            let mut meta = files[0].meta_ref().clone();
1820            meta.sequence = None;
1821            files[0] = FileHandle::new(meta, Arc::new(NoopFilePurger));
1822        }
1823        let compaction_region = CompactionRegion {
1824            region_id,
1825            region_options: version.options.clone(),
1826            engine_config: Arc::new(MitoConfig {
1827                default_flat_format: flat_format,
1828                ..Default::default()
1829            }),
1830            region_metadata: version.metadata.clone(),
1831            cache_manager: engine.cache_manager(),
1832            access_layer: region.access_layer.clone(),
1833            manifest_ctx: region.manifest_ctx.clone(),
1834            current_version: version.into(),
1835            file_purger: None,
1836            ttl: None,
1837            max_parallelism: 2,
1838            plugins: common_base::Plugins::new(),
1839        };
1840        let puts = vec![files[0].clone(), files[2].clone()];
1841        let deletes = vec![files[1].clone()];
1842        let picker_output = PickerOutput {
1843            outputs: [puts.clone(), deletes.clone()]
1844                .into_iter()
1845                .map(|inputs| CompactionOutput {
1846                    output_level: 1,
1847                    inputs,
1848                    filter_deleted: false,
1849                    output_time_range: None,
1850                })
1851                .collect(),
1852            expired_ssts: vec![],
1853            time_window_size: 3600,
1854            max_file_size: None,
1855        };
1856        let merged = DefaultCompactor::with_merger(DefaultSstMerger)
1857            .merge_ssts(&compaction_region, picker_output)
1858            .await
1859            .unwrap();
1860        assert_eq!(2, merged.files_to_add.len());
1861        let outputs: Vec<_> = merged
1862            .files_to_add
1863            .into_iter()
1864            .map(|meta| FileHandle::new(meta, Arc::new(NoopFilePurger)))
1865            .collect();
1866        let put_output = outputs
1867            .iter()
1868            .find(|file| file.meta_ref().num_rows == 2)
1869            .unwrap();
1870        let delete_output = outputs
1871            .iter()
1872            .find(|file| file.meta_ref().num_rows == 1)
1873            .unwrap();
1874        assert_eq!(
1875            if unknown_put_bound {
1876                None
1877            } else {
1878                NonZeroU64::new(3)
1879            },
1880            put_output.meta_ref().sequence,
1881        );
1882        assert_eq!(NonZeroU64::new(2), delete_output.meta_ref().sequence);
1883        assert!(
1884            outputs
1885                .iter()
1886                .all(|file| !file.meta_ref().preserve_row_sequence)
1887        );
1888
1889        // Cover the original snapshot, each partial success/cancellation state,
1890        // and both completed outputs using real persisted SSTs and merge readers.
1891        for (put_done, delete_done) in [(false, false), (true, false), (false, true), (true, true)]
1892        {
1893            let mut visible = if put_done {
1894                vec![put_output.clone()]
1895            } else {
1896                puts.clone()
1897            };
1898            visible.extend(if delete_done {
1899                vec![delete_output.clone()]
1900            } else {
1901                deletes.clone()
1902            });
1903            let mut reader = CompactionSstReaderBuilder {
1904                metadata: compaction_region.region_metadata.clone(),
1905                sst_layer: region.access_layer.clone(),
1906                cache: engine.cache_manager(),
1907                inputs: &visible,
1908                append_mode: false,
1909                filter_deleted: true,
1910                time_range: None,
1911                merge_mode: MergeMode::LastRow,
1912                read_parallelism: 1,
1913            }
1914            .build_flat_sst_reader()
1915            .await
1916            .unwrap();
1917            let mut timestamps = Vec::new();
1918            while let Some(batch) = reader.next_batch().await.unwrap() {
1919                timestamps.extend(
1920                    batch
1921                        .column_by_name("ts")
1922                        .unwrap()
1923                        .as_primitive::<TimestampMillisecondType>()
1924                        .values()
1925                        .iter()
1926                        .copied(),
1927                );
1928            }
1929            assert_eq!(
1930                vec![10_000],
1931                timestamps,
1932                "put_done={put_done}, delete_done={delete_done}"
1933            );
1934        }
1935    }
1936
1937    #[rstest::rstest]
1938    #[case::primary_key(false)]
1939    #[case::flat(true)]
1940    #[tokio::test]
1941    async fn test_compaction_skips_missing_input(#[case] flat_format: bool) {
1942        use datatypes::arrow::array::AsArray;
1943        use datatypes::arrow::datatypes::TimestampMillisecondType;
1944        use store_api::region_engine::RegionEngine;
1945        use store_api::region_request::RegionRequest;
1946
1947        use crate::engine::compaction_test::put_and_flush;
1948        use crate::test_util::{CreateRequestBuilder, TestEnv, rows_schema};
1949
1950        let mut env = TestEnv::new().await;
1951        let config = MitoConfig {
1952            default_flat_format: flat_format,
1953            min_compaction_interval: Duration::from_secs(3600),
1954            ..Default::default()
1955        };
1956        let engine = env.create_engine(config.clone()).await;
1957        let region_id = RegionId::new(1, 1);
1958        let request = CreateRequestBuilder::new().build();
1959        let columns = rows_schema(&request);
1960        engine
1961            .handle_request(region_id, RegionRequest::Create(request))
1962            .await
1963            .unwrap();
1964        // Nine files cross the eight-footer concurrency limit.
1965        for file in 0..9 {
1966            put_and_flush(&engine, region_id, &columns, file * 2..file * 2 + 2).await;
1967        }
1968        let region = engine.get_region(region_id).unwrap();
1969        let version = region.version();
1970        let mut inputs: Vec<_> = version.ssts.levels()[0].files().cloned().collect();
1971        assert_eq!(9, inputs.len());
1972        inputs.sort_unstable_by_key(|file| file.meta_ref().sequence);
1973        let missing = inputs[4].clone();
1974        let output = CompactionOutput {
1975            output_level: 1,
1976            inputs,
1977            filter_deleted: true,
1978            output_time_range: None,
1979        };
1980        // Delete after selecting the inputs; a fresh cache avoids hiding the missing
1981        // footer behind the metadata populated by flush.
1982        let context = CompactionContext {
1983            region_id,
1984            region_options: version.options.clone(),
1985            version_options: version.options.clone(),
1986            engine_config: Arc::new(config),
1987            region_metadata: version.metadata.clone(),
1988            cache_manager: Arc::new(
1989                CacheManager::builder()
1990                    .sst_meta_cache_size(1024 * 1024)
1991                    .build(),
1992            ),
1993            access_layer: region.access_layer.clone(),
1994            manifest_ctx: region.manifest_ctx.clone(),
1995            plugins: Plugins::new(),
1996            index_plan: Arc::default(),
1997            index_registry: Arc::new(IndexRegistry::new(
1998                Default::default(),
1999                Default::default(),
2000                Default::default(),
2001            )),
2002            existing_index_inputs: None,
2003        };
2004        region
2005            .access_layer
2006            .object_store()
2007            .delete(&missing.file_path(
2008                region.access_layer.table_dir(),
2009                region.access_layer.path_type(),
2010            ))
2011            .await
2012            .unwrap();
2013        let (files, _) = DefaultSstMerger
2014            .merge_single_output(
2015                context,
2016                output,
2017                WriteOptions::default(),
2018                CancellationToken::new(),
2019            )
2020            .await
2021            .unwrap();
2022        assert_eq!(1, files.len());
2023        let outputs: Vec<_> = files.into_iter().map(new_file_handle).collect();
2024        let mut reader = CompactionSstReaderBuilder {
2025            metadata: version.metadata.clone(),
2026            sst_layer: region.access_layer.clone(),
2027            cache: Arc::new(CacheManager::default()),
2028            inputs: &outputs,
2029            append_mode: false,
2030            filter_deleted: true,
2031            time_range: None,
2032            merge_mode: MergeMode::LastRow,
2033            read_parallelism: 1,
2034        }
2035        .build_flat_sst_reader()
2036        .await
2037        .unwrap();
2038        let mut timestamps = Vec::new();
2039        while let Some(batch) = reader.next_batch().await.unwrap() {
2040            timestamps.extend_from_slice(
2041                batch
2042                    .column_by_name("ts")
2043                    .unwrap()
2044                    .as_primitive::<TimestampMillisecondType>()
2045                    .values(),
2046            );
2047        }
2048        let expected: Vec<i64> = (0..18)
2049            .filter(|ts| !(8..10).contains(ts))
2050            .map(|ts| ts * 1000)
2051            .collect();
2052        assert_eq!(expected, timestamps);
2053    }
2054
2055    /// An [`SstMerger`] that returns pre-configured results per call index.
2056    ///
2057    /// Call 0 gets `results[0]`, call 1 gets `results[1]`, etc.
2058    #[derive(Clone)]
2059    struct MockMerger {
2060        results: Arc<Mutex<Vec<Result<Vec<FileMeta>>>>>,
2061        call_idx: Arc<AtomicUsize>,
2062    }
2063
2064    impl MockMerger {
2065        fn new(results: Vec<Result<Vec<FileMeta>>>) -> Self {
2066            Self {
2067                results: Arc::new(Mutex::new(results)),
2068                call_idx: Arc::new(AtomicUsize::new(0)),
2069            }
2070        }
2071    }
2072
2073    #[async_trait::async_trait]
2074    impl SstMerger for MockMerger {
2075        async fn merge_single_output(
2076            &self,
2077            _context: CompactionContext,
2078            _output: CompactionOutput,
2079            _write_opts: WriteOptions,
2080            _cancellation: CancellationToken,
2081        ) -> Result<(Vec<FileMeta>, Vec<SstInfo>)> {
2082            let idx = self.call_idx.fetch_add(1, Ordering::SeqCst);
2083            match self.results.lock().unwrap().get(idx) {
2084                Some(Ok(files)) => Ok((files.clone(), Vec::new())),
2085                Some(Err(_)) => error::InvalidMetaSnafu {
2086                    reason: format!("simulated failure at index {idx}"),
2087                }
2088                .fail(),
2089                None => panic!("MockMerger: no result configured for call index {idx}"),
2090            }
2091        }
2092    }
2093
2094    #[tokio::test]
2095    async fn test_compaction_unit_group_failure_is_atomic() {
2096        let context = CompactionContext::try_from(&new_test_compaction_region().await).unwrap();
2097        let input = new_file_handle(dummy_file_meta());
2098        let unit = CompactionUnit::from_picker(PickerOutput {
2099            outputs: (0..2)
2100                .map(|_| CompactionOutput {
2101                    output_level: 1,
2102                    inputs: vec![input.clone()],
2103                    filter_deleted: false,
2104                    output_time_range: None,
2105                })
2106                .collect(),
2107            ..Default::default()
2108        })
2109        .unwrap()
2110        .pop()
2111        .unwrap();
2112        for fail_second in [false, true] {
2113            let second = if fail_second {
2114                error::InvalidMetaSnafu {
2115                    reason: "second output failed",
2116                }
2117                .fail()
2118            } else {
2119                Ok(vec![dummy_file_meta(), dummy_file_meta()])
2120            };
2121            let compactor =
2122                DefaultCompactor::with_merger(MockMerger::new(vec![Ok(Vec::new()), second]));
2123            let result = compactor.merge_unit(&context, &unit).await;
2124            if fail_second {
2125                assert!(
2126                    result.is_err(),
2127                    "cannot publish a successful subset of a dependency group"
2128                );
2129            } else {
2130                let result = result.unwrap();
2131                assert_eq!(2, result.files_to_add.len());
2132                assert_eq!(
2133                    vec![input.meta_ref().file_id],
2134                    result
2135                        .files_to_remove
2136                        .iter()
2137                        .map(|f| f.file_id)
2138                        .collect::<Vec<_>>()
2139                );
2140            }
2141        }
2142    }
2143
2144    #[tokio::test]
2145    async fn test_missing_index_handler_does_not_block_builtin_compaction() {
2146        use api::v1::SemanticType;
2147        use datatypes::prelude::ConcreteDataType;
2148        use datatypes::schema::{
2149            ColumnSchema, FulltextOptions, SkippingIndexOptions, SkippingIndexType,
2150        };
2151        use store_api::metadata::{ColumnMetadata, RegionMetadataBuilder};
2152
2153        use crate::sst::file::{ColumnIndexMetadata, IndexType};
2154
2155        #[derive(Debug, PartialEq, Eq)]
2156        enum RequiredBy {
2157            None,
2158            Schema,
2159            File,
2160            Column,
2161        }
2162        for required_by in [
2163            RequiredBy::None,
2164            RequiredBy::Schema,
2165            RequiredBy::File,
2166            RequiredBy::Column,
2167        ] {
2168            let mut region = new_test_compaction_region().await;
2169            Arc::make_mut(&mut region.region_metadata).column_metadatas[0]
2170                .column_schema
2171                .set_inverted_index(true);
2172            let mut metadata =
2173                RegionMetadataBuilder::from_existing((*region.region_metadata).clone());
2174            metadata.push_column_metadata(ColumnMetadata {
2175                column_schema: ColumnSchema::new("text", ConcreteDataType::string_datatype(), true)
2176                    .with_fulltext_options(FulltextOptions {
2177                        enable: true,
2178                        ..Default::default()
2179                    })
2180                    .unwrap()
2181                    .with_skipping_options(SkippingIndexOptions::new_unchecked(
2182                        42,
2183                        0.01,
2184                        SkippingIndexType::BloomFilter,
2185                    ))
2186                    .unwrap(),
2187                semantic_type: SemanticType::Field,
2188                column_id: 5,
2189            });
2190            region.region_metadata = Arc::new(metadata.build().unwrap());
2191            let mut input = dummy_file_meta();
2192            match required_by {
2193                RequiredBy::Schema => {
2194                    Arc::make_mut(&mut region.region_metadata).column_metadatas[0]
2195                        .column_schema
2196                        .mut_metadata()
2197                        .insert(
2198                            datatypes::schema::HLL_KEY.into(),
2199                            r#"{"precision":10}"#.into(),
2200                        );
2201                }
2202                RequiredBy::File => input.available_indexes.push(IndexType::HllIndex),
2203                RequiredBy::Column => input.indexes.push(ColumnIndexMetadata {
2204                    column_id: 0,
2205                    created_indexes: [IndexType::HllIndex].into_iter().collect(),
2206                    ..Default::default()
2207                }),
2208                _ => {}
2209            }
2210            let context = CompactionContext::try_from(&region).unwrap();
2211            assert_eq!(
2212                context
2213                    .index_plan
2214                    .planned()
2215                    .iter()
2216                    .flat_map(|plan| plan.kinds().iter().copied())
2217                    .collect::<Vec<_>>(),
2218                [IndexKind::Inverted, IndexKind::Fulltext, IndexKind::Bloom]
2219            );
2220            let output = PickerOutput {
2221                outputs: vec![CompactionOutput {
2222                    output_level: 1,
2223                    inputs: vec![new_file_handle(input)],
2224                    filter_deleted: false,
2225                    output_time_range: None,
2226                }],
2227                ..Default::default()
2228            };
2229            for local in [false, true] {
2230                let merger = MockMerger::new(vec![Ok(Vec::new())]);
2231                let calls = merger.call_idx.clone();
2232                let compactor = DefaultCompactor::with_merger(merger);
2233                let result = if local {
2234                    let context = CompactionContext::try_from(&region).unwrap();
2235                    let unit = CompactionUnit::from_picker(output.clone())
2236                        .unwrap()
2237                        .pop()
2238                        .unwrap();
2239                    compactor.merge_unit(&context, &unit).await
2240                } else {
2241                    compactor.merge_ssts(&region, output.clone()).await
2242                };
2243                assert!(result.is_ok(), "{required_by:?}, local={local}: {result:?}");
2244                assert_eq!(calls.load(Ordering::SeqCst), 1);
2245            }
2246        }
2247    }
2248
2249    #[tokio::test]
2250    async fn test_partial_merge_failure_collects_only_successful_outputs() {
2251        common_telemetry::init_default_ut_logging();
2252
2253        let compaction_region = new_test_compaction_region().await;
2254
2255        // Prepare 3 compaction outputs: output 0 and 2 succeed, output 1 fails.
2256        let input_meta_0 = dummy_file_meta();
2257        let input_meta_1 = dummy_file_meta();
2258        let input_meta_2 = dummy_file_meta();
2259
2260        let output_meta_0 = vec![dummy_file_meta()];
2261        let output_meta_2 = vec![dummy_file_meta(), dummy_file_meta()];
2262
2263        let merger = MockMerger::new(vec![
2264            Ok(output_meta_0.clone()),
2265            Err(error::InvalidMetaSnafu {
2266                reason: "boom".to_string(),
2267            }
2268            .build()),
2269            Ok(output_meta_2.clone()),
2270        ]);
2271        let compactor = DefaultCompactor::with_merger(merger);
2272
2273        let picker_output = PickerOutput {
2274            outputs: vec![
2275                CompactionOutput {
2276                    output_level: 1,
2277                    inputs: vec![new_file_handle(input_meta_0.clone())],
2278                    filter_deleted: false,
2279                    output_time_range: None,
2280                },
2281                CompactionOutput {
2282                    output_level: 1,
2283                    inputs: vec![new_file_handle(input_meta_1.clone())],
2284                    filter_deleted: false,
2285                    output_time_range: None,
2286                },
2287                CompactionOutput {
2288                    output_level: 1,
2289                    inputs: vec![new_file_handle(input_meta_2.clone())],
2290                    filter_deleted: false,
2291                    output_time_range: None,
2292                },
2293            ],
2294            expired_ssts: vec![],
2295            time_window_size: 3600,
2296            max_file_size: None,
2297        };
2298
2299        let merge_output = compactor
2300            .merge_ssts(&compaction_region, picker_output)
2301            .await
2302            .unwrap();
2303
2304        // Outputs 0 and 2 succeeded (1 + 2 = 3 files added).
2305        assert_eq!(merge_output.files_to_add.len(), 3);
2306        // Only inputs from successful merges should be removed.
2307        assert_eq!(merge_output.files_to_remove.len(), 2);
2308
2309        let removed_ids: Vec<_> = merge_output
2310            .files_to_remove
2311            .iter()
2312            .map(|f| f.file_id)
2313            .collect();
2314        assert!(removed_ids.contains(&input_meta_0.file_id));
2315        assert!(removed_ids.contains(&input_meta_2.file_id));
2316        // The failed output's input must NOT be removed.
2317        assert!(!removed_ids.contains(&input_meta_1.file_id));
2318    }
2319
2320    #[tokio::test]
2321    async fn test_all_outputs_succeed() {
2322        common_telemetry::init_default_ut_logging();
2323
2324        let compaction_region = new_test_compaction_region().await;
2325        let input_meta = dummy_file_meta();
2326        let output_meta = vec![dummy_file_meta()];
2327
2328        let merger = MockMerger::new(vec![Ok(output_meta.clone())]);
2329        let compactor = DefaultCompactor::with_merger(merger);
2330
2331        let picker_output = PickerOutput {
2332            outputs: vec![CompactionOutput {
2333                output_level: 1,
2334                inputs: vec![new_file_handle(input_meta.clone())],
2335                filter_deleted: false,
2336                output_time_range: None,
2337            }],
2338            expired_ssts: vec![],
2339            time_window_size: 3600,
2340            max_file_size: None,
2341        };
2342
2343        let merge_output = compactor
2344            .merge_ssts(&compaction_region, picker_output)
2345            .await
2346            .unwrap();
2347
2348        assert_eq!(merge_output.files_to_add.len(), 1);
2349        assert_eq!(merge_output.files_to_add[0].file_id, output_meta[0].file_id);
2350        assert_eq!(merge_output.files_to_remove.len(), 1);
2351        assert_eq!(merge_output.files_to_remove[0].file_id, input_meta.file_id);
2352    }
2353
2354    #[tokio::test]
2355    async fn test_expired_ssts_always_removed() {
2356        common_telemetry::init_default_ut_logging();
2357
2358        let compaction_region = new_test_compaction_region().await;
2359        let input_meta = dummy_file_meta();
2360        let expired_meta = dummy_file_meta();
2361
2362        // The single merge output fails, but expired SSTs should still be removed.
2363        let merger = MockMerger::new(vec![Err(error::InvalidMetaSnafu {
2364            reason: "fail".to_string(),
2365        }
2366        .build())]);
2367        let compactor = DefaultCompactor::with_merger(merger);
2368
2369        let picker_output = PickerOutput {
2370            outputs: vec![CompactionOutput {
2371                output_level: 1,
2372                inputs: vec![new_file_handle(input_meta.clone())],
2373                filter_deleted: false,
2374                output_time_range: None,
2375            }],
2376            expired_ssts: vec![new_file_handle(expired_meta.clone())],
2377            time_window_size: 3600,
2378            max_file_size: None,
2379        };
2380
2381        let merge_output = compactor
2382            .merge_ssts(&compaction_region, picker_output)
2383            .await
2384            .unwrap();
2385
2386        // No files added (merge failed).
2387        assert!(merge_output.files_to_add.is_empty());
2388        // Only the expired SST should be in files_to_remove (not the failed merge's input).
2389        assert_eq!(merge_output.files_to_remove.len(), 1);
2390        assert_eq!(
2391            merge_output.files_to_remove[0].file_id,
2392            expired_meta.file_id
2393        );
2394    }
2395
2396    #[derive(Debug)]
2397    struct PendingEncoding {
2398        input_id: FileId,
2399        output_id: FileId,
2400        batch: Weak<RecordBatch>,
2401        release: oneshot::Sender<()>,
2402    }
2403
2404    /// A merger with real blocking Parquet encoding and deterministic lifetime gates.
2405    #[derive(Clone)]
2406    struct GatedEncodingMerger {
2407        started: mpsc::UnboundedSender<PendingEncoding>,
2408        panic_input: Option<FileId>,
2409    }
2410
2411    #[async_trait::async_trait]
2412    impl SstMerger for GatedEncodingMerger {
2413        async fn merge_single_output(
2414            &self,
2415            _context: CompactionContext,
2416            output: CompactionOutput,
2417            _write_opts: WriteOptions,
2418            _cancellation: CancellationToken,
2419        ) -> Result<(Vec<FileMeta>, Vec<SstInfo>)> {
2420            let input_id = output.inputs[0].meta_ref().file_id;
2421            let mut file = dummy_file_meta();
2422            let batch = Arc::new(new_record_batch_by_range(&["a", "b"], 0, 4));
2423            let (release, wait) = oneshot::channel();
2424            let pending = PendingEncoding {
2425                input_id,
2426                output_id: file.file_id,
2427                batch: Arc::downgrade(&batch),
2428                release,
2429            };
2430            let started = self.started.clone();
2431            file.file_size = common_runtime::spawn_blocking_compact(move || {
2432                started.send(pending).unwrap();
2433                wait.blocking_recv().unwrap();
2434                let mut bytes = Vec::new();
2435                let mut writer = ArrowWriter::try_new(&mut bytes, batch.schema(), None)?;
2436                writer.write(&batch)?;
2437                writer.close()?;
2438                Ok::<_, parquet::errors::ParquetError>(bytes.len() as u64)
2439            })
2440            .await
2441            .context(error::JoinSnafu)?
2442            .context(error::WriteParquetSnafu)?;
2443            if self.panic_input == Some(input_id) {
2444                panic!("merge task panicked");
2445            }
2446            Ok((vec![file], Vec::new()))
2447        }
2448    }
2449
2450    #[rstest::rstest]
2451    #[case::successful_outputs(false)]
2452    #[case::join_error(true)]
2453    #[tokio::test]
2454    async fn test_merge_ssts_cancellation_waits_for_encoders(#[case] panic_merge: bool) {
2455        let mut region = new_test_compaction_region().await;
2456        region.max_parallelism = 2;
2457        region.region_options.compaction_output_parallelism = Some(2);
2458        let inputs: Vec<_> = (0..3).map(|_| dummy_file_meta()).collect();
2459        let picker_output = PickerOutput {
2460            outputs: inputs
2461                .iter()
2462                .map(|input| CompactionOutput {
2463                    output_level: 1,
2464                    inputs: vec![new_file_handle(input.clone())],
2465                    filter_deleted: false,
2466                    output_time_range: None,
2467                })
2468                .collect(),
2469            ..Default::default()
2470        };
2471        let cancel_token = CancellationToken::new();
2472        let (started_tx, mut started_rx) = mpsc::unbounded_channel();
2473        let compactor = DefaultCompactor {
2474            merger: GatedEncodingMerger {
2475                started: started_tx,
2476                // Outputs are popped from the back, then joined in reverse order.
2477                panic_input: panic_merge.then_some(inputs[1].file_id),
2478            },
2479            cancel_token: cancel_token.clone(),
2480            uncommitted: None,
2481        };
2482        let memory = new_compaction_memory_manager(1024 * 1024);
2483        let budget = memory.try_acquire(memory.limit_bytes()).unwrap();
2484        let mut merge = Box::pin(async {
2485            let _budget = budget;
2486            compactor.merge_ssts(&region, picker_output).await
2487        });
2488        assert!(futures::poll!(merge.as_mut()).is_pending());
2489        let mut encoders = Vec::new();
2490        for _ in 0..2 {
2491            encoders.push(
2492                timeout(Duration::from_secs(10), started_rx.recv())
2493                    .await
2494                    .unwrap()
2495                    .unwrap(),
2496            );
2497        }
2498        cancel_token.cancel();
2499        assert!(futures::poll!(merge.as_mut()).is_pending());
2500        assert!(memory.try_acquire(memory.limit_bytes()).is_none());
2501        assert!(
2502            encoders
2503                .iter()
2504                .all(|encoder| encoder.batch.upgrade().is_some())
2505        );
2506        let retained_batches: Vec<_> = encoders
2507            .iter()
2508            .map(|encoder| encoder.batch.clone())
2509            .collect();
2510        let mut expected_inputs: Vec<_> = encoders.iter().map(|encoder| encoder.input_id).collect();
2511        let mut expected_outputs: Vec<_> =
2512            encoders.iter().map(|encoder| encoder.output_id).collect();
2513        for encoder in encoders {
2514            encoder.release.send(()).unwrap();
2515        }
2516        let result = timeout(Duration::from_secs(10), merge).await.unwrap();
2517        assert!(
2518            retained_batches
2519                .iter()
2520                .all(|batch| batch.upgrade().is_none())
2521        );
2522        assert!(memory.try_acquire(memory.limit_bytes()).is_some());
2523        assert!(
2524            started_rx.try_recv().is_err(),
2525            "cancelled work must not start another output"
2526        );
2527        if panic_merge {
2528            assert!(matches!(result, Err(error::Error::Join { error, .. }) if error.is_panic()));
2529        } else {
2530            let merged = result.unwrap();
2531            let mut removed: Vec<_> = merged
2532                .files_to_remove
2533                .iter()
2534                .map(|file| file.file_id)
2535                .collect();
2536            let mut added: Vec<_> = merged
2537                .files_to_add
2538                .iter()
2539                .map(|file| file.file_id)
2540                .collect();
2541            for ids in [
2542                &mut removed,
2543                &mut added,
2544                &mut expected_inputs,
2545                &mut expected_outputs,
2546            ] {
2547                ids.sort_by(|a, b| a.as_bytes().cmp(b.as_bytes()));
2548            }
2549            assert_eq!(expected_inputs, removed);
2550            assert_eq!(expected_outputs, added);
2551            assert!(merged.files_to_add.iter().all(|file| file.file_size > 0));
2552        }
2553    }
2554
2555    #[tokio::test]
2556    async fn test_merge_ssts_cancelled_before_start_skips_outputs() {
2557        let region = new_test_compaction_region().await;
2558        let merger = MockMerger::new(vec![Ok(vec![dummy_file_meta()])]);
2559        let calls = merger.call_idx.clone();
2560        let compactor = DefaultCompactor::with_merger(merger);
2561        compactor.cancel_token.cancel();
2562        let picker_output = PickerOutput {
2563            outputs: vec![CompactionOutput {
2564                output_level: 1,
2565                inputs: vec![new_file_handle(dummy_file_meta())],
2566                filter_deleted: false,
2567                output_time_range: None,
2568            }],
2569            ..Default::default()
2570        };
2571        let merged = compactor.merge_ssts(&region, picker_output).await.unwrap();
2572        assert!(merged.is_empty());
2573        assert_eq!(0, calls.load(Ordering::SeqCst));
2574    }
2575}