Skip to main content

store_api/
region_request.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::HashMap;
16use std::fmt::{self, Display};
17use std::time::Duration;
18
19use api::helper::{ColumnDataTypeWrapper, from_pb_time_ranges};
20use api::v1::add_column_location::LocationType;
21use api::v1::column_def::{
22    as_fulltext_option_analyzer, as_fulltext_option_backend, as_skipping_index_type,
23};
24use api::v1::region::bulk_insert_request::Body;
25use api::v1::region::{
26    AlterRequest, AlterRequests, BuildIndexRequest, BulkInsertRequest,
27    CleanUpRequest as PbCleanUpRequest, CloseRequest, CompactRequest, CreateRequest,
28    CreateRequests, DeleteRequests, DropRequest, DropRequests, FlushRequest, InsertRequests,
29    OpenRequest, TruncateRequest, alter_request, compact_request, region_request, truncate_request,
30};
31use api::v1::{
32    self, Analyzer, ArrowIpc, FulltextBackend as PbFulltextBackend, Option as PbOption, Rows,
33    SemanticType, SkippingIndexType as PbSkippingIndexType, WriteHint,
34};
35pub use common_base::AffectedRows;
36use common_base::readable_size::ReadableSize;
37use common_grpc::flight::FlightDecoder;
38use common_recordbatch::DfRecordBatch;
39use common_time::{TimeToLive, Timestamp};
40use datatypes::prelude::ConcreteDataType;
41use datatypes::schema::{FulltextOptions, SkippingIndexOptions};
42use num_enum::TryFromPrimitive;
43use serde::{Deserialize, Serialize};
44use snafu::{OptionExt, ResultExt, ensure};
45use strum::{AsRefStr, IntoStaticStr};
46
47use crate::logstore::entry;
48use crate::metadata::{
49    ColumnMetadata, ConvertTimeRangesSnafu, DecodeProtoSnafu, FlightCodecSnafu,
50    InvalidIndexOptionSnafu, InvalidRawRegionRequestSnafu, InvalidRegionRequestSnafu,
51    InvalidSetRegionOptionRequestSnafu, InvalidUnsetRegionOptionRequestSnafu, MetadataError,
52    RegionMetadata, Result, UnexpectedSnafu,
53};
54use crate::metric_engine_consts::PHYSICAL_TABLE_METADATA_KEY;
55use crate::metrics;
56use crate::mito_engine_options::{
57    APPEND_MODE_KEY, AUTO_FLUSH_INTERVAL_KEY, SST_FORMAT_KEY, TTL_KEY, TWCS_MAX_OUTPUT_FILE_SIZE,
58    TWCS_TIME_WINDOW, TWCS_TRIGGER_FILE_NUM, WRITE_BUFFER_SIZE_KEY,
59};
60use crate::path_utils::table_dir;
61use crate::storage::{ColumnId, RegionId, ScanRequest};
62
63/// The type of path to generate.
64#[derive(Debug, Clone, Copy, PartialEq, TryFromPrimitive)]
65#[repr(u8)]
66pub enum PathType {
67    /// A bare path - the original path of an engine.
68    ///
69    /// The path prefix is `{table_dir}/{table_id}_{region_sequence}/`.
70    Bare,
71    /// A path for the data region of a metric engine table.
72    ///
73    /// The path prefix is `{table_dir}/{table_id}_{region_sequence}/data/`.
74    Data,
75    /// A path for the metadata region of a metric engine table.
76    ///
77    /// The path prefix is `{table_dir}/{table_id}_{region_sequence}/metadata/`.
78    Metadata,
79}
80
81#[derive(Debug, IntoStaticStr)]
82pub enum BatchRegionDdlRequest {
83    Create(Vec<(RegionId, RegionCreateRequest)>),
84    Drop(Vec<(RegionId, RegionDropRequest)>),
85    Alter(Vec<(RegionId, RegionAlterRequest)>),
86}
87
88impl BatchRegionDdlRequest {
89    /// Converts [Body](region_request::Body) to [`BatchRegionDdlRequest`].
90    pub fn try_from_request_body(body: region_request::Body) -> Result<Option<Self>> {
91        match body {
92            region_request::Body::Creates(creates) => {
93                let requests = creates
94                    .requests
95                    .into_iter()
96                    .map(parse_region_create)
97                    .collect::<Result<Vec<_>>>()?;
98                Ok(Some(Self::Create(requests)))
99            }
100            region_request::Body::Drops(drops) => {
101                let requests = drops
102                    .requests
103                    .into_iter()
104                    .map(parse_region_drop)
105                    .collect::<Result<Vec<_>>>()?;
106                Ok(Some(Self::Drop(requests)))
107            }
108            region_request::Body::Alters(alters) => {
109                let requests = alters
110                    .requests
111                    .into_iter()
112                    .map(parse_region_alter)
113                    .collect::<Result<Vec<_>>>()?;
114                Ok(Some(Self::Alter(requests)))
115            }
116            _ => Ok(None),
117        }
118    }
119
120    pub fn request_type(&self) -> &'static str {
121        self.into()
122    }
123
124    pub fn into_region_requests(self) -> Vec<(RegionId, RegionRequest)> {
125        match self {
126            Self::Create(requests) => requests
127                .into_iter()
128                .map(|(region_id, request)| (region_id, RegionRequest::Create(request)))
129                .collect(),
130            Self::Drop(requests) => requests
131                .into_iter()
132                .map(|(region_id, request)| (region_id, RegionRequest::Drop(request)))
133                .collect(),
134            Self::Alter(requests) => requests
135                .into_iter()
136                .map(|(region_id, request)| (region_id, RegionRequest::Alter(request)))
137                .collect(),
138        }
139    }
140}
141
142#[derive(Debug, IntoStaticStr)]
143pub enum RegionRequest {
144    Put(RegionPutRequest),
145    Delete(RegionDeleteRequest),
146    Create(RegionCreateRequest),
147    Drop(RegionDropRequest),
148    Open(RegionOpenRequest),
149    CleanUp(RegionCleanUpRequest),
150    Close(RegionCloseRequest),
151    Alter(RegionAlterRequest),
152    Flush(RegionFlushRequest),
153    Compact(RegionCompactRequest),
154    BuildIndex(RegionBuildIndexRequest),
155    Truncate(RegionTruncateRequest),
156    Catchup(RegionCatchupRequest),
157    BulkInserts(RegionBulkInsertsRequest),
158    EnterStaging(EnterStagingRequest),
159    ApplyStagingManifest(ApplyStagingManifestRequest),
160}
161
162impl RegionRequest {
163    /// Convert [Body](region_request::Body) to a group of [RegionRequest] with region id.
164    /// Inserts/Deletes request might become multiple requests. Others are one-to-one.
165    pub fn try_from_request_body(body: region_request::Body) -> Result<Vec<(RegionId, Self)>> {
166        match body {
167            region_request::Body::Inserts(inserts) => make_region_puts(inserts),
168            region_request::Body::Deletes(deletes) => make_region_deletes(deletes),
169            region_request::Body::Create(create) => make_region_create(create),
170            region_request::Body::Drop(drop) => make_region_drop(drop),
171            region_request::Body::Open(open) => make_region_open(open),
172            region_request::Body::CleanUp(clean_up) => make_region_clean_up(clean_up),
173            region_request::Body::Close(close) => make_region_close(close),
174            region_request::Body::Alter(alter) => make_region_alter(alter),
175            region_request::Body::Flush(flush) => make_region_flush(flush),
176            region_request::Body::Compact(compact) => make_region_compact(compact),
177            region_request::Body::BuildIndex(index) => make_region_build_index(index),
178            region_request::Body::Truncate(truncate) => make_region_truncate(truncate),
179            region_request::Body::Creates(creates) => make_region_creates(creates),
180            region_request::Body::Drops(drops) => make_region_drops(drops),
181            region_request::Body::Alters(alters) => make_region_alters(alters),
182            region_request::Body::BulkInsert(bulk) => make_region_bulk_inserts(bulk),
183            region_request::Body::Sync(_) => UnexpectedSnafu {
184                reason: "Sync request should be handled separately by RegionServer",
185            }
186            .fail(),
187            region_request::Body::ListMetadata(_) => UnexpectedSnafu {
188                reason: "ListMetadata request should be handled separately by RegionServer",
189            }
190            .fail(),
191            region_request::Body::RemoteDynFilter(_) => UnexpectedSnafu {
192                reason: "RemoteDynFilter request should be handled separately by RegionServer",
193            }
194            .fail(),
195            region_request::Body::ApplyStagingManifest(apply) => {
196                make_region_apply_staging_manifest(apply)
197            }
198        }
199    }
200
201    /// Returns the type name of the request.
202    pub fn request_type(&self) -> &'static str {
203        self.into()
204    }
205}
206
207fn make_region_puts(inserts: InsertRequests) -> Result<Vec<(RegionId, RegionRequest)>> {
208    let requests = inserts
209        .requests
210        .into_iter()
211        .filter_map(|r| {
212            let region_id = r.region_id.into();
213            r.rows.map(|rows| {
214                (
215                    region_id,
216                    RegionRequest::Put(RegionPutRequest {
217                        rows,
218                        hint: None,
219                        partition_expr_version: r.partition_expr_version.map(|v| v.value),
220                    }),
221                )
222            })
223        })
224        .collect();
225    Ok(requests)
226}
227
228fn make_region_deletes(deletes: DeleteRequests) -> Result<Vec<(RegionId, RegionRequest)>> {
229    let requests = deletes
230        .requests
231        .into_iter()
232        .filter_map(|r| {
233            let region_id = r.region_id.into();
234            r.rows.map(|rows| {
235                (
236                    region_id,
237                    RegionRequest::Delete(RegionDeleteRequest {
238                        rows,
239                        hint: None,
240                        partition_expr_version: r.partition_expr_version.map(|v| v.value),
241                    }),
242                )
243            })
244        })
245        .collect();
246    Ok(requests)
247}
248
249fn parse_region_create(create: CreateRequest) -> Result<(RegionId, RegionCreateRequest)> {
250    let column_metadatas = create
251        .column_defs
252        .into_iter()
253        .map(ColumnMetadata::try_from_column_def)
254        .collect::<Result<Vec<_>>>()?;
255    let region_id = RegionId::from(create.region_id);
256    let table_dir = table_dir(&create.path, region_id.table_id());
257    let partition_expr_json = create.partition.as_ref().map(|p| p.expression.clone());
258    Ok((
259        region_id,
260        RegionCreateRequest {
261            engine: create.engine,
262            column_metadatas,
263            primary_key: create.primary_key,
264            options: create.options,
265            table_dir,
266            path_type: PathType::Bare,
267            partition_expr_json,
268            requirements: create
269                .requirements
270                .map(RegionRequirements::from)
271                .unwrap_or_default(),
272        },
273    ))
274}
275
276fn make_region_create(create: CreateRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
277    let (region_id, request) = parse_region_create(create)?;
278    Ok(vec![(region_id, RegionRequest::Create(request))])
279}
280
281fn make_region_creates(creates: CreateRequests) -> Result<Vec<(RegionId, RegionRequest)>> {
282    let mut requests = Vec::with_capacity(creates.requests.len());
283    for create in creates.requests {
284        requests.extend(make_region_create(create)?);
285    }
286    Ok(requests)
287}
288
289fn parse_region_drop(drop: DropRequest) -> Result<(RegionId, RegionDropRequest)> {
290    let region_id = drop.region_id.into();
291    Ok((
292        region_id,
293        RegionDropRequest {
294            fast_path: drop.fast_path,
295            force: drop.force,
296            partial_drop: drop.partial_drop,
297        },
298    ))
299}
300
301fn make_region_drop(drop: DropRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
302    let (region_id, request) = parse_region_drop(drop)?;
303    Ok(vec![(region_id, RegionRequest::Drop(request))])
304}
305
306fn make_region_drops(drops: DropRequests) -> Result<Vec<(RegionId, RegionRequest)>> {
307    let mut requests = Vec::with_capacity(drops.requests.len());
308    for drop in drops.requests {
309        requests.extend(make_region_drop(drop)?);
310    }
311    Ok(requests)
312}
313
314fn make_region_open(open: OpenRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
315    let region_id = RegionId::from(open.region_id);
316    let table_dir = table_dir(&open.path, region_id.table_id());
317    Ok(vec![(
318        region_id,
319        RegionRequest::Open(RegionOpenRequest {
320            engine: open.engine,
321            table_dir,
322            path_type: PathType::Bare,
323            options: open.options,
324            skip_wal_replay: false,
325            checkpoint: None,
326            requirements: Default::default(),
327        }),
328    )])
329}
330
331fn make_region_clean_up(clean_up: PbCleanUpRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
332    let region_id = RegionId::from(clean_up.region_id);
333    let table_dir = table_dir(&clean_up.path, region_id.table_id());
334    Ok(vec![(
335        region_id,
336        RegionRequest::CleanUp(RegionCleanUpRequest {
337            engine: clean_up.engine,
338            table_dir,
339            path_type: PathType::Bare,
340            options: clean_up.options,
341        }),
342    )])
343}
344
345fn make_region_close(close: CloseRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
346    let region_id = close.region_id.into();
347    Ok(vec![(
348        region_id,
349        RegionRequest::Close(RegionCloseRequest {
350            flush_on_close: close.flush_on_close,
351        }),
352    )])
353}
354
355fn parse_region_alter(alter: AlterRequest) -> Result<(RegionId, RegionAlterRequest)> {
356    let region_id = alter.region_id.into();
357    let request = RegionAlterRequest::try_from(alter)?;
358    Ok((region_id, request))
359}
360
361fn make_region_alter(alter: AlterRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
362    let (region_id, request) = parse_region_alter(alter)?;
363    Ok(vec![(region_id, RegionRequest::Alter(request))])
364}
365
366fn make_region_alters(alters: AlterRequests) -> Result<Vec<(RegionId, RegionRequest)>> {
367    let mut requests = Vec::with_capacity(alters.requests.len());
368    for alter in alters.requests {
369        requests.extend(make_region_alter(alter)?);
370    }
371    Ok(requests)
372}
373
374fn make_region_flush(flush: FlushRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
375    let region_id = flush.region_id.into();
376    Ok(vec![(
377        region_id,
378        RegionRequest::Flush(RegionFlushRequest::default()),
379    )])
380}
381
382fn make_region_compact(compact: CompactRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
383    let region_id = compact.region_id.into();
384    let options = compact
385        .options
386        .unwrap_or(compact_request::Options::Regular(Default::default()));
387    // Convert parallelism: a value of 0 indicates no specific parallelism requested (None)
388    let parallelism = if compact.parallelism == 0 {
389        None
390    } else {
391        Some(compact.parallelism)
392    };
393    Ok(vec![(
394        region_id,
395        RegionRequest::Compact(RegionCompactRequest {
396            options,
397            parallelism,
398        }),
399    )])
400}
401
402fn make_region_build_index(index: BuildIndexRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
403    let region_id = index.region_id.into();
404    Ok(vec![(
405        region_id,
406        RegionRequest::BuildIndex(RegionBuildIndexRequest {}),
407    )])
408}
409
410fn make_region_truncate(truncate: TruncateRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
411    let region_id = truncate.region_id.into();
412    match truncate.kind {
413        None => InvalidRawRegionRequestSnafu {
414            err: "missing kind in TruncateRequest".to_string(),
415        }
416        .fail(),
417        Some(truncate_request::Kind::All(_)) => Ok(vec![(
418            region_id,
419            RegionRequest::Truncate(RegionTruncateRequest::All),
420        )]),
421        Some(truncate_request::Kind::TimeRanges(time_ranges)) => {
422            let time_ranges = from_pb_time_ranges(time_ranges).context(ConvertTimeRangesSnafu)?;
423
424            Ok(vec![(
425                region_id,
426                RegionRequest::Truncate(RegionTruncateRequest::ByTimeRanges { time_ranges }),
427            )])
428        }
429    }
430}
431
432/// Convert [BulkInsertRequest] to [RegionRequest] and group by [RegionId].
433fn make_region_bulk_inserts(request: BulkInsertRequest) -> Result<Vec<(RegionId, RegionRequest)>> {
434    let region_id = request.region_id.into();
435    let partition_expr_version = request.partition_expr_version.map(|v| v.value);
436    let aligned_schema_version = request.aligned_schema_version.map(|v| v.schema_version);
437    let Some(Body::ArrowIpc(request)) = request.body else {
438        return Ok(vec![]);
439    };
440
441    let decoder_timer = metrics::CONVERT_REGION_BULK_REQUEST
442        .with_label_values(&["decode"])
443        .start_timer();
444    let mut decoder =
445        FlightDecoder::try_from_schema_bytes(&request.schema).context(FlightCodecSnafu)?;
446    let payload = decoder
447        .try_decode_record_batch(&request.data_header, &request.payload)
448        .context(FlightCodecSnafu)?;
449    decoder_timer.observe_duration();
450    Ok(vec![(
451        region_id,
452        RegionRequest::BulkInserts(RegionBulkInsertsRequest {
453            region_id,
454            payload,
455            raw_data: request,
456            partition_expr_version,
457            aligned_schema_version,
458        }),
459    )])
460}
461
462fn make_region_apply_staging_manifest(
463    api::v1::region::ApplyStagingManifestRequest {
464        region_id,
465        partition_expr,
466        central_region_id,
467        manifest_path,
468    }: api::v1::region::ApplyStagingManifestRequest,
469) -> Result<Vec<(RegionId, RegionRequest)>> {
470    let region_id = region_id.into();
471    Ok(vec![(
472        region_id,
473        RegionRequest::ApplyStagingManifest(ApplyStagingManifestRequest {
474            partition_expr,
475            central_region_id: central_region_id.into(),
476            manifest_path,
477        }),
478    )])
479}
480
481/// Request to put data into a region.
482#[derive(Debug)]
483pub struct RegionPutRequest {
484    /// Rows to put.
485    pub rows: Rows,
486    /// Write hint.
487    pub hint: Option<WriteHint>,
488    /// Partition expression version for the region.
489    pub partition_expr_version: Option<u64>,
490}
491
492#[derive(Debug)]
493pub struct RegionReadRequest {
494    pub request: ScanRequest,
495}
496
497/// Request to delete data from a region.
498#[derive(Debug)]
499pub struct RegionDeleteRequest {
500    /// Keys to rows to delete.
501    ///
502    /// Each row only contains primary key columns and a time index column.
503    pub rows: Rows,
504    /// Write hint.
505    pub hint: Option<WriteHint>,
506    /// Partition expression version for the region.
507    pub partition_expr_version: Option<u64>,
508}
509
510#[derive(Debug, Clone)]
511pub struct RegionCreateRequest {
512    /// Region engine name
513    pub engine: String,
514    /// Columns in this region.
515    pub column_metadatas: Vec<ColumnMetadata>,
516    /// Columns in the primary key.
517    pub primary_key: Vec<ColumnId>,
518    /// Options of the created region.
519    pub options: HashMap<String, String>,
520    /// Directory for table's data home. Usually is composed by catalog and table id
521    pub table_dir: String,
522    /// Path type for generating paths
523    pub path_type: PathType,
524    /// Partition expression JSON from table metadata. Set to empty string for a region without partition.
525    /// `Option` to keep compatibility with old clients.
526    pub partition_expr_json: Option<String>,
527    /// Requirements for creating the region.
528    pub requirements: RegionRequirements,
529}
530
531impl RegionCreateRequest {
532    /// Checks whether the request is valid, returns an error if it is invalid.
533    pub fn validate(&self) -> Result<()> {
534        // time index must exist
535        ensure!(
536            self.column_metadatas
537                .iter()
538                .any(|x| x.semantic_type == SemanticType::Timestamp),
539            InvalidRegionRequestSnafu {
540                region_id: RegionId::new(0, 0),
541                err: "missing timestamp column in create region request".to_string(),
542            }
543        );
544
545        // build column id to indices
546        let mut column_id_to_indices = HashMap::with_capacity(self.column_metadatas.len());
547        for (i, c) in self.column_metadatas.iter().enumerate() {
548            if let Some(previous) = column_id_to_indices.insert(c.column_id, i) {
549                return InvalidRegionRequestSnafu {
550                    region_id: RegionId::new(0, 0),
551                    err: format!(
552                        "duplicate column id {} (at position {} and {}) in create region request",
553                        c.column_id, previous, i
554                    ),
555                }
556                .fail();
557            }
558        }
559
560        // primary key must exist
561        for column_id in &self.primary_key {
562            ensure!(
563                column_id_to_indices.contains_key(column_id),
564                InvalidRegionRequestSnafu {
565                    region_id: RegionId::new(0, 0),
566                    err: format!(
567                        "missing primary key column {} in create region request",
568                        column_id
569                    ),
570                }
571            );
572        }
573
574        Ok(())
575    }
576
577    /// Returns true when the region belongs to the metric engine's physical table.
578    pub fn is_physical_table(&self) -> bool {
579        self.options.contains_key(PHYSICAL_TABLE_METADATA_KEY)
580    }
581}
582
583#[derive(Debug, Clone)]
584pub struct RegionDropRequest {
585    /// Enables fast-path drop optimizations for logical regions.
586    /// Only applicable to the Metric Engine; ignored by others.
587    pub fast_path: bool,
588
589    /// Forces the drop of a physical region and all its associated logical regions.
590    /// Only relevant for physical regions managed by the Metric Engine.
591    pub force: bool,
592
593    /// If true, indicates that only a portion of the region is being dropped, and files may still be referenced by other regions.
594    /// This is used to prevent deletion of files that are still in use by other regions.
595    pub partial_drop: bool,
596}
597
598/// Requirements for a region request.
599#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
600#[serde(default)]
601pub struct RegionRequirements {
602    /// Whether the region data must be backed by object storage.
603    pub object_storage: bool,
604}
605
606impl RegionRequirements {
607    /// Returns empty requirements.
608    pub fn empty() -> Self {
609        Self::default()
610    }
611
612    /// Returns requirements for object storage.
613    pub fn object_storage() -> Self {
614        Self {
615            object_storage: true,
616        }
617    }
618}
619
620impl From<api::v1::region::RegionRequirements> for RegionRequirements {
621    fn from(value: api::v1::region::RegionRequirements) -> Self {
622        Self {
623            object_storage: value.object_storage,
624        }
625    }
626}
627
628impl From<RegionRequirements> for api::v1::region::RegionRequirements {
629    fn from(value: RegionRequirements) -> Self {
630        Self {
631            object_storage: value.object_storage,
632        }
633    }
634}
635
636/// Open region request.
637#[derive(Debug, Clone)]
638pub struct RegionOpenRequest {
639    /// Region engine name
640    pub engine: String,
641    /// Directory for table's data home. Usually is composed by catalog and table id
642    pub table_dir: String,
643    /// Path type for generating paths
644    pub path_type: PathType,
645    /// Options of the opened region.
646    pub options: HashMap<String, String>,
647    /// To skip replaying the WAL.
648    pub skip_wal_replay: bool,
649    /// Replay checkpoint.
650    pub checkpoint: Option<ReplayCheckpoint>,
651    /// Requirements for opening the region.
652    pub requirements: RegionRequirements,
653}
654
655#[derive(Debug, Clone, Copy, PartialEq, Eq)]
656pub struct ReplayCheckpoint {
657    pub entry_id: u64,
658    pub metadata_entry_id: Option<u64>,
659}
660
661impl RegionOpenRequest {
662    /// Returns true when the region belongs to the metric engine's physical table.
663    pub fn is_physical_table(&self) -> bool {
664        self.options.contains_key(PHYSICAL_TABLE_METADATA_KEY)
665    }
666}
667
668/// Offline region cleanup request.
669#[derive(Debug, Clone)]
670pub struct RegionCleanUpRequest {
671    /// Region engine name
672    pub engine: String,
673    /// Directory for table's data home. Usually is composed by catalog and table id
674    pub table_dir: String,
675    /// Path type for generating paths
676    pub path_type: PathType,
677    /// Options of the cleaned region.
678    pub options: HashMap<String, String>,
679}
680
681impl RegionCleanUpRequest {
682    /// Returns true when the region belongs to the metric engine's physical table.
683    pub fn is_physical_table(&self) -> bool {
684        self.options.contains_key(PHYSICAL_TABLE_METADATA_KEY)
685    }
686}
687
688/// Close region request.
689#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
690pub struct RegionCloseRequest {
691    /// Whether to flush the region before closing it.
692    pub flush_on_close: bool,
693}
694
695/// Alter metadata of a region.
696#[derive(Debug, PartialEq, Eq, Clone)]
697pub struct RegionAlterRequest {
698    /// Kind of alteration to do.
699    pub kind: AlterKind,
700}
701
702impl RegionAlterRequest {
703    /// Checks whether the request is valid, returns an error if it is invalid.
704    pub fn validate(&self, metadata: &RegionMetadata) -> Result<()> {
705        self.kind.validate(metadata)?;
706
707        Ok(())
708    }
709
710    /// Returns true if we need to apply the request to the region.
711    ///
712    /// The `request` should be valid.
713    pub fn need_alter(&self, metadata: &RegionMetadata) -> bool {
714        debug_assert!(self.validate(metadata).is_ok());
715        self.kind.need_alter(metadata)
716    }
717}
718
719impl TryFrom<AlterRequest> for RegionAlterRequest {
720    type Error = MetadataError;
721
722    fn try_from(value: AlterRequest) -> Result<Self> {
723        let kind = value.kind.context(InvalidRawRegionRequestSnafu {
724            err: "missing kind in AlterRequest",
725        })?;
726
727        let kind = AlterKind::try_from(kind)?;
728        Ok(RegionAlterRequest { kind })
729    }
730}
731
732/// Kind of the alteration.
733#[derive(Debug, PartialEq, Eq, Clone, AsRefStr)]
734pub enum AlterKind {
735    /// Add columns to the region.
736    AddColumns {
737        /// Columns to add.
738        columns: Vec<AddColumn>,
739    },
740    /// Drop columns from the region, only fields are allowed to drop.
741    DropColumns {
742        /// Name of columns to drop.
743        names: Vec<String>,
744    },
745    /// Change columns datatype form the region, only fields are allowed to change.
746    ModifyColumnTypes {
747        /// Columns to change.
748        columns: Vec<ModifyColumnType>,
749    },
750    /// Set region options.
751    SetRegionOptions { options: Vec<SetRegionOption> },
752    /// Unset region options.
753    UnsetRegionOptions { keys: Vec<UnsetRegionOption> },
754    /// Set index options.
755    SetIndexes { options: Vec<SetIndexOption> },
756    /// Unset index options.
757    UnsetIndexes { options: Vec<UnsetIndexOption> },
758    /// Drop column default value.
759    DropDefaults {
760        /// Name of columns to drop.
761        names: Vec<String>,
762    },
763    /// Set column default value.
764    SetDefaults {
765        /// Columns to change.
766        columns: Vec<SetDefault>,
767    },
768    /// Sync column metadatas.
769    SyncColumns {
770        column_metadatas: Vec<ColumnMetadata>,
771    },
772}
773#[derive(Debug, PartialEq, Eq, Clone)]
774pub struct SetDefault {
775    pub name: String,
776    pub default_constraint: Vec<u8>,
777}
778
779#[derive(Debug, PartialEq, Eq, Clone)]
780pub enum SetIndexOption {
781    Fulltext {
782        column_name: String,
783        options: FulltextOptions,
784    },
785    Inverted {
786        column_name: String,
787    },
788    Skipping {
789        column_name: String,
790        options: SkippingIndexOptions,
791    },
792}
793
794impl SetIndexOption {
795    /// Returns the column name of the index option.
796    pub fn column_name(&self) -> &String {
797        match self {
798            SetIndexOption::Fulltext { column_name, .. } => column_name,
799            SetIndexOption::Inverted { column_name } => column_name,
800            SetIndexOption::Skipping { column_name, .. } => column_name,
801        }
802    }
803
804    /// Returns true if the index option is fulltext.
805    pub fn is_fulltext(&self) -> bool {
806        match self {
807            SetIndexOption::Fulltext { .. } => true,
808            SetIndexOption::Inverted { .. } => false,
809            SetIndexOption::Skipping { .. } => false,
810        }
811    }
812}
813
814impl TryFrom<v1::SetIndex> for SetIndexOption {
815    type Error = MetadataError;
816
817    fn try_from(value: v1::SetIndex) -> Result<Self> {
818        let option = value.options.context(InvalidRawRegionRequestSnafu {
819            err: "missing options in SetIndex",
820        })?;
821
822        let opt = match option {
823            v1::set_index::Options::Fulltext(x) => SetIndexOption::Fulltext {
824                column_name: x.column_name.clone(),
825                options: FulltextOptions::new(
826                    x.enable,
827                    as_fulltext_option_analyzer(
828                        Analyzer::try_from(x.analyzer).context(DecodeProtoSnafu)?,
829                    ),
830                    x.case_sensitive,
831                    as_fulltext_option_backend(
832                        PbFulltextBackend::try_from(x.backend).context(DecodeProtoSnafu)?,
833                    ),
834                    x.granularity as u32,
835                    x.false_positive_rate,
836                )
837                .context(InvalidIndexOptionSnafu)?,
838            },
839            v1::set_index::Options::Inverted(i) => SetIndexOption::Inverted {
840                column_name: i.column_name,
841            },
842            v1::set_index::Options::Skipping(s) => SetIndexOption::Skipping {
843                column_name: s.column_name,
844                options: SkippingIndexOptions::new(
845                    s.granularity as u32,
846                    s.false_positive_rate,
847                    as_skipping_index_type(
848                        PbSkippingIndexType::try_from(s.skipping_index_type)
849                            .context(DecodeProtoSnafu)?,
850                    ),
851                )
852                .context(InvalidIndexOptionSnafu)?,
853            },
854        };
855
856        Ok(opt)
857    }
858}
859
860#[derive(Debug, PartialEq, Eq, Clone)]
861pub enum UnsetIndexOption {
862    Fulltext { column_name: String },
863    Inverted { column_name: String },
864    Skipping { column_name: String },
865}
866
867impl UnsetIndexOption {
868    pub fn column_name(&self) -> &String {
869        match self {
870            UnsetIndexOption::Fulltext { column_name } => column_name,
871            UnsetIndexOption::Inverted { column_name } => column_name,
872            UnsetIndexOption::Skipping { column_name } => column_name,
873        }
874    }
875
876    pub fn is_fulltext(&self) -> bool {
877        match self {
878            UnsetIndexOption::Fulltext { .. } => true,
879            UnsetIndexOption::Inverted { .. } => false,
880            UnsetIndexOption::Skipping { .. } => false,
881        }
882    }
883}
884
885impl TryFrom<v1::UnsetIndex> for UnsetIndexOption {
886    type Error = MetadataError;
887
888    fn try_from(value: v1::UnsetIndex) -> Result<Self> {
889        let option = value.options.context(InvalidRawRegionRequestSnafu {
890            err: "missing options in UnsetIndex",
891        })?;
892
893        let opt = match option {
894            v1::unset_index::Options::Fulltext(f) => UnsetIndexOption::Fulltext {
895                column_name: f.column_name,
896            },
897            v1::unset_index::Options::Inverted(i) => UnsetIndexOption::Inverted {
898                column_name: i.column_name,
899            },
900            v1::unset_index::Options::Skipping(s) => UnsetIndexOption::Skipping {
901                column_name: s.column_name,
902            },
903        };
904
905        Ok(opt)
906    }
907}
908
909impl AlterKind {
910    /// Returns an error if the alter kind is invalid.
911    ///
912    /// It allows adding column if not exists and dropping column if exists.
913    pub fn validate(&self, metadata: &RegionMetadata) -> Result<()> {
914        match self {
915            AlterKind::AddColumns { columns } => {
916                for col_to_add in columns {
917                    col_to_add.validate(metadata)?;
918                }
919            }
920            AlterKind::DropColumns { names } => {
921                for name in names {
922                    Self::validate_column_to_drop(name, metadata)?;
923                }
924            }
925            AlterKind::ModifyColumnTypes { columns } => {
926                for col_to_change in columns {
927                    col_to_change.validate(metadata)?;
928                }
929            }
930            AlterKind::SetRegionOptions { .. } => {}
931            AlterKind::UnsetRegionOptions { .. } => {}
932            AlterKind::SetIndexes { options } => {
933                for option in options {
934                    Self::validate_column_alter_index_option(
935                        option.column_name(),
936                        metadata,
937                        option.is_fulltext(),
938                    )?;
939                }
940            }
941            AlterKind::UnsetIndexes { options } => {
942                for option in options {
943                    Self::validate_column_alter_index_option(
944                        option.column_name(),
945                        metadata,
946                        option.is_fulltext(),
947                    )?;
948                }
949            }
950            AlterKind::DropDefaults { names } => {
951                names
952                    .iter()
953                    .try_for_each(|name| Self::validate_column_existence(name, metadata))?;
954            }
955            AlterKind::SetDefaults { columns } => {
956                columns
957                    .iter()
958                    .try_for_each(|col| Self::validate_column_existence(&col.name, metadata))?;
959            }
960            AlterKind::SyncColumns { column_metadatas } => {
961                let new_primary_keys = column_metadatas
962                    .iter()
963                    .filter(|c| c.semantic_type == SemanticType::Tag)
964                    .map(|c| (c.column_schema.name.as_str(), c.column_id))
965                    .collect::<HashMap<_, _>>();
966
967                let old_primary_keys = metadata
968                    .column_metadatas
969                    .iter()
970                    .filter(|c| c.semantic_type == SemanticType::Tag)
971                    .map(|c| (c.column_schema.name.as_str(), c.column_id));
972
973                for (name, id) in old_primary_keys {
974                    let primary_key =
975                        new_primary_keys
976                            .get(name)
977                            .with_context(|| InvalidRegionRequestSnafu {
978                                region_id: metadata.region_id,
979                                err: format!("column {} is not a primary key", name),
980                            })?;
981
982                    ensure!(
983                        *primary_key == id,
984                        InvalidRegionRequestSnafu {
985                            region_id: metadata.region_id,
986                            err: format!(
987                                "column with same name {} has different id, existing: {}, got: {}",
988                                name, id, primary_key
989                            ),
990                        }
991                    );
992                }
993
994                let new_ts_column = column_metadatas
995                    .iter()
996                    .find(|c| c.semantic_type == SemanticType::Timestamp)
997                    .map(|c| (c.column_schema.name.as_str(), c.column_id))
998                    .context(InvalidRegionRequestSnafu {
999                        region_id: metadata.region_id,
1000                        err: "timestamp column not found",
1001                    })?;
1002
1003                // Safety: timestamp column must exist.
1004                let old_ts_column = metadata
1005                    .column_metadatas
1006                    .iter()
1007                    .find(|c| c.semantic_type == SemanticType::Timestamp)
1008                    .map(|c| (c.column_schema.name.as_str(), c.column_id))
1009                    .unwrap();
1010
1011                ensure!(
1012                    new_ts_column == old_ts_column,
1013                    InvalidRegionRequestSnafu {
1014                        region_id: metadata.region_id,
1015                        err: format!(
1016                            "timestamp column {} has different id, existing: {}, got: {}",
1017                            old_ts_column.0, old_ts_column.1, new_ts_column.1
1018                        ),
1019                    }
1020                );
1021            }
1022        }
1023        Ok(())
1024    }
1025
1026    /// Returns true if we need to apply the alteration to the region.
1027    pub fn need_alter(&self, metadata: &RegionMetadata) -> bool {
1028        debug_assert!(self.validate(metadata).is_ok());
1029        match self {
1030            AlterKind::AddColumns { columns } => columns
1031                .iter()
1032                .any(|col_to_add| col_to_add.need_alter(metadata)),
1033            AlterKind::DropColumns { names } => names
1034                .iter()
1035                .any(|name| metadata.column_by_name(name).is_some()),
1036            AlterKind::ModifyColumnTypes { columns } => columns
1037                .iter()
1038                .any(|col_to_change| col_to_change.need_alter(metadata)),
1039            AlterKind::SetRegionOptions { .. } => true,
1040            AlterKind::UnsetRegionOptions { .. } => true,
1041            AlterKind::SetIndexes { options, .. } => options
1042                .iter()
1043                .any(|option| metadata.column_by_name(option.column_name()).is_some()),
1044            AlterKind::UnsetIndexes { options } => options
1045                .iter()
1046                .any(|option| metadata.column_by_name(option.column_name()).is_some()),
1047            AlterKind::DropDefaults { names } => names
1048                .iter()
1049                .any(|name| metadata.column_by_name(name).is_some()),
1050
1051            AlterKind::SetDefaults { columns } => columns
1052                .iter()
1053                .any(|x| metadata.column_by_name(&x.name).is_some()),
1054            AlterKind::SyncColumns { column_metadatas } => {
1055                metadata.column_metadatas != *column_metadatas
1056            }
1057        }
1058    }
1059
1060    /// Returns an error if the column to drop is invalid.
1061    fn validate_column_to_drop(name: &str, metadata: &RegionMetadata) -> Result<()> {
1062        let Some(column) = metadata.column_by_name(name) else {
1063            return Ok(());
1064        };
1065        ensure!(
1066            column.semantic_type == SemanticType::Field,
1067            InvalidRegionRequestSnafu {
1068                region_id: metadata.region_id,
1069                err: format!("column {} is not a field and could not be dropped", name),
1070            }
1071        );
1072        Ok(())
1073    }
1074
1075    /// Returns an error if the column's alter index option is invalid.
1076    fn validate_column_alter_index_option(
1077        column_name: &String,
1078        metadata: &RegionMetadata,
1079        is_fulltext: bool,
1080    ) -> Result<()> {
1081        let column = metadata
1082            .column_by_name(column_name)
1083            .context(InvalidRegionRequestSnafu {
1084                region_id: metadata.region_id,
1085                err: format!("column {} not found", column_name),
1086            })?;
1087
1088        if is_fulltext {
1089            ensure!(
1090                column.column_schema.data_type.is_string(),
1091                InvalidRegionRequestSnafu {
1092                    region_id: metadata.region_id,
1093                    err: format!(
1094                        "cannot change alter index options for non-string column {}",
1095                        column_name
1096                    ),
1097                }
1098            );
1099        }
1100
1101        Ok(())
1102    }
1103
1104    /// Returns an error if the column isn't exist.
1105    fn validate_column_existence(column_name: &String, metadata: &RegionMetadata) -> Result<()> {
1106        metadata
1107            .column_by_name(column_name)
1108            .context(InvalidRegionRequestSnafu {
1109                region_id: metadata.region_id,
1110                err: format!("column {} not found", column_name),
1111            })?;
1112
1113        Ok(())
1114    }
1115}
1116
1117impl TryFrom<alter_request::Kind> for AlterKind {
1118    type Error = MetadataError;
1119
1120    fn try_from(kind: alter_request::Kind) -> Result<Self> {
1121        let alter_kind = match kind {
1122            alter_request::Kind::AddColumns(x) => {
1123                let columns = x
1124                    .add_columns
1125                    .into_iter()
1126                    .map(|x| x.try_into())
1127                    .collect::<Result<Vec<_>>>()?;
1128                AlterKind::AddColumns { columns }
1129            }
1130            alter_request::Kind::ModifyColumnTypes(x) => {
1131                let columns = x
1132                    .modify_column_types
1133                    .into_iter()
1134                    .map(|x| x.into())
1135                    .collect::<Vec<_>>();
1136                AlterKind::ModifyColumnTypes { columns }
1137            }
1138            alter_request::Kind::DropColumns(x) => {
1139                let names = x.drop_columns.into_iter().map(|x| x.name).collect();
1140                AlterKind::DropColumns { names }
1141            }
1142            alter_request::Kind::SetTableOptions(options) => AlterKind::SetRegionOptions {
1143                options: options
1144                    .table_options
1145                    .iter()
1146                    .map(TryFrom::try_from)
1147                    .collect::<Result<Vec<_>>>()?,
1148            },
1149            alter_request::Kind::UnsetTableOptions(options) => AlterKind::UnsetRegionOptions {
1150                keys: options
1151                    .keys
1152                    .iter()
1153                    .map(|key| UnsetRegionOption::try_from(key.as_str()))
1154                    .collect::<Result<Vec<_>>>()?,
1155            },
1156            alter_request::Kind::SetIndex(o) => AlterKind::SetIndexes {
1157                options: vec![SetIndexOption::try_from(o)?],
1158            },
1159            alter_request::Kind::UnsetIndex(o) => AlterKind::UnsetIndexes {
1160                options: vec![UnsetIndexOption::try_from(o)?],
1161            },
1162            alter_request::Kind::SetIndexes(o) => AlterKind::SetIndexes {
1163                options: o
1164                    .set_indexes
1165                    .into_iter()
1166                    .map(SetIndexOption::try_from)
1167                    .collect::<Result<Vec<_>>>()?,
1168            },
1169            alter_request::Kind::UnsetIndexes(o) => AlterKind::UnsetIndexes {
1170                options: o
1171                    .unset_indexes
1172                    .into_iter()
1173                    .map(UnsetIndexOption::try_from)
1174                    .collect::<Result<Vec<_>>>()?,
1175            },
1176            alter_request::Kind::DropDefaults(x) => AlterKind::DropDefaults {
1177                names: x.drop_defaults.into_iter().map(|x| x.column_name).collect(),
1178            },
1179            alter_request::Kind::SetDefaults(x) => AlterKind::SetDefaults {
1180                columns: x
1181                    .set_defaults
1182                    .into_iter()
1183                    .map(|x| {
1184                        Ok(SetDefault {
1185                            name: x.column_name,
1186                            default_constraint: x.default_constraint.clone(),
1187                        })
1188                    })
1189                    .collect::<Result<Vec<_>>>()?,
1190            },
1191            alter_request::Kind::SyncColumns(x) => AlterKind::SyncColumns {
1192                column_metadatas: x
1193                    .column_defs
1194                    .into_iter()
1195                    .map(ColumnMetadata::try_from_column_def)
1196                    .collect::<Result<Vec<_>>>()?,
1197            },
1198        };
1199
1200        Ok(alter_kind)
1201    }
1202}
1203
1204/// Adds a column.
1205#[derive(Debug, PartialEq, Eq, Clone)]
1206pub struct AddColumn {
1207    /// Metadata of the column to add.
1208    pub column_metadata: ColumnMetadata,
1209    /// Location to add the column. If location is None, the region adds
1210    /// the column to the last.
1211    pub location: Option<AddColumnLocation>,
1212}
1213
1214impl AddColumn {
1215    /// Returns an error if the column to add is invalid.
1216    ///
1217    /// It allows adding existing columns. However, the existing column must have the same metadata
1218    /// and the location must be None.
1219    pub fn validate(&self, metadata: &RegionMetadata) -> Result<()> {
1220        ensure!(
1221            self.column_metadata.column_schema.is_nullable()
1222                || self
1223                    .column_metadata
1224                    .column_schema
1225                    .default_constraint()
1226                    .is_some(),
1227            InvalidRegionRequestSnafu {
1228                region_id: metadata.region_id,
1229                err: format!(
1230                    "no default value for column {}",
1231                    self.column_metadata.column_schema.name
1232                ),
1233            }
1234        );
1235
1236        if let Some(existing_column) =
1237            metadata.column_by_name(&self.column_metadata.column_schema.name)
1238        {
1239            // If the column already exists.
1240            ensure!(
1241                *existing_column == self.column_metadata,
1242                InvalidRegionRequestSnafu {
1243                    region_id: metadata.region_id,
1244                    err: format!(
1245                        "column {} already exists with different metadata, existing: {:?}, got: {:?}",
1246                        self.column_metadata.column_schema.name,
1247                        existing_column,
1248                        self.column_metadata,
1249                    ),
1250                }
1251            );
1252            ensure!(
1253                self.location.is_none(),
1254                InvalidRegionRequestSnafu {
1255                    region_id: metadata.region_id,
1256                    err: format!(
1257                        "column {} already exists, but location is specified",
1258                        self.column_metadata.column_schema.name
1259                    ),
1260                }
1261            );
1262        }
1263
1264        if let Some(existing_column) = metadata.column_by_id(self.column_metadata.column_id) {
1265            // Ensures the existing column has the same name.
1266            ensure!(
1267                existing_column.column_schema.name == self.column_metadata.column_schema.name,
1268                InvalidRegionRequestSnafu {
1269                    region_id: metadata.region_id,
1270                    err: format!(
1271                        "column id {} already exists with different name {}",
1272                        self.column_metadata.column_id, existing_column.column_schema.name
1273                    ),
1274                }
1275            );
1276        }
1277
1278        Ok(())
1279    }
1280
1281    /// Returns true if no column to add to the region.
1282    pub fn need_alter(&self, metadata: &RegionMetadata) -> bool {
1283        debug_assert!(self.validate(metadata).is_ok());
1284        metadata
1285            .column_by_name(&self.column_metadata.column_schema.name)
1286            .is_none()
1287    }
1288}
1289
1290impl TryFrom<v1::region::AddColumn> for AddColumn {
1291    type Error = MetadataError;
1292
1293    fn try_from(add_column: v1::region::AddColumn) -> Result<Self> {
1294        let column_def = add_column
1295            .column_def
1296            .context(InvalidRawRegionRequestSnafu {
1297                err: "missing column_def in AddColumn",
1298            })?;
1299
1300        let column_metadata = ColumnMetadata::try_from_column_def(column_def)?;
1301        let location = add_column
1302            .location
1303            .map(AddColumnLocation::try_from)
1304            .transpose()?;
1305
1306        Ok(AddColumn {
1307            column_metadata,
1308            location,
1309        })
1310    }
1311}
1312
1313/// Location to add a column.
1314#[derive(Debug, PartialEq, Eq, Clone)]
1315pub enum AddColumnLocation {
1316    /// Add the column to the first position of columns.
1317    First,
1318    /// Add the column after specific column.
1319    After {
1320        /// Add the column after this column.
1321        column_name: String,
1322    },
1323}
1324
1325impl TryFrom<v1::AddColumnLocation> for AddColumnLocation {
1326    type Error = MetadataError;
1327
1328    fn try_from(location: v1::AddColumnLocation) -> Result<Self> {
1329        let location_type = LocationType::try_from(location.location_type)
1330            .map_err(|e| InvalidRawRegionRequestSnafu { err: e.to_string() }.build())?;
1331        let add_column_location = match location_type {
1332            LocationType::First => AddColumnLocation::First,
1333            LocationType::After => AddColumnLocation::After {
1334                column_name: location.after_column_name,
1335            },
1336        };
1337
1338        Ok(add_column_location)
1339    }
1340}
1341
1342/// Change a column's datatype.
1343#[derive(Debug, PartialEq, Eq, Clone)]
1344pub struct ModifyColumnType {
1345    /// Schema of the column to modify.
1346    pub column_name: String,
1347    /// Column will be changed to this type.
1348    pub target_type: ConcreteDataType,
1349}
1350
1351impl ModifyColumnType {
1352    /// Returns an error if the column's datatype to change is invalid.
1353    pub fn validate(&self, metadata: &RegionMetadata) -> Result<()> {
1354        let column_meta = metadata
1355            .column_by_name(&self.column_name)
1356            .with_context(|| InvalidRegionRequestSnafu {
1357                region_id: metadata.region_id,
1358                err: format!("column {} not found", self.column_name),
1359            })?;
1360
1361        ensure!(
1362            matches!(column_meta.semantic_type, SemanticType::Field),
1363            InvalidRegionRequestSnafu {
1364                region_id: metadata.region_id,
1365                err: "'timestamp' or 'tag' column cannot change type".to_string()
1366            }
1367        );
1368        ensure!(
1369            column_meta
1370                .column_schema
1371                .data_type
1372                .can_arrow_type_cast_to(&self.target_type),
1373            InvalidRegionRequestSnafu {
1374                region_id: metadata.region_id,
1375                err: format!(
1376                    "column '{}' cannot be cast automatically to type '{}'",
1377                    self.column_name, self.target_type
1378                ),
1379            }
1380        );
1381
1382        Ok(())
1383    }
1384
1385    /// Returns true if no column's datatype to change to the region.
1386    pub fn need_alter(&self, metadata: &RegionMetadata) -> bool {
1387        debug_assert!(self.validate(metadata).is_ok());
1388        metadata.column_by_name(&self.column_name).is_some()
1389    }
1390}
1391
1392impl From<v1::ModifyColumnType> for ModifyColumnType {
1393    fn from(modify_column_type: v1::ModifyColumnType) -> Self {
1394        let target_type = ColumnDataTypeWrapper::new(
1395            modify_column_type.target_type(),
1396            modify_column_type.target_type_extension,
1397        )
1398        .into();
1399
1400        ModifyColumnType {
1401            column_name: modify_column_type.column_name,
1402            target_type,
1403        }
1404    }
1405}
1406
1407#[derive(Debug, Eq, PartialEq, Clone, Serialize, Deserialize)]
1408pub enum SetRegionOption {
1409    WriteBufferSize(Option<ReadableSize>),
1410    Ttl(Option<TimeToLive>),
1411    // Modifying TwscOptions with values as (option name, new value).
1412    Twsc(String, String),
1413    // Modifying the SST format.
1414    Format(String),
1415    // Modifying the append mode.
1416    AppendMode(bool),
1417    // Modifying the per-region auto flush interval override.
1418    AutoFlushInterval(Option<Duration>),
1419}
1420
1421impl TryFrom<&PbOption> for SetRegionOption {
1422    type Error = MetadataError;
1423
1424    fn try_from(value: &PbOption) -> std::result::Result<Self, Self::Error> {
1425        let PbOption { key, value } = value;
1426        match key.as_str() {
1427            WRITE_BUFFER_SIZE_KEY => {
1428                let size = value
1429                    .parse::<ReadableSize>()
1430                    .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?;
1431                Ok(Self::WriteBufferSize(Some(size)))
1432            }
1433            TTL_KEY => {
1434                let ttl = TimeToLive::from_humantime_or_str(value)
1435                    .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?;
1436
1437                Ok(Self::Ttl(Some(ttl)))
1438            }
1439            TWCS_TRIGGER_FILE_NUM | TWCS_MAX_OUTPUT_FILE_SIZE | TWCS_TIME_WINDOW => {
1440                Ok(Self::Twsc(key.clone(), value.clone()))
1441            }
1442            SST_FORMAT_KEY => Ok(Self::Format(value.clone())),
1443            APPEND_MODE_KEY => {
1444                let append_mode = value
1445                    .parse::<bool>()
1446                    .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?;
1447                Ok(Self::AppendMode(append_mode))
1448            }
1449            AUTO_FLUSH_INTERVAL_KEY => {
1450                if value.is_empty() {
1451                    // SET 'auto_flush_interval' = NULL comes through as an empty
1452                    // string; treat it as clearing the override (fall back to
1453                    // the global default), same as Ttl.
1454                    return Ok(Self::AutoFlushInterval(None));
1455                }
1456                let interval = humantime::parse_duration(value)
1457                    .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?;
1458                if interval <= Duration::ZERO {
1459                    return InvalidSetRegionOptionRequestSnafu { key, value }.fail();
1460                }
1461                Ok(Self::AutoFlushInterval(Some(interval)))
1462            }
1463            _ => InvalidSetRegionOptionRequestSnafu { key, value }.fail(),
1464        }
1465    }
1466}
1467
1468impl From<&UnsetRegionOption> for SetRegionOption {
1469    fn from(unset_option: &UnsetRegionOption) -> Self {
1470        match unset_option {
1471            UnsetRegionOption::TwcsTriggerFileNum => {
1472                SetRegionOption::Twsc(unset_option.to_string(), String::new())
1473            }
1474            UnsetRegionOption::TwcsMaxOutputFileSize => {
1475                SetRegionOption::Twsc(unset_option.to_string(), String::new())
1476            }
1477            UnsetRegionOption::TwcsTimeWindow => {
1478                SetRegionOption::Twsc(unset_option.to_string(), String::new())
1479            }
1480            UnsetRegionOption::Ttl => SetRegionOption::Ttl(Default::default()),
1481            UnsetRegionOption::WriteBufferSize => SetRegionOption::WriteBufferSize(None),
1482        }
1483    }
1484}
1485
1486impl TryFrom<&str> for UnsetRegionOption {
1487    type Error = MetadataError;
1488
1489    fn try_from(key: &str) -> Result<Self> {
1490        match key.to_ascii_lowercase().as_str() {
1491            TTL_KEY => Ok(Self::Ttl),
1492            WRITE_BUFFER_SIZE_KEY => Ok(Self::WriteBufferSize),
1493            TWCS_TRIGGER_FILE_NUM => Ok(Self::TwcsTriggerFileNum),
1494            TWCS_MAX_OUTPUT_FILE_SIZE => Ok(Self::TwcsMaxOutputFileSize),
1495            TWCS_TIME_WINDOW => Ok(Self::TwcsTimeWindow),
1496            _ => InvalidUnsetRegionOptionRequestSnafu { key }.fail(),
1497        }
1498    }
1499}
1500
1501#[derive(Debug, Eq, PartialEq, Clone, Serialize, Deserialize)]
1502pub enum UnsetRegionOption {
1503    TwcsTriggerFileNum,
1504    TwcsMaxOutputFileSize,
1505    TwcsTimeWindow,
1506    Ttl,
1507    WriteBufferSize,
1508}
1509
1510impl UnsetRegionOption {
1511    pub fn as_str(&self) -> &str {
1512        match self {
1513            Self::Ttl => TTL_KEY,
1514            Self::WriteBufferSize => WRITE_BUFFER_SIZE_KEY,
1515            Self::TwcsTriggerFileNum => TWCS_TRIGGER_FILE_NUM,
1516            Self::TwcsMaxOutputFileSize => TWCS_MAX_OUTPUT_FILE_SIZE,
1517            Self::TwcsTimeWindow => TWCS_TIME_WINDOW,
1518        }
1519    }
1520}
1521
1522impl Display for UnsetRegionOption {
1523    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1524        write!(f, "{}", self.as_str())
1525    }
1526}
1527
1528#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
1529pub enum RegionFlushReason {
1530    /// Flush triggered before region migration.
1531    RegionMigration,
1532    /// Flush triggered by repartition procedure.
1533    Repartition,
1534    /// Flush triggered by remote WAL pruning.
1535    RemoteWalPrune,
1536    /// Flush region before closing region.
1537    Closing,
1538    /// Flush region before downgrading region.
1539    Downgrading,
1540}
1541
1542#[derive(Debug, Clone, Default)]
1543pub struct RegionFlushRequest {
1544    pub row_group_size: Option<usize>,
1545    pub reason: Option<RegionFlushReason>,
1546}
1547
1548#[derive(Debug)]
1549pub struct RegionCompactRequest {
1550    pub options: compact_request::Options,
1551    pub parallelism: Option<u32>,
1552}
1553
1554impl Default for RegionCompactRequest {
1555    fn default() -> Self {
1556        Self {
1557            // Default to regular compaction.
1558            options: compact_request::Options::Regular(Default::default()),
1559            parallelism: None,
1560        }
1561    }
1562}
1563
1564#[derive(Debug, Clone, Default)]
1565pub struct RegionBuildIndexRequest {}
1566
1567/// Truncate region request.
1568#[derive(Debug)]
1569pub enum RegionTruncateRequest {
1570    /// Truncate all data in the region.
1571    All,
1572    ByTimeRanges {
1573        /// Time ranges to truncate. Both bound are inclusive.
1574        /// only files that are fully contained in the time range will be truncated.
1575        /// so no guarantee that all data in the time range will be truncated.
1576        time_ranges: Vec<(Timestamp, Timestamp)>,
1577    },
1578}
1579
1580/// Catchup region request.
1581///
1582/// Makes a readonly region to catch up to leader region changes.
1583/// There is no effect if it operating on a leader region.
1584#[derive(Debug, Clone, Copy, Default)]
1585pub struct RegionCatchupRequest {
1586    /// Sets it to writable if it's available after it has caught up with all changes.
1587    pub set_writable: bool,
1588    /// The `entry_id` that was expected to reply to.
1589    /// `None` stands replaying to latest.
1590    pub entry_id: Option<entry::Id>,
1591    /// Used for metrics metadata region.
1592    /// The `entry_id` that was expected to reply to.
1593    /// `None` stands replaying to latest.
1594    pub metadata_entry_id: Option<entry::Id>,
1595    /// The hint for replaying memtable.
1596    pub location_id: Option<u64>,
1597    /// Replay checkpoint.
1598    pub checkpoint: Option<ReplayCheckpoint>,
1599}
1600
1601#[derive(Debug, Clone)]
1602pub struct RegionBulkInsertsRequest {
1603    pub region_id: RegionId,
1604    pub payload: DfRecordBatch,
1605    pub raw_data: ArrowIpc,
1606    pub partition_expr_version: Option<u64>,
1607    pub aligned_schema_version: Option<u64>,
1608}
1609
1610impl RegionBulkInsertsRequest {
1611    pub fn estimated_size(&self) -> usize {
1612        self.payload.get_array_memory_size()
1613    }
1614}
1615
1616/// Request to stage a region with a new partition directive.
1617///
1618/// This request transitions a region into the staging mode.
1619/// It first flushes the memtable for the old partition expression if it is not
1620/// empty, then enters the staging mode with the new directive.
1621#[derive(Debug, Clone, PartialEq, Eq)]
1622pub enum StagingPartitionDirective {
1623    UpdatePartitionExpr(String),
1624    RejectAllWrites,
1625}
1626
1627impl StagingPartitionDirective {
1628    /// Returns the partition expression carried by this directive, if any.
1629    pub fn partition_expr(&self) -> Option<&str> {
1630        match self {
1631            Self::UpdatePartitionExpr(expr) => Some(expr),
1632            Self::RejectAllWrites => None,
1633        }
1634    }
1635}
1636
1637#[derive(Debug, Clone)]
1638pub struct EnterStagingRequest {
1639    /// The staging partition directive of the region.
1640    pub partition_directive: StagingPartitionDirective,
1641}
1642
1643impl EnterStagingRequest {
1644    /// Builds an enter-staging request with a partition expression directive.
1645    pub fn with_partition_expr(partition_expr: String) -> Self {
1646        Self {
1647            partition_directive: StagingPartitionDirective::UpdatePartitionExpr(partition_expr),
1648        }
1649    }
1650}
1651
1652/// This request is used as part of the region repartition.
1653///
1654/// After a region has entered staging mode with a new partition expression
1655/// expression) and a separate process (for example, `remap_manifests`) has
1656/// generated the new file assignments for the staging region, this request
1657/// applies that generated manifest to the region.
1658///
1659/// In practice, this means:
1660/// - The `partition_expr` identifies the staging partition expression that the manifest
1661///   was generated for.
1662/// - `central_region_id` specifies which region holds the staging blob storage
1663///   where the manifest was written during the `remap_manifests` operation.
1664/// - `manifest_path` is the relative path within the central region's staging
1665///   blob storage to fetch the generated manifest.
1666///
1667/// It should typically be called **after** the staging region has been
1668/// initialized by [`EnterStagingRequest`] and the new file layout has been
1669/// computed, to finalize the repartition operation.
1670#[derive(Debug, Clone)]
1671pub struct ApplyStagingManifestRequest {
1672    /// The partition expression of the staging region.
1673    pub partition_expr: String,
1674    /// The region that stores the staging manifests in its staging blob storage.
1675    pub central_region_id: RegionId,
1676    /// The relative path to the staging manifest within the central region's
1677    /// staging blob storage.
1678    pub manifest_path: String,
1679}
1680
1681impl fmt::Display for RegionRequest {
1682    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1683        match self {
1684            RegionRequest::Put(_) => write!(f, "Put"),
1685            RegionRequest::Delete(_) => write!(f, "Delete"),
1686            RegionRequest::Create(_) => write!(f, "Create"),
1687            RegionRequest::Drop(_) => write!(f, "Drop"),
1688            RegionRequest::Open(_) => write!(f, "Open"),
1689            RegionRequest::CleanUp(_) => write!(f, "CleanUp"),
1690            RegionRequest::Close(_) => write!(f, "Close"),
1691            RegionRequest::Alter(_) => write!(f, "Alter"),
1692            RegionRequest::Flush(_) => write!(f, "Flush"),
1693            RegionRequest::Compact(_) => write!(f, "Compact"),
1694            RegionRequest::BuildIndex(_) => write!(f, "BuildIndex"),
1695            RegionRequest::Truncate(_) => write!(f, "Truncate"),
1696            RegionRequest::Catchup(_) => write!(f, "Catchup"),
1697            RegionRequest::BulkInserts(_) => write!(f, "BulkInserts"),
1698            RegionRequest::EnterStaging(_) => write!(f, "EnterStaging"),
1699            RegionRequest::ApplyStagingManifest(_) => write!(f, "ApplyStagingManifest"),
1700        }
1701    }
1702}
1703
1704#[cfg(test)]
1705mod tests {
1706
1707    use api::v1::region::RegionColumnDef;
1708    use api::v1::{ColumnDataType, ColumnDef};
1709    use datatypes::prelude::ConcreteDataType;
1710    use datatypes::schema::{ColumnSchema, FulltextAnalyzer, FulltextBackend};
1711
1712    use super::*;
1713    use crate::metadata::RegionMetadataBuilder;
1714
1715    #[test]
1716    fn test_from_proto_location() {
1717        let proto_location = v1::AddColumnLocation {
1718            location_type: LocationType::First as i32,
1719            after_column_name: String::default(),
1720        };
1721        let location = AddColumnLocation::try_from(proto_location).unwrap();
1722        assert_eq!(location, AddColumnLocation::First);
1723
1724        let proto_location = v1::AddColumnLocation {
1725            location_type: 10,
1726            after_column_name: String::default(),
1727        };
1728        AddColumnLocation::try_from(proto_location).unwrap_err();
1729
1730        let proto_location = v1::AddColumnLocation {
1731            location_type: LocationType::After as i32,
1732            after_column_name: "a".to_string(),
1733        };
1734        let location = AddColumnLocation::try_from(proto_location).unwrap();
1735        assert_eq!(
1736            location,
1737            AddColumnLocation::After {
1738                column_name: "a".to_string()
1739            }
1740        );
1741    }
1742
1743    #[test]
1744    fn test_from_none_proto_add_column() {
1745        AddColumn::try_from(v1::region::AddColumn {
1746            column_def: None,
1747            location: None,
1748        })
1749        .unwrap_err();
1750    }
1751
1752    #[test]
1753    fn test_set_region_option_auto_flush_interval_try_from() {
1754        use std::time::Duration;
1755
1756        // Valid duration
1757        let pb = PbOption {
1758            key: "auto_flush_interval".to_string(),
1759            value: "5m".to_string(),
1760        };
1761        let opt = SetRegionOption::try_from(&pb).unwrap();
1762        assert_eq!(
1763            opt,
1764            SetRegionOption::AutoFlushInterval(Some(Duration::from_secs(300)))
1765        );
1766
1767        // Empty value clears the override (mirrors Ttl's behaviour for `SET key = NULL`).
1768        let pb = PbOption {
1769            key: "auto_flush_interval".to_string(),
1770            value: String::new(),
1771        };
1772        let opt = SetRegionOption::try_from(&pb).unwrap();
1773        assert_eq!(opt, SetRegionOption::AutoFlushInterval(None));
1774
1775        // Zero is rejected up front (engine invariant).
1776        let pb = PbOption {
1777            key: "auto_flush_interval".to_string(),
1778            value: "0s".to_string(),
1779        };
1780        assert!(SetRegionOption::try_from(&pb).is_err());
1781
1782        // Garbage value is rejected.
1783        let pb = PbOption {
1784            key: "auto_flush_interval".to_string(),
1785            value: "not_a_duration".to_string(),
1786        };
1787        assert!(SetRegionOption::try_from(&pb).is_err());
1788    }
1789
1790    #[test]
1791    fn test_from_proto_alter_request() {
1792        RegionAlterRequest::try_from(AlterRequest {
1793            region_id: 0,
1794            schema_version: 1,
1795            kind: None,
1796        })
1797        .unwrap_err();
1798
1799        let request = RegionAlterRequest::try_from(AlterRequest {
1800            region_id: 0,
1801            schema_version: 1,
1802            kind: Some(alter_request::Kind::AddColumns(v1::region::AddColumns {
1803                add_columns: vec![v1::region::AddColumn {
1804                    column_def: Some(RegionColumnDef {
1805                        column_def: Some(ColumnDef {
1806                            name: "a".to_string(),
1807                            data_type: ColumnDataType::String as i32,
1808                            is_nullable: true,
1809                            default_constraint: vec![],
1810                            semantic_type: SemanticType::Field as i32,
1811                            comment: String::new(),
1812                            ..Default::default()
1813                        }),
1814                        column_id: 1,
1815                    }),
1816                    location: Some(v1::AddColumnLocation {
1817                        location_type: LocationType::First as i32,
1818                        after_column_name: String::default(),
1819                    }),
1820                }],
1821            })),
1822        })
1823        .unwrap();
1824
1825        assert_eq!(
1826            request,
1827            RegionAlterRequest {
1828                kind: AlterKind::AddColumns {
1829                    columns: vec![AddColumn {
1830                        column_metadata: ColumnMetadata {
1831                            column_schema: ColumnSchema::new(
1832                                "a",
1833                                ConcreteDataType::string_datatype(),
1834                                true,
1835                            ),
1836                            semantic_type: SemanticType::Field,
1837                            column_id: 1,
1838                        },
1839                        location: Some(AddColumnLocation::First),
1840                    }]
1841                },
1842            }
1843        );
1844    }
1845
1846    #[test]
1847    fn test_write_buffer_size_region_options() {
1848        let option = PbOption {
1849            key: WRITE_BUFFER_SIZE_KEY.to_string(),
1850            value: "128MiB".to_string(),
1851        };
1852        assert_eq!(
1853            SetRegionOption::WriteBufferSize(Some(ReadableSize::mb(128))),
1854            SetRegionOption::try_from(&option).unwrap()
1855        );
1856
1857        let option = PbOption {
1858            key: WRITE_BUFFER_SIZE_KEY.to_string(),
1859            value: "invalid".to_string(),
1860        };
1861        SetRegionOption::try_from(&option).unwrap_err();
1862
1863        // Clearing the option uses UNSET. Empty SET values, including SQL NULL,
1864        // remain invalid because the SQL layer does not distinguish NULL from ''.
1865        let option = PbOption {
1866            key: WRITE_BUFFER_SIZE_KEY.to_string(),
1867            value: String::new(),
1868        };
1869        SetRegionOption::try_from(&option).unwrap_err();
1870
1871        assert_eq!(
1872            UnsetRegionOption::WriteBufferSize,
1873            UnsetRegionOption::try_from(WRITE_BUFFER_SIZE_KEY).unwrap()
1874        );
1875        assert_eq!(
1876            SetRegionOption::WriteBufferSize(None),
1877            SetRegionOption::from(&UnsetRegionOption::WriteBufferSize)
1878        );
1879    }
1880
1881    /// Returns a new region metadata for testing. Metadata:
1882    /// `[(ts, ms, 1), (tag_0, string, 2), (field_0, string, 3), (field_1, bool, 4)]`
1883    fn new_metadata() -> RegionMetadata {
1884        let mut builder = RegionMetadataBuilder::new(RegionId::new(1, 1));
1885        builder
1886            .push_column_metadata(ColumnMetadata {
1887                column_schema: ColumnSchema::new(
1888                    "ts",
1889                    ConcreteDataType::timestamp_millisecond_datatype(),
1890                    false,
1891                ),
1892                semantic_type: SemanticType::Timestamp,
1893                column_id: 1,
1894            })
1895            .push_column_metadata(ColumnMetadata {
1896                column_schema: ColumnSchema::new(
1897                    "tag_0",
1898                    ConcreteDataType::string_datatype(),
1899                    true,
1900                ),
1901                semantic_type: SemanticType::Tag,
1902                column_id: 2,
1903            })
1904            .push_column_metadata(ColumnMetadata {
1905                column_schema: ColumnSchema::new(
1906                    "field_0",
1907                    ConcreteDataType::string_datatype(),
1908                    true,
1909                ),
1910                semantic_type: SemanticType::Field,
1911                column_id: 3,
1912            })
1913            .push_column_metadata(ColumnMetadata {
1914                column_schema: ColumnSchema::new(
1915                    "field_1",
1916                    ConcreteDataType::boolean_datatype(),
1917                    true,
1918                ),
1919                semantic_type: SemanticType::Field,
1920                column_id: 4,
1921            })
1922            .primary_key(vec![2]);
1923        builder.build().unwrap()
1924    }
1925
1926    #[test]
1927    fn test_add_column_validate() {
1928        let metadata = new_metadata();
1929        let add_column = AddColumn {
1930            column_metadata: ColumnMetadata {
1931                column_schema: ColumnSchema::new(
1932                    "tag_1",
1933                    ConcreteDataType::string_datatype(),
1934                    true,
1935                ),
1936                semantic_type: SemanticType::Tag,
1937                column_id: 5,
1938            },
1939            location: None,
1940        };
1941        add_column.validate(&metadata).unwrap();
1942        assert!(add_column.need_alter(&metadata));
1943
1944        // Add not null column.
1945        AddColumn {
1946            column_metadata: ColumnMetadata {
1947                column_schema: ColumnSchema::new(
1948                    "tag_1",
1949                    ConcreteDataType::string_datatype(),
1950                    false,
1951                ),
1952                semantic_type: SemanticType::Tag,
1953                column_id: 5,
1954            },
1955            location: None,
1956        }
1957        .validate(&metadata)
1958        .unwrap_err();
1959
1960        // Add existing column.
1961        let add_column = AddColumn {
1962            column_metadata: ColumnMetadata {
1963                column_schema: ColumnSchema::new(
1964                    "tag_0",
1965                    ConcreteDataType::string_datatype(),
1966                    true,
1967                ),
1968                semantic_type: SemanticType::Tag,
1969                column_id: 2,
1970            },
1971            location: None,
1972        };
1973        add_column.validate(&metadata).unwrap();
1974        assert!(!add_column.need_alter(&metadata));
1975    }
1976
1977    #[test]
1978    fn test_add_duplicate_columns() {
1979        let kind = AlterKind::AddColumns {
1980            columns: vec![
1981                AddColumn {
1982                    column_metadata: ColumnMetadata {
1983                        column_schema: ColumnSchema::new(
1984                            "tag_1",
1985                            ConcreteDataType::string_datatype(),
1986                            true,
1987                        ),
1988                        semantic_type: SemanticType::Tag,
1989                        column_id: 5,
1990                    },
1991                    location: None,
1992                },
1993                AddColumn {
1994                    column_metadata: ColumnMetadata {
1995                        column_schema: ColumnSchema::new(
1996                            "tag_1",
1997                            ConcreteDataType::string_datatype(),
1998                            true,
1999                        ),
2000                        semantic_type: SemanticType::Field,
2001                        column_id: 6,
2002                    },
2003                    location: None,
2004                },
2005            ],
2006        };
2007        let metadata = new_metadata();
2008        kind.validate(&metadata).unwrap();
2009        assert!(kind.need_alter(&metadata));
2010    }
2011
2012    #[test]
2013    fn test_add_existing_column_different_metadata() {
2014        let metadata = new_metadata();
2015
2016        // Add existing column with different id.
2017        let kind = AlterKind::AddColumns {
2018            columns: vec![AddColumn {
2019                column_metadata: ColumnMetadata {
2020                    column_schema: ColumnSchema::new(
2021                        "tag_0",
2022                        ConcreteDataType::string_datatype(),
2023                        true,
2024                    ),
2025                    semantic_type: SemanticType::Tag,
2026                    column_id: 4,
2027                },
2028                location: None,
2029            }],
2030        };
2031        kind.validate(&metadata).unwrap_err();
2032
2033        // Add existing column with different type.
2034        let kind = AlterKind::AddColumns {
2035            columns: vec![AddColumn {
2036                column_metadata: ColumnMetadata {
2037                    column_schema: ColumnSchema::new(
2038                        "tag_0",
2039                        ConcreteDataType::int64_datatype(),
2040                        true,
2041                    ),
2042                    semantic_type: SemanticType::Tag,
2043                    column_id: 2,
2044                },
2045                location: None,
2046            }],
2047        };
2048        kind.validate(&metadata).unwrap_err();
2049
2050        // Add existing column with different name.
2051        let kind = AlterKind::AddColumns {
2052            columns: vec![AddColumn {
2053                column_metadata: ColumnMetadata {
2054                    column_schema: ColumnSchema::new(
2055                        "tag_1",
2056                        ConcreteDataType::string_datatype(),
2057                        true,
2058                    ),
2059                    semantic_type: SemanticType::Tag,
2060                    column_id: 2,
2061                },
2062                location: None,
2063            }],
2064        };
2065        kind.validate(&metadata).unwrap_err();
2066    }
2067
2068    #[test]
2069    fn test_add_existing_column_with_location() {
2070        let metadata = new_metadata();
2071        let kind = AlterKind::AddColumns {
2072            columns: vec![AddColumn {
2073                column_metadata: ColumnMetadata {
2074                    column_schema: ColumnSchema::new(
2075                        "tag_0",
2076                        ConcreteDataType::string_datatype(),
2077                        true,
2078                    ),
2079                    semantic_type: SemanticType::Tag,
2080                    column_id: 2,
2081                },
2082                location: Some(AddColumnLocation::First),
2083            }],
2084        };
2085        kind.validate(&metadata).unwrap_err();
2086    }
2087
2088    #[test]
2089    fn test_validate_drop_column() {
2090        let metadata = new_metadata();
2091        let kind = AlterKind::DropColumns {
2092            names: vec!["xxxx".to_string()],
2093        };
2094        kind.validate(&metadata).unwrap();
2095        assert!(!kind.need_alter(&metadata));
2096
2097        AlterKind::DropColumns {
2098            names: vec!["tag_0".to_string()],
2099        }
2100        .validate(&metadata)
2101        .unwrap_err();
2102
2103        let kind = AlterKind::DropColumns {
2104            names: vec!["field_0".to_string()],
2105        };
2106        kind.validate(&metadata).unwrap();
2107        assert!(kind.need_alter(&metadata));
2108    }
2109
2110    #[test]
2111    fn test_validate_modify_column_type() {
2112        let metadata = new_metadata();
2113        AlterKind::ModifyColumnTypes {
2114            columns: vec![ModifyColumnType {
2115                column_name: "xxxx".to_string(),
2116                target_type: ConcreteDataType::string_datatype(),
2117            }],
2118        }
2119        .validate(&metadata)
2120        .unwrap_err();
2121
2122        AlterKind::ModifyColumnTypes {
2123            columns: vec![ModifyColumnType {
2124                column_name: "field_1".to_string(),
2125                target_type: ConcreteDataType::date_datatype(),
2126            }],
2127        }
2128        .validate(&metadata)
2129        .unwrap_err();
2130
2131        AlterKind::ModifyColumnTypes {
2132            columns: vec![ModifyColumnType {
2133                column_name: "ts".to_string(),
2134                target_type: ConcreteDataType::date_datatype(),
2135            }],
2136        }
2137        .validate(&metadata)
2138        .unwrap_err();
2139
2140        AlterKind::ModifyColumnTypes {
2141            columns: vec![ModifyColumnType {
2142                column_name: "tag_0".to_string(),
2143                target_type: ConcreteDataType::date_datatype(),
2144            }],
2145        }
2146        .validate(&metadata)
2147        .unwrap_err();
2148
2149        let kind = AlterKind::ModifyColumnTypes {
2150            columns: vec![ModifyColumnType {
2151                column_name: "field_0".to_string(),
2152                target_type: ConcreteDataType::int32_datatype(),
2153            }],
2154        };
2155        kind.validate(&metadata).unwrap();
2156        assert!(kind.need_alter(&metadata));
2157    }
2158
2159    #[test]
2160    fn test_validate_add_columns() {
2161        let kind = AlterKind::AddColumns {
2162            columns: vec![
2163                AddColumn {
2164                    column_metadata: ColumnMetadata {
2165                        column_schema: ColumnSchema::new(
2166                            "tag_1",
2167                            ConcreteDataType::string_datatype(),
2168                            true,
2169                        ),
2170                        semantic_type: SemanticType::Tag,
2171                        column_id: 5,
2172                    },
2173                    location: None,
2174                },
2175                AddColumn {
2176                    column_metadata: ColumnMetadata {
2177                        column_schema: ColumnSchema::new(
2178                            "field_2",
2179                            ConcreteDataType::string_datatype(),
2180                            true,
2181                        ),
2182                        semantic_type: SemanticType::Field,
2183                        column_id: 6,
2184                    },
2185                    location: None,
2186                },
2187            ],
2188        };
2189        let request = RegionAlterRequest { kind };
2190        let mut metadata = new_metadata();
2191        metadata.schema_version = 1;
2192        request.validate(&metadata).unwrap();
2193    }
2194
2195    #[test]
2196    fn test_validate_create_region() {
2197        let column_metadatas = vec![
2198            ColumnMetadata {
2199                column_schema: ColumnSchema::new(
2200                    "ts",
2201                    ConcreteDataType::timestamp_millisecond_datatype(),
2202                    false,
2203                ),
2204                semantic_type: SemanticType::Timestamp,
2205                column_id: 1,
2206            },
2207            ColumnMetadata {
2208                column_schema: ColumnSchema::new(
2209                    "tag_0",
2210                    ConcreteDataType::string_datatype(),
2211                    true,
2212                ),
2213                semantic_type: SemanticType::Tag,
2214                column_id: 2,
2215            },
2216            ColumnMetadata {
2217                column_schema: ColumnSchema::new(
2218                    "field_0",
2219                    ConcreteDataType::string_datatype(),
2220                    true,
2221                ),
2222                semantic_type: SemanticType::Field,
2223                column_id: 3,
2224            },
2225        ];
2226        let create = RegionCreateRequest {
2227            engine: "mito".to_string(),
2228            column_metadatas,
2229            primary_key: vec![3, 4],
2230            options: HashMap::new(),
2231            table_dir: "path".to_string(),
2232            path_type: PathType::Bare,
2233            partition_expr_json: Some("".to_string()),
2234            requirements: Default::default(),
2235        };
2236
2237        assert!(create.validate().is_err());
2238    }
2239
2240    #[test]
2241    fn test_parse_create_region_requirements_defaults_to_empty() {
2242        let create = CreateRequest {
2243            region_id: RegionId::new(42, 0).as_u64(),
2244            engine: "mito".to_string(),
2245            column_defs: vec![],
2246            primary_key: vec![],
2247            path: "test".to_string(),
2248            options: HashMap::new(),
2249            partition: None,
2250            requirements: None,
2251        };
2252
2253        let requests =
2254            RegionRequest::try_from_request_body(region_request::Body::Create(create)).unwrap();
2255        let RegionRequest::Create(request) = &requests[0].1 else {
2256            unreachable!()
2257        };
2258
2259        assert_eq!(request.requirements, RegionRequirements::empty());
2260    }
2261
2262    #[test]
2263    fn test_parse_create_region_requirements_from_proto() {
2264        let create = CreateRequest {
2265            region_id: RegionId::new(42, 0).as_u64(),
2266            engine: "mito".to_string(),
2267            column_defs: vec![],
2268            primary_key: vec![],
2269            path: "test".to_string(),
2270            options: HashMap::new(),
2271            partition: None,
2272            requirements: Some(api::v1::region::RegionRequirements {
2273                object_storage: true,
2274            }),
2275        };
2276
2277        let requests =
2278            RegionRequest::try_from_request_body(region_request::Body::Create(create)).unwrap();
2279        let RegionRequest::Create(request) = &requests[0].1 else {
2280            unreachable!()
2281        };
2282
2283        assert_eq!(request.requirements, RegionRequirements::object_storage());
2284    }
2285
2286    #[test]
2287    fn test_parse_region_cleanup_from_proto() {
2288        let clean_up = api::v1::region::CleanUpRequest {
2289            region_id: RegionId::new(42, 3).as_u64(),
2290            engine: "mito".to_string(),
2291            path: "test".to_string(),
2292            options: HashMap::from([("k".to_string(), "v".to_string())]),
2293        };
2294
2295        let requests =
2296            RegionRequest::try_from_request_body(region_request::Body::CleanUp(clean_up)).unwrap();
2297        let RegionRequest::CleanUp(request) = &requests[0].1 else {
2298            unreachable!()
2299        };
2300
2301        assert_eq!(requests[0].0, RegionId::new(42, 3));
2302        assert_eq!(request.engine, "mito");
2303        assert_eq!(request.table_dir, "data/test/42/");
2304        assert_eq!(request.path_type, PathType::Bare);
2305        assert_eq!(request.options.get("k"), Some(&"v".to_string()));
2306    }
2307
2308    #[test]
2309    fn test_validate_modify_column_fulltext_options() {
2310        let kind = AlterKind::SetIndexes {
2311            options: vec![SetIndexOption::Fulltext {
2312                column_name: "tag_0".to_string(),
2313                options: FulltextOptions::new_unchecked(
2314                    true,
2315                    FulltextAnalyzer::Chinese,
2316                    false,
2317                    FulltextBackend::Bloom,
2318                    1000,
2319                    0.01,
2320                ),
2321            }],
2322        };
2323        let request = RegionAlterRequest { kind };
2324        let mut metadata = new_metadata();
2325        metadata.schema_version = 1;
2326        request.validate(&metadata).unwrap();
2327
2328        let kind = AlterKind::UnsetIndexes {
2329            options: vec![UnsetIndexOption::Fulltext {
2330                column_name: "tag_0".to_string(),
2331            }],
2332        };
2333        let request = RegionAlterRequest { kind };
2334        let mut metadata = new_metadata();
2335        metadata.schema_version = 1;
2336        request.validate(&metadata).unwrap();
2337    }
2338
2339    #[test]
2340    fn test_validate_sync_columns() {
2341        let metadata = new_metadata();
2342        let kind = AlterKind::SyncColumns {
2343            column_metadatas: vec![
2344                ColumnMetadata {
2345                    column_schema: ColumnSchema::new(
2346                        "tag_1",
2347                        ConcreteDataType::string_datatype(),
2348                        true,
2349                    ),
2350                    semantic_type: SemanticType::Tag,
2351                    column_id: 5,
2352                },
2353                ColumnMetadata {
2354                    column_schema: ColumnSchema::new(
2355                        "field_2",
2356                        ConcreteDataType::string_datatype(),
2357                        true,
2358                    ),
2359                    semantic_type: SemanticType::Field,
2360                    column_id: 6,
2361                },
2362            ],
2363        };
2364        let err = kind.validate(&metadata).unwrap_err();
2365        assert!(err.to_string().contains("not a primary key"));
2366
2367        // Change the timestamp column name.
2368        let mut column_metadatas_with_different_ts_column = metadata.column_metadatas.clone();
2369        let ts_column = column_metadatas_with_different_ts_column
2370            .iter_mut()
2371            .find(|c| c.semantic_type == SemanticType::Timestamp)
2372            .unwrap();
2373        ts_column.column_schema.name = "ts1".to_string();
2374
2375        let kind = AlterKind::SyncColumns {
2376            column_metadatas: column_metadatas_with_different_ts_column,
2377        };
2378        let err = kind.validate(&metadata).unwrap_err();
2379        assert!(
2380            err.to_string()
2381                .contains("timestamp column ts has different id")
2382        );
2383
2384        // Change the primary key column name.
2385        let mut column_metadatas_with_different_pk_column = metadata.column_metadatas.clone();
2386        let pk_column = column_metadatas_with_different_pk_column
2387            .iter_mut()
2388            .find(|c| c.column_schema.name == "tag_0")
2389            .unwrap();
2390        pk_column.column_id = 100;
2391        let kind = AlterKind::SyncColumns {
2392            column_metadatas: column_metadatas_with_different_pk_column,
2393        };
2394        let err = kind.validate(&metadata).unwrap_err();
2395        assert!(
2396            err.to_string()
2397                .contains("column with same name tag_0 has different id")
2398        );
2399
2400        // Add a new field column.
2401        let mut column_metadatas_with_new_field_column = metadata.column_metadatas.clone();
2402        column_metadatas_with_new_field_column.push(ColumnMetadata {
2403            column_schema: ColumnSchema::new("field_2", ConcreteDataType::string_datatype(), true),
2404            semantic_type: SemanticType::Field,
2405            column_id: 4,
2406        });
2407        let kind = AlterKind::SyncColumns {
2408            column_metadatas: column_metadatas_with_new_field_column,
2409        };
2410        kind.validate(&metadata).unwrap();
2411    }
2412
2413    #[test]
2414    fn test_cast_path_type_to_primitive() {
2415        assert_eq!(PathType::Bare as u8, 0);
2416        assert_eq!(PathType::Data as u8, 1);
2417        assert_eq!(PathType::Metadata as u8, 2);
2418        assert_eq!(
2419            PathType::try_from(PathType::Bare as u8).unwrap(),
2420            PathType::Bare
2421        );
2422        assert_eq!(
2423            PathType::try_from(PathType::Data as u8).unwrap(),
2424            PathType::Data
2425        );
2426        assert_eq!(
2427            PathType::try_from(PathType::Metadata as u8).unwrap(),
2428            PathType::Metadata
2429        );
2430    }
2431}