1use std::str::FromStr;
18use std::sync::Arc;
19
20use common_base::readable_size::ReadableSize;
21use common_telemetry::tracing::warn;
22use common_telemetry::{error, info};
23use humantime_serde::re::humantime;
24use snafu::{ResultExt, ensure};
25use store_api::logstore::LogStore;
26use store_api::logstore::provider::Provider;
27use store_api::metadata::{
28 InvalidSetRegionOptionRequestSnafu, MetadataError, RegionMetadata, RegionMetadataBuilder,
29 RegionMetadataRef,
30};
31use store_api::mito_engine_options;
32use store_api::mito_engine_options::MAX_ROW_GROUP_ROW_COUNT_LIMIT;
33use store_api::region_request::{AlterKind, RegionAlterRequest, SetRegionOption};
34use store_api::storage::RegionId;
35
36use crate::error::{InvalidMetadataSnafu, InvalidRegionRequestSnafu, Result};
37use crate::flush::FlushReason;
38use crate::manifest::action::RegionChange;
39use crate::memtable::ensure_json2_uses_flat_format;
40use crate::region::MitoRegionRef;
41use crate::region::options::CompactionOptions::Twcs;
42use crate::region::options::{RegionOptions, TwcsOptions};
43use crate::region::version::VersionRef;
44use crate::request::{DdlRequest, OptionOutputTx, SenderDdlRequest};
45use crate::sst::FormatType;
46use crate::worker::RegionWorkerLoop;
47
48impl<S: LogStore> RegionWorkerLoop<S> {
49 pub(crate) async fn execute_alter_request(
50 &mut self,
51 region_id: RegionId,
52 request: RegionAlterRequest,
53 sender: OptionOutputTx,
54 ) {
55 let requested_skip_wal = skip_wal_value(&request.kind);
56 let (region, follower_skip_wal) = match self.regions.writable_non_staging_region(region_id)
57 {
58 Ok(region) => (region, None),
59 Err(_) if requested_skip_wal.is_some() => {
60 match self.regions.follower_region(region_id) {
61 Ok(region) => (region, requested_skip_wal),
62 Err(e) => {
63 sender.send(Err(e));
64 return;
65 }
66 }
67 }
68 Err(e) => {
69 sender.send(Err(e));
70 return;
71 }
72 };
73
74 info!("Try to alter region: {}, request: {:?}", region_id, request);
75
76 if let Some(skip_wal) = follower_skip_wal {
79 if let Err(e) = validate_skip_wal_change(®ion, skip_wal) {
80 sender.send(Err(e).context(InvalidMetadataSnafu));
81 return;
82 }
83 let mut options = region.version().options.clone();
84 if options.skip_wal != skip_wal {
85 info!(
86 "Set skip_wal for follower region: {}, previous: {} new: {}",
87 region_id, options.skip_wal, skip_wal
88 );
89 options.skip_wal = skip_wal;
90 region.version_control.alter_options(options);
91 }
92 sender.send(Ok(0));
93 return;
94 }
95
96 let version = region.version();
98
99 let set_options = match &request.kind {
101 AlterKind::SetRegionOptions { options } => options.clone(),
102 AlterKind::UnsetRegionOptions { keys } => {
103 keys.iter().map(Into::into).collect()
107 }
108 _ => Vec::new(),
109 };
110 let mut new_options = None;
111 if !set_options.is_empty() {
112 match self.handle_alter_region_options_fast(®ion, version.clone(), set_options) {
113 Ok(staged_options) => {
114 let Some(staged_options) = staged_options else {
115 sender.send(Ok(0));
117 return;
118 };
119 new_options = Some(staged_options);
120 }
121 Err(e) => {
122 sender.send(Err(e).context(InvalidMetadataSnafu));
123 return;
124 }
125 }
126 }
127
128 if let Err(e) = request.validate(&version.metadata) {
130 sender.send(Err(e).context(InvalidRegionRequestSnafu));
132 return;
133 }
134
135 if !is_allowed_with_pending_tails(&request.kind)
136 && let Err(e) = version.ensure_no_pending_tails()
137 {
138 sender.send(Err(e));
139 return;
140 }
141
142 if !request.need_alter(&version.metadata) {
144 warn!(
145 "Ignores alter request as it alters nothing, region_id: {}, request: {:?}",
146 region_id, request
147 );
148 sender.send(Ok(0));
149 return;
150 }
151
152 if !version.memtables.is_empty() {
154 info!("Flush region: {} before alteration", region_id);
157
158 let task = self.new_flush_task(®ion, FlushReason::Alter, None, self.config.clone());
160 if let Err(e) =
161 self.flush_scheduler
162 .schedule_flush(region.region_id, ®ion.version_control, task)
163 {
164 sender.send(Err(e));
166 return;
167 }
168
169 self.flush_scheduler
171 .add_ddl_request_to_pending(SenderDdlRequest {
172 region_id,
173 sender,
174 request: DdlRequest::Alter(request),
175 });
176
177 return;
178 }
179
180 info!(
181 "Try to alter region {}, version.metadata: {:?}, version.options: {:?}, request: {:?}",
182 region_id, version.metadata, version.options, request,
183 );
184 log_time_index_widening_overflow(region.region_id, &version, &request);
185 self.handle_alter_region_with_empty_memtable(region, version, request, new_options, sender);
186 }
187
188 fn handle_alter_region_with_empty_memtable(
191 &mut self,
192 region: MitoRegionRef,
193 version: VersionRef,
194 request: RegionAlterRequest,
195 new_options: Option<RegionOptions>,
196 sender: OptionOutputTx,
197 ) {
198 let need_index = need_change_index(&request.kind);
199 let new_meta = match metadata_after_alteration(&version.metadata, request) {
200 Ok(new_meta) => new_meta,
201 Err(e) => {
202 sender.send(Err(e));
203 return;
204 }
205 };
206 let options = new_options.as_ref().unwrap_or(&version.options);
207 if let Err(e) = ensure_json2_uses_flat_format(&new_meta, options) {
208 sender.send(Err(e));
209 return;
210 }
211 if let Err(e) = options.validate_column_compression(&new_meta) {
212 sender.send(Err(e));
213 return;
214 }
215 let change = RegionChange {
217 metadata: new_meta,
218 sst_format: options.sst_format.unwrap_or_default(),
219 append_mode: Some(options.append_mode),
220 };
221 self.handle_manifest_region_change(region, change, need_index, new_options, sender);
222 }
223
224 fn handle_alter_region_options_fast(
235 &mut self,
236 region: &MitoRegionRef,
237 version: VersionRef,
238 options: Vec<SetRegionOption>,
239 ) -> std::result::Result<Option<RegionOptions>, MetadataError> {
240 assert!(!options.is_empty());
241
242 let mut all_options_altered = true;
243 let mut current_options = version.options.clone();
244 for option in options.iter().cloned() {
245 match option {
246 SetRegionOption::WriteBufferSize(new_write_buffer_size) => {
247 info!(
248 "Update region write_buffer_size: {}, previous: {:?} new: {:?}",
249 region.region_id, current_options.write_buffer_size, new_write_buffer_size
250 );
251 current_options.write_buffer_size = new_write_buffer_size;
252 current_options.validate().map_err(|e| {
253 store_api::metadata::InvalidRegionRequestSnafu {
254 region_id: region.region_id,
255 err: e.to_string(),
256 }
257 .build()
258 })?;
259 }
260 SetRegionOption::Ttl(new_ttl) => {
261 info!(
262 "Update region ttl: {}, previous: {:?} new: {:?}",
263 region.region_id, current_options.ttl, new_ttl
264 );
265 current_options.ttl = new_ttl;
266 }
267 SetRegionOption::Twsc(key, value) => {
268 let Twcs(options) = &mut current_options.compaction;
269 set_twcs_options(
270 options,
271 &TwcsOptions::default(),
272 &key,
273 &value,
274 region.region_id,
275 )?;
276 if !value.is_empty() {
277 current_options.compaction_override = true;
278 }
279 }
280 SetRegionOption::Format(format_str) => {
281 let new_format = format_str.parse::<FormatType>().map_err(|_| {
282 store_api::metadata::InvalidRegionRequestSnafu {
283 region_id: region.region_id,
284 err: format!("Invalid format type: {}", format_str),
285 }
286 .build()
287 })?;
288 if new_format != current_options.sst_format.unwrap_or_default() {
290 all_options_altered = false;
291 }
292 }
293 SetRegionOption::AppendMode(new_append_mode) => {
294 if new_append_mode != current_options.append_mode {
296 ensure!(
298 !current_options.append_mode && new_append_mode,
299 store_api::metadata::InvalidRegionRequestSnafu {
300 region_id: region.region_id,
301 err: "Only allow changing append_mode from false to true",
302 }
303 );
304 current_options.merge_mode = None;
306 all_options_altered = false;
307 }
308 }
309 SetRegionOption::AutoFlushInterval(new_interval) => {
310 if new_interval != current_options.auto_flush_interval {
314 info!(
315 "Update region auto_flush_interval: {}, previous: {:?} new: {:?}",
316 region.region_id, current_options.auto_flush_interval, new_interval
317 );
318 current_options.auto_flush_interval = new_interval;
319 }
320 }
321 SetRegionOption::CompactionOutputParallelism(parallelism) => {
322 current_options.compaction_output_parallelism = parallelism;
325 }
326 SetRegionOption::MaxRowGroupRowCount(new_row_count) => {
327 if let Some(row_count) = new_row_count {
328 ensure!(
329 row_count > 0 && row_count <= MAX_ROW_GROUP_ROW_COUNT_LIMIT,
330 store_api::metadata::InvalidRegionRequestSnafu {
331 region_id: region.region_id,
332 err: format!(
333 "max_row_group_row_count must be in (0, \
334 {MAX_ROW_GROUP_ROW_COUNT_LIMIT}], got {row_count}"
335 ),
336 }
337 );
338 }
339 if new_row_count != current_options.max_row_group_row_count {
340 all_options_altered = false;
341 }
342 }
343 SetRegionOption::PreserveRowSequence(new_preserve) => {
344 if new_preserve != current_options.preserve_row_sequence {
345 info!(
346 "Update region preserve_row_sequence: {}, previous: {:?} new: {:?}",
347 region.region_id, current_options.preserve_row_sequence, new_preserve
348 );
349 current_options.preserve_row_sequence = new_preserve;
350 }
351 }
352 SetRegionOption::SkipWal(skip_wal) => {
353 validate_skip_wal_change(region, skip_wal)?;
354 if current_options.skip_wal != skip_wal {
355 info!(
356 "Set skip_wal for region: {}, previous: {} new: {}",
357 region.region_id, current_options.skip_wal, skip_wal
358 );
359 current_options.skip_wal = skip_wal;
360 }
361 }
362 }
363 }
364 let kind = AlterKind::SetRegionOptions { options };
365 let candidate = new_region_options_on_empty_memtable(¤t_options, &kind)
372 .unwrap_or_else(|| current_options.clone());
373 candidate.validate().map_err(|e| {
374 store_api::metadata::InvalidRegionRequestSnafu {
375 region_id: region.region_id,
376 err: e.to_string(),
377 }
378 .build()
379 })?;
380 candidate
381 .validate_column_compression(&version.metadata)
382 .map_err(|e| {
383 store_api::metadata::InvalidRegionRequestSnafu {
384 region_id: region.region_id,
385 err: e.to_string(),
386 }
387 .build()
388 })?;
389 if all_options_altered {
390 region.version_control.alter_options(candidate);
391 Ok(None)
392 } else {
393 Ok(Some(candidate))
396 }
397 }
398}
399
400fn is_allowed_with_pending_tails(kind: &AlterKind) -> bool {
403 match kind {
404 AlterKind::AddColumns { columns } => columns.iter().all(|column| {
405 let schema = &column.column_metadata.column_schema;
406 schema.is_nullable() && schema.default_constraint().is_none()
407 }),
408 AlterKind::SetRegionOptions { .. } | AlterKind::UnsetRegionOptions { .. } => true,
409 _ => false,
410 }
411}
412
413fn skip_wal_value(kind: &AlterKind) -> Option<bool> {
414 let AlterKind::SetRegionOptions { options } = kind else {
415 return None;
416 };
417 let [SetRegionOption::SkipWal(skip_wal)] = options.as_slice() else {
418 return None;
419 };
420 Some(*skip_wal)
421}
422
423fn validate_skip_wal_change(
424 region: &MitoRegionRef,
425 skip_wal: bool,
426) -> std::result::Result<(), MetadataError> {
427 ensure!(
428 skip_wal || !matches!(®ion.provider, Provider::Noop),
429 store_api::metadata::InvalidRegionRequestSnafu {
430 region_id: region.region_id,
431 err: "cannot enable WAL because the region uses the Noop WAL provider".to_string(),
432 }
433 );
434 Ok(())
435}
436
437fn new_region_options_on_empty_memtable(
439 current_options: &RegionOptions,
440 kind: &AlterKind,
441) -> Option<RegionOptions> {
442 let options = match kind {
443 AlterKind::SetRegionOptions { options } => options.clone(),
444 AlterKind::UnsetRegionOptions { keys } => keys.iter().map(Into::into).collect(),
445 _ => return None,
446 };
447
448 if options.is_empty() {
449 return None;
450 }
451
452 let mut current_options = current_options.clone();
453 for option in &options {
454 match option {
455 SetRegionOption::WriteBufferSize(_)
456 | SetRegionOption::Ttl(_)
457 | SetRegionOption::Twsc(_, _)
458 | SetRegionOption::AutoFlushInterval(_)
459 | SetRegionOption::CompactionOutputParallelism(_)
460 | SetRegionOption::SkipWal(_) => (),
461 SetRegionOption::Format(format_str) => {
462 let new_format = format_str.parse::<FormatType>().unwrap();
464 current_options.sst_format = Some(new_format);
465 }
466 SetRegionOption::AppendMode(new_append_mode) => {
467 if *new_append_mode != current_options.append_mode {
468 current_options.append_mode = *new_append_mode;
471 current_options.merge_mode = None;
472 }
473 }
474 SetRegionOption::MaxRowGroupRowCount(new_row_count) => {
475 current_options.max_row_group_row_count = *new_row_count;
476 }
477 SetRegionOption::PreserveRowSequence(new_preserve) => {
478 current_options.preserve_row_sequence = *new_preserve;
479 }
480 }
481 }
482 Some(current_options)
483}
484
485fn metadata_after_alteration(
489 metadata: &RegionMetadata,
490 request: RegionAlterRequest,
491) -> Result<RegionMetadataRef> {
492 let mut builder = RegionMetadataBuilder::from_existing(metadata.clone());
493 builder
494 .alter(request.kind)
495 .context(InvalidRegionRequestSnafu)?
496 .bump_version();
497 let new_meta = builder.build().context(InvalidMetadataSnafu)?;
498
499 Ok(Arc::new(new_meta))
500}
501
502fn set_twcs_options(
503 options: &mut TwcsOptions,
504 default_option: &TwcsOptions,
505 key: &str,
506 value: &str,
507 region_id: RegionId,
508) -> std::result::Result<(), MetadataError> {
509 match key {
510 mito_engine_options::TWCS_TRIGGER_FILE_NUM
511 | mito_engine_options::TWCS_ACTIVE_WINDOW_TRIGGER_FILE_NUM => {
512 let files = parse_usize_with_default(
513 key,
514 value,
515 default_option.active_window_trigger_file_num,
516 )?;
517 log_option_update(
518 region_id,
519 key,
520 options.active_window_trigger_file_num,
521 files,
522 );
523 options.active_window_trigger_file_num = files;
524 }
525 mito_engine_options::TWCS_ACTIVE_WINDOW_L1_MERGE_TRIGGER => {
526 let files = parse_usize_with_default(
527 key,
528 value,
529 default_option.active_window_l1_merge_trigger,
530 )?;
531 ensure!(
532 files >= 2,
533 InvalidSetRegionOptionRequestSnafu { key, value }
534 );
535 log_option_update(
536 region_id,
537 key,
538 options.active_window_l1_merge_trigger,
539 files,
540 );
541 options.active_window_l1_merge_trigger = files;
542 }
543 mito_engine_options::TWCS_INACTIVE_WINDOW_TRIGGER_FILE_NUM => {
544 let files = parse_usize_with_default(
545 key,
546 value,
547 default_option.inactive_window_trigger_file_num,
548 )?;
549 log_option_update(
550 region_id,
551 key,
552 options.inactive_window_trigger_file_num,
553 files,
554 );
555 options.inactive_window_trigger_file_num = files;
556 }
557 mito_engine_options::TWCS_INACTIVE_WINDOW_L1_MERGE_TRIGGER => {
558 let files = parse_usize_with_default(
559 key,
560 value,
561 default_option.inactive_window_l1_merge_trigger,
562 )?;
563 ensure!(
564 files >= 2,
565 InvalidSetRegionOptionRequestSnafu { key, value }
566 );
567 log_option_update(
568 region_id,
569 key,
570 options.inactive_window_l1_merge_trigger,
571 files,
572 );
573 options.inactive_window_l1_merge_trigger = files;
574 }
575 mito_engine_options::TWCS_MAX_OUTPUT_FILE_SIZE => {
576 let size = if value.is_empty() {
577 default_option.max_output_file_size
578 } else {
579 Some(
580 ReadableSize::from_str(value)
581 .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?,
582 )
583 };
584 log_option_update(region_id, key, options.max_output_file_size, size);
585 options.max_output_file_size = size;
586 }
587 mito_engine_options::TWCS_TIME_WINDOW => {
588 let window = if value.is_empty() {
589 default_option.time_window
590 } else {
591 Some(
592 humantime::parse_duration(value)
593 .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())?,
594 )
595 };
596 log_option_update(region_id, key, options.time_window, window);
597 options.time_window = window;
598 }
599 _ => return InvalidSetRegionOptionRequestSnafu { key, value }.fail(),
600 }
601 Ok(())
602}
603
604fn parse_usize_with_default(
605 key: &str,
606 value: &str,
607 default: usize,
608) -> std::result::Result<usize, MetadataError> {
609 if value.is_empty() {
610 Ok(default)
611 } else {
612 value
613 .parse::<usize>()
614 .map_err(|_| InvalidSetRegionOptionRequestSnafu { key, value }.build())
615 }
616}
617
618fn log_option_update<T: std::fmt::Debug>(
619 region_id: RegionId,
620 option_name: &str,
621 prev_value: T,
622 cur_value: T,
623) {
624 info!(
625 "Update region {}: {}, previous: {:?}, new: {:?}",
626 option_name, region_id, prev_value, cur_value
627 );
628}
629
630fn log_time_index_widening_overflow(
635 region_id: RegionId,
636 version: &VersionRef,
637 request: &RegionAlterRequest,
638) {
639 let AlterKind::ModifyColumnTypes { columns } = &request.kind else {
640 return;
641 };
642 let time_index = version.metadata.time_index_column();
643 for column in columns {
644 if column.column_name != time_index.column_schema.name {
645 continue;
646 }
647 let Some(target_unit) = column.target_type.as_timestamp().map(|t| t.unit()) else {
650 continue;
651 };
652 for level in version.ssts.levels() {
653 for file in level.files.values() {
654 let (start, end) = file.time_range();
655 if start.convert_to(target_unit).is_none() || end.convert_to(target_unit).is_none()
656 {
657 error!(
658 "Time index widening for region {} overflows file {}: widening column \
659 '{}' to {:?}, but data spans [{}, {}] beyond the target unit's i64 \
660 range; overflowing values read back as NULL",
661 region_id,
662 file.file_id(),
663 column.column_name,
664 target_unit,
665 start.to_iso8601_string(),
666 end.to_iso8601_string(),
667 );
668 return;
669 }
670 }
671 }
672 }
673}
674
675fn need_change_index(kind: &AlterKind) -> bool {
677 match kind {
678 AlterKind::SetIndexes { options: _ } => true,
681 _ => false,
685 }
686}
687
688#[cfg(test)]
689mod tests {
690 use super::*;
691
692 #[test]
693 fn test_set_twcs_window_trigger_options() {
694 let mut options = TwcsOptions::default();
695 let defaults = options.clone();
696 let region_id = RegionId::new(1, 1);
697
698 set_twcs_options(
699 &mut options,
700 &defaults,
701 "compaction.twcs.active_window.trigger_file_num",
702 "8",
703 region_id,
704 )
705 .unwrap();
706 set_twcs_options(
707 &mut options,
708 &defaults,
709 "compaction.twcs.active_window.l1_merge_trigger",
710 "16",
711 region_id,
712 )
713 .unwrap();
714 set_twcs_options(
715 &mut options,
716 &defaults,
717 "compaction.twcs.inactive_window.trigger_file_num",
718 "3",
719 region_id,
720 )
721 .unwrap();
722 set_twcs_options(
723 &mut options,
724 &defaults,
725 "compaction.twcs.inactive_window.l1_merge_trigger",
726 "12",
727 region_id,
728 )
729 .unwrap();
730 assert_eq!(8, options.active_window_trigger_file_num);
731 assert_eq!(16, options.active_window_l1_merge_trigger);
732 assert_eq!(3, options.inactive_window_trigger_file_num);
733 assert_eq!(12, options.inactive_window_l1_merge_trigger);
734
735 set_twcs_options(
736 &mut options,
737 &defaults,
738 "compaction.twcs.active_window.trigger_file_num",
739 "",
740 region_id,
741 )
742 .unwrap();
743 set_twcs_options(
744 &mut options,
745 &defaults,
746 "compaction.twcs.active_window.l1_merge_trigger",
747 "",
748 region_id,
749 )
750 .unwrap();
751 set_twcs_options(
752 &mut options,
753 &defaults,
754 "compaction.twcs.inactive_window.trigger_file_num",
755 "",
756 region_id,
757 )
758 .unwrap();
759 set_twcs_options(
760 &mut options,
761 &defaults,
762 "compaction.twcs.inactive_window.l1_merge_trigger",
763 "",
764 region_id,
765 )
766 .unwrap();
767 assert_eq!(defaults, options);
768 }
769
770 #[test]
771 fn test_set_twcs_window_trigger_accepts_one() {
772 let defaults = TwcsOptions::default();
773 for key in [
774 "compaction.twcs.trigger_file_num",
775 "compaction.twcs.active_window.trigger_file_num",
776 "compaction.twcs.inactive_window.trigger_file_num",
777 ] {
778 let mut options = defaults.clone();
779 assert!(
780 set_twcs_options(&mut options, &defaults, key, "1", RegionId::new(1, 1)).is_ok(),
781 "{key}"
782 );
783 }
784 }
785
786 #[test]
787 fn test_set_twcs_l1_merge_triggers_reject_one() {
788 let defaults = TwcsOptions::default();
789 for key in [
790 "compaction.twcs.active_window.l1_merge_trigger",
791 "compaction.twcs.inactive_window.l1_merge_trigger",
792 ] {
793 let mut options = TwcsOptions::default();
794 assert!(
795 set_twcs_options(&mut options, &defaults, key, "1", RegionId::new(1, 1)).is_err(),
796 "{key}"
797 );
798 }
799 }
800
801 #[test]
802 fn test_new_region_options_with_idempotent_append_mode() {
803 let current_options = RegionOptions::default();
804 let kind = AlterKind::SetRegionOptions {
805 options: vec![
806 SetRegionOption::AppendMode(false),
807 SetRegionOption::MaxRowGroupRowCount(Some(1024)),
808 ],
809 };
810
811 let new_options = new_region_options_on_empty_memtable(¤t_options, &kind).unwrap();
812 assert!(!new_options.append_mode);
813 assert_eq!(Some(1024), new_options.max_row_group_row_count);
814 }
815}