1#[internal_api]
2pub(crate) use column_mapping::get_any_level_column_physical_name;
3#[deprecated = "Enable internal-api and use TableConfiguration instead"]
4pub use column_mapping::validate_schema_column_mapping;
5pub use column_mapping::ColumnMappingMode;
6#[internal_api]
7pub(crate) use column_mapping::{assign_column_mapping_metadata, find_max_column_id_in_schema};
8pub(crate) use column_mapping::{
9 column_mapping_mode, get_column_mapping_mode_from_properties,
10 physical_to_logical_column_name_and_type, schema_has_column_mapping_metadata,
11 strip_stray_column_mapping_metadata, try_assign_flat_column_mapping_info,
12 validate_and_extract_column_mapping_annotations, validate_column_mapping_id,
13 StaleAnnotationPolicy,
14};
15use delta_kernel_derive::internal_api;
16#[cfg(feature = "geo-type-in-dev")]
17pub(crate) use geospatial::validate_geospatial_feature_support;
18pub(crate) use iceberg_compat::v3::V3_VALIDATOR;
19pub(crate) use iceberg_compat::{
20 validate_iceberg_compat_if_needed, IcebergCompatValidationContext,
21};
22use itertools::Itertools;
23use serde::{Deserialize, Serialize};
24use strum::{AsRefStr, Display as StrumDisplay, EnumCount, EnumIter, EnumString};
25#[cfg(feature = "nanosecond-timestamps")]
26pub(crate) use timestamp_nanos::{
27 schema_contains_timestamp_nanos, validate_timestamp_nanos_feature_support,
28};
29pub(crate) use timestamp_ntz::{
30 schema_contains_timestamp_ntz, validate_timestamp_ntz_feature_support,
31};
32
33use crate::actions::Protocol;
34use crate::expressions::Scalar;
35use crate::schema::derive_macro_utils::ToDataType;
36use crate::schema::DataType;
37use crate::table_properties::TableProperties;
38use crate::utils::require;
39use crate::{DeltaResult, Error};
40
41mod column_mapping;
42#[cfg(feature = "geo-type-in-dev")]
43mod geospatial;
44mod iceberg_compat;
45#[cfg(feature = "nanosecond-timestamps")]
46mod timestamp_nanos;
47mod timestamp_ntz;
48
49pub const MIN_VALID_RW_VERSION: i32 = 1;
51
52pub const MAX_VALID_READER_VERSION: i32 = 3;
54
55pub const MAX_VALID_WRITER_VERSION: i32 = 7;
57
58pub const TABLE_FEATURES_MIN_READER_VERSION: i32 = 3;
61
62pub const TABLE_FEATURES_MIN_WRITER_VERSION: i32 = 7;
65
66pub const SET_TABLE_FEATURE_SUPPORTED_PREFIX: &str = "delta.feature.";
70
71pub const SET_TABLE_FEATURE_SUPPORTED_VALUE: &str = "supported";
74
75#[derive(
87 Serialize,
88 Deserialize,
89 Debug,
90 Clone,
91 Eq,
92 PartialEq,
93 EnumString,
94 StrumDisplay,
95 AsRefStr,
96 EnumCount,
97 Hash,
98)]
99#[strum(serialize_all = "camelCase")]
100#[serde(rename_all = "camelCase")]
101#[internal_api]
102#[derive(EnumIter)]
103pub(crate) enum TableFeature {
106 AppendOnly,
111 Invariants,
113 CheckConstraints,
115 ChangeDataFeed,
117 GeneratedColumns,
119 IdentityColumns,
121 InCommitTimestamp,
123 RowTracking,
125 DomainMetadata,
127 IcebergCompatV1,
129 IcebergCompatV2,
131 IcebergCompatV3,
133 #[strum(serialize = "clustering")]
136 #[serde(rename = "clustering")]
137 ClusteredTable,
138 MaterializePartitionColumns,
140 AllowColumnDefaults,
142
143 CatalogManaged,
149 #[strum(serialize = "catalogOwned-preview")]
150 #[serde(rename = "catalogOwned-preview")]
151 CatalogOwnedPreview,
152 ColumnMapping,
154 DeletionVectors,
156 #[cfg(feature = "nanosecond-timestamps")]
158 #[strum(serialize = "timestampNanos")]
159 #[serde(rename = "timestampNanos")]
160 TimestampNanos,
161 #[strum(to_string = "timestampNtz", serialize = "timestampWithoutTimezone")]
168 #[serde(rename = "timestampNtz", alias = "timestampWithoutTimezone")]
169 TimestampWithoutTimezone,
170
171 TypeWidening,
173 #[strum(serialize = "typeWidening-preview")]
174 #[serde(rename = "typeWidening-preview")]
175 TypeWideningPreview,
176 V2Checkpoint,
178 VacuumProtocolCheck,
181 VariantType,
183 #[strum(serialize = "variantType-preview")]
184 #[serde(rename = "variantType-preview")]
185 VariantTypePreview,
186 VariantShredding,
187 #[strum(serialize = "variantShredding-preview")]
188 #[serde(rename = "variantShredding-preview")]
189 VariantShreddingPreview,
190 #[strum(serialize = "adaptiveMetadata-preview")]
194 #[serde(rename = "adaptiveMetadata-preview")]
195 AdaptiveMetadataPreview,
196 #[strum(serialize = "geospatial")]
198 #[serde(rename = "geospatial")]
199 GeospatialType,
200
201 #[serde(untagged)]
202 #[strum(default)]
203 Unknown(String),
204}
205
206pub(crate) static LEGACY_READER_FEATURES: [TableFeature; 1] = [TableFeature::ColumnMapping];
209
210pub(crate) static LEGACY_WRITER_FEATURES: [TableFeature; 7] = [
213 TableFeature::AppendOnly, TableFeature::Invariants, TableFeature::CheckConstraints, TableFeature::ChangeDataFeed, TableFeature::GeneratedColumns, TableFeature::IdentityColumns, TableFeature::ColumnMapping, ];
223
224#[derive(Debug, Clone, Copy, PartialEq, Eq)]
226pub(crate) enum FeatureType {
227 WriterOnly,
229 ReaderWriter,
231 Unknown,
233}
234
235#[derive(Debug, Clone, Copy)]
237pub(crate) enum EnablementCheck {
238 AlwaysIfSupported,
240 EnabledIf(fn(&TableProperties) -> bool),
243}
244
245#[derive(Debug, Clone, Copy, PartialEq, Eq)]
247#[internal_api]
248pub(crate) enum Operation {
249 Scan,
251 Cdf,
253 Write,
255}
256
257pub(crate) enum KernelSupport {
259 Supported,
261 NotSupported,
263 Custom(fn(&Protocol, &TableProperties, Operation) -> DeltaResult<()>),
267}
268
269#[derive(Debug)]
271pub(crate) enum FeatureRequirement {
272 Supported(TableFeature),
274 Enabled(TableFeature),
276 NotSupported(TableFeature),
278 NotEnabled(TableFeature),
280 Custom(fn(&Protocol, &TableProperties) -> DeltaResult<()>),
282}
283
284pub(crate) struct MinReaderWriterVersion {
286 pub reader: i32,
287 pub writer: i32,
288}
289
290impl MinReaderWriterVersion {
291 pub(crate) const fn new(reader: i32, writer: i32) -> Self {
292 Self { reader, writer }
293 }
294}
295
296pub(crate) struct FeatureInfo {
299 pub feature_type: FeatureType,
301 pub min_legacy_version: Option<MinReaderWriterVersion>,
305 pub feature_requirements: &'static [FeatureRequirement],
307 pub kernel_support: KernelSupport,
315 pub enablement_check: EnablementCheck,
317}
318
319static APPEND_ONLY_INFO: FeatureInfo = FeatureInfo {
321 feature_type: FeatureType::WriterOnly,
322 min_legacy_version: Some(MinReaderWriterVersion::new(1, 2)),
323 feature_requirements: &[],
324 kernel_support: KernelSupport::Supported,
325 enablement_check: EnablementCheck::EnabledIf(|props| props.append_only == Some(true)),
326};
327
328static INVARIANTS_INFO: FeatureInfo = FeatureInfo {
333 feature_type: FeatureType::WriterOnly,
334 min_legacy_version: Some(MinReaderWriterVersion::new(1, 2)),
335 feature_requirements: &[],
336 kernel_support: KernelSupport::Supported,
337 enablement_check: EnablementCheck::AlwaysIfSupported,
338};
339
340static CHECK_CONSTRAINTS_INFO: FeatureInfo = FeatureInfo {
341 feature_type: FeatureType::WriterOnly,
342 min_legacy_version: Some(MinReaderWriterVersion::new(1, 3)),
343 feature_requirements: &[],
344 kernel_support: KernelSupport::NotSupported,
345 enablement_check: EnablementCheck::AlwaysIfSupported,
346};
347
348static CHANGE_DATA_FEED_INFO: FeatureInfo = FeatureInfo {
349 feature_type: FeatureType::WriterOnly,
350 min_legacy_version: Some(MinReaderWriterVersion::new(1, 4)),
351 feature_requirements: &[],
352 kernel_support: KernelSupport::Supported,
353 enablement_check: EnablementCheck::EnabledIf(|props| {
354 props.enable_change_data_feed == Some(true)
355 }),
356};
357
358static GENERATED_COLUMNS_INFO: FeatureInfo = FeatureInfo {
359 feature_type: FeatureType::WriterOnly,
360 min_legacy_version: Some(MinReaderWriterVersion::new(1, 4)),
361 feature_requirements: &[],
362 kernel_support: KernelSupport::NotSupported,
363 enablement_check: EnablementCheck::AlwaysIfSupported,
364};
365
366static IDENTITY_COLUMNS_INFO: FeatureInfo = FeatureInfo {
367 feature_type: FeatureType::WriterOnly,
368 min_legacy_version: Some(MinReaderWriterVersion::new(1, 6)),
369 feature_requirements: &[],
370 kernel_support: KernelSupport::NotSupported,
371 enablement_check: EnablementCheck::AlwaysIfSupported,
372};
373
374static IN_COMMIT_TIMESTAMP_INFO: FeatureInfo = FeatureInfo {
375 feature_type: FeatureType::WriterOnly,
376 min_legacy_version: None,
377 feature_requirements: &[],
378 kernel_support: KernelSupport::Custom(|_protocol, _properties, operation| match operation {
379 Operation::Scan | Operation::Write | Operation::Cdf => Ok(()),
380 }),
381 enablement_check: EnablementCheck::EnabledIf(|props| {
382 props.enable_in_commit_timestamps == Some(true)
383 }),
384};
385
386static ROW_TRACKING_INFO: FeatureInfo = FeatureInfo {
397 feature_type: FeatureType::WriterOnly,
398 min_legacy_version: None,
399 feature_requirements: &[FeatureRequirement::Supported(TableFeature::DomainMetadata)],
400 kernel_support: KernelSupport::Supported,
401 enablement_check: EnablementCheck::EnabledIf(|props| {
402 props.enable_row_tracking == Some(true) && props.row_tracking_suspended != Some(true)
403 }),
404};
405
406static DOMAIN_METADATA_INFO: FeatureInfo = FeatureInfo {
407 feature_type: FeatureType::WriterOnly,
408 min_legacy_version: None,
409 feature_requirements: &[],
410 kernel_support: KernelSupport::Supported,
411 enablement_check: EnablementCheck::AlwaysIfSupported,
412};
413
414static ICEBERG_COMPAT_V1_INFO: FeatureInfo = FeatureInfo {
422 feature_type: FeatureType::WriterOnly,
423 min_legacy_version: None,
424 feature_requirements: &[
425 FeatureRequirement::Enabled(TableFeature::ColumnMapping),
426 FeatureRequirement::NotSupported(TableFeature::DeletionVectors),
427 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV2),
428 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV3),
429 ],
430 kernel_support: KernelSupport::NotSupported,
431 enablement_check: EnablementCheck::EnabledIf(|props| {
432 props.enable_iceberg_compat_v1 == Some(true)
433 }),
434};
435
436static ICEBERG_COMPAT_V2_INFO: FeatureInfo = FeatureInfo {
445 feature_type: FeatureType::WriterOnly,
446 min_legacy_version: None,
447 feature_requirements: &[
448 FeatureRequirement::Enabled(TableFeature::ColumnMapping),
449 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV1),
450 FeatureRequirement::NotEnabled(TableFeature::DeletionVectors),
451 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV3),
452 ],
453 kernel_support: KernelSupport::NotSupported,
454 enablement_check: EnablementCheck::EnabledIf(|props| {
455 props.enable_iceberg_compat_v2 == Some(true)
456 }),
457};
458
459static ICEBERG_COMPAT_V3_INFO: FeatureInfo = FeatureInfo {
479 feature_type: FeatureType::WriterOnly,
480 min_legacy_version: None,
481 feature_requirements: &[
482 FeatureRequirement::Enabled(TableFeature::ColumnMapping),
483 FeatureRequirement::Enabled(TableFeature::RowTracking),
484 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV1),
490 FeatureRequirement::NotEnabled(TableFeature::IcebergCompatV2),
491 ],
492 kernel_support: KernelSupport::Supported,
493 enablement_check: EnablementCheck::EnabledIf(|props| {
494 props.enable_iceberg_compat_v3 == Some(true)
495 }),
496};
497
498static CLUSTERED_TABLE_INFO: FeatureInfo = FeatureInfo {
499 feature_type: FeatureType::WriterOnly,
500 min_legacy_version: None,
501 feature_requirements: &[FeatureRequirement::Supported(TableFeature::DomainMetadata)],
502 kernel_support: KernelSupport::Supported,
503 enablement_check: EnablementCheck::AlwaysIfSupported,
504};
505
506static MATERIALIZE_PARTITION_COLUMNS_INFO: FeatureInfo = FeatureInfo {
507 feature_type: FeatureType::WriterOnly,
508 min_legacy_version: None,
509 feature_requirements: &[],
510 kernel_support: KernelSupport::Supported,
511 enablement_check: EnablementCheck::AlwaysIfSupported,
512};
513
514static ALLOW_COLUMN_DEFAULTS_INFO: FeatureInfo = FeatureInfo {
515 feature_type: FeatureType::WriterOnly,
516 min_legacy_version: None,
517 feature_requirements: &[],
518 kernel_support: KernelSupport::Supported,
519 enablement_check: EnablementCheck::AlwaysIfSupported,
520};
521
522static CATALOG_MANAGED_INFO: FeatureInfo = FeatureInfo {
523 feature_type: FeatureType::ReaderWriter,
524 min_legacy_version: None,
525 feature_requirements: &[FeatureRequirement::Enabled(TableFeature::InCommitTimestamp)],
526 kernel_support: KernelSupport::Custom(|_, _, op| match op {
527 Operation::Scan | Operation::Write => Ok(()),
528 Operation::Cdf => Err(Error::unsupported(
529 "Feature 'catalogManaged' is not supported for CDF",
530 )),
531 }),
532 enablement_check: EnablementCheck::AlwaysIfSupported,
533};
534
535static CATALOG_OWNED_PREVIEW_INFO: FeatureInfo = FeatureInfo {
536 feature_type: FeatureType::ReaderWriter,
537 min_legacy_version: None,
538 feature_requirements: &[FeatureRequirement::Enabled(TableFeature::InCommitTimestamp)],
539 kernel_support: KernelSupport::Custom(|_, _, op| match op {
540 Operation::Scan | Operation::Write => Ok(()),
541 Operation::Cdf => Err(Error::unsupported(
542 "Feature 'catalogOwned-preview' is not supported for CDF",
543 )),
544 }),
545 enablement_check: EnablementCheck::AlwaysIfSupported,
546};
547
548static COLUMN_MAPPING_INFO: FeatureInfo = FeatureInfo {
549 feature_type: FeatureType::ReaderWriter,
550 min_legacy_version: Some(MinReaderWriterVersion::new(2, 5)),
551 feature_requirements: &[],
552 kernel_support: KernelSupport::Supported,
553 enablement_check: EnablementCheck::EnabledIf(|props| {
554 props.column_mapping_mode.is_some()
555 && props.column_mapping_mode != Some(ColumnMappingMode::None)
556 }),
557};
558
559static DELETION_VECTORS_INFO: FeatureInfo = FeatureInfo {
560 feature_type: FeatureType::ReaderWriter,
561 min_legacy_version: None,
562 feature_requirements: &[],
563 kernel_support: KernelSupport::Supported,
567 enablement_check: EnablementCheck::EnabledIf(|props| {
568 props.enable_deletion_vectors == Some(true)
569 }),
570};
571
572#[cfg(feature = "nanosecond-timestamps")]
573#[allow(dead_code)]
574static TIMESTAMP_NANOSECOND_INFO: FeatureInfo = FeatureInfo {
575 feature_type: FeatureType::ReaderWriter,
576 min_legacy_version: None,
577 feature_requirements: &[FeatureRequirement::Enabled(
578 TableFeature::TimestampWithoutTimezone,
579 )],
580 kernel_support: KernelSupport::Supported,
581 enablement_check: EnablementCheck::AlwaysIfSupported,
582};
583
584#[allow(dead_code)]
585static TIMESTAMP_WITHOUT_TIMEZONE_INFO: FeatureInfo = FeatureInfo {
586 feature_type: FeatureType::ReaderWriter,
587 min_legacy_version: None,
588 feature_requirements: &[],
589 kernel_support: KernelSupport::Supported,
590 enablement_check: EnablementCheck::AlwaysIfSupported,
591};
592
593static TYPE_WIDENING_INFO: FeatureInfo = FeatureInfo {
594 feature_type: FeatureType::ReaderWriter,
595 min_legacy_version: None,
596 feature_requirements: &[],
597 kernel_support: KernelSupport::Supported,
601 enablement_check: EnablementCheck::EnabledIf(|props| props.enable_type_widening == Some(true)),
602};
603
604static TYPE_WIDENING_PREVIEW_INFO: FeatureInfo = FeatureInfo {
605 feature_type: FeatureType::ReaderWriter,
606 min_legacy_version: None,
607 feature_requirements: &[],
608 kernel_support: KernelSupport::Supported,
612 enablement_check: EnablementCheck::EnabledIf(|props| props.enable_type_widening == Some(true)),
613};
614
615static V2_CHECKPOINT_INFO: FeatureInfo = FeatureInfo {
616 feature_type: FeatureType::ReaderWriter,
617 min_legacy_version: None,
618 feature_requirements: &[],
619 kernel_support: KernelSupport::Supported,
620 enablement_check: EnablementCheck::AlwaysIfSupported,
621};
622
623static VACUUM_PROTOCOL_CHECK_INFO: FeatureInfo = FeatureInfo {
624 feature_type: FeatureType::ReaderWriter,
625 min_legacy_version: None,
626 feature_requirements: &[],
627 kernel_support: KernelSupport::Supported,
628 enablement_check: EnablementCheck::AlwaysIfSupported,
629};
630
631static VARIANT_TYPE_INFO: FeatureInfo = FeatureInfo {
632 feature_type: FeatureType::ReaderWriter,
633 min_legacy_version: None,
634 feature_requirements: &[],
635 kernel_support: KernelSupport::Supported,
636 enablement_check: EnablementCheck::AlwaysIfSupported,
637};
638
639static VARIANT_TYPE_PREVIEW_INFO: FeatureInfo = FeatureInfo {
640 feature_type: FeatureType::ReaderWriter,
641 min_legacy_version: None,
642 feature_requirements: &[],
643 kernel_support: KernelSupport::Supported,
644 enablement_check: EnablementCheck::AlwaysIfSupported,
645};
646
647static VARIANT_SHREDDING_INFO: FeatureInfo = FeatureInfo {
648 feature_type: FeatureType::ReaderWriter,
649 min_legacy_version: None,
650 feature_requirements: &[],
651 kernel_support: KernelSupport::Supported,
652 enablement_check: EnablementCheck::AlwaysIfSupported,
653};
654
655static VARIANT_SHREDDING_PREVIEW_INFO: FeatureInfo = FeatureInfo {
656 feature_type: FeatureType::ReaderWriter,
657 min_legacy_version: None,
658 feature_requirements: &[],
659 kernel_support: KernelSupport::Supported,
660 enablement_check: EnablementCheck::AlwaysIfSupported,
661};
662
663static ADAPTIVE_METADATA_PREVIEW_INFO: FeatureInfo = FeatureInfo {
667 feature_type: FeatureType::ReaderWriter,
668 min_legacy_version: None,
669 feature_requirements: &[
670 FeatureRequirement::Enabled(TableFeature::ColumnMapping),
671 FeatureRequirement::Custom(|_protocol, properties| {
672 require!(
673 properties.column_mapping_mode == Some(ColumnMappingMode::Id),
674 Error::invalid_protocol(
675 "Feature 'adaptiveMetadata-preview' requires column mapping in 'id' mode"
676 )
677 );
678 Ok(())
679 }),
680 FeatureRequirement::Enabled(TableFeature::RowTracking),
681 FeatureRequirement::Enabled(TableFeature::DomainMetadata),
682 FeatureRequirement::Enabled(TableFeature::DeletionVectors),
683 FeatureRequirement::Enabled(TableFeature::InCommitTimestamp),
684 ],
685 #[cfg(feature = "adaptive-metadata-in-dev")]
686 kernel_support: KernelSupport::Supported,
687 #[cfg(not(feature = "adaptive-metadata-in-dev"))]
688 kernel_support: KernelSupport::NotSupported,
689 enablement_check: EnablementCheck::AlwaysIfSupported,
690};
691
692static GEOSPATIAL_TYPE_INFO: FeatureInfo = FeatureInfo {
694 feature_type: FeatureType::ReaderWriter,
695 min_legacy_version: None,
696 feature_requirements: &[],
697 #[cfg(feature = "geo-type-in-dev")]
698 kernel_support: KernelSupport::Custom(|_, _, op| match op {
699 Operation::Scan | Operation::Cdf => Ok(()),
700 Operation::Write => Err(Error::unsupported(
701 "Feature 'geospatial' is not supported for writes",
702 )),
703 }),
704 #[cfg(not(feature = "geo-type-in-dev"))]
705 kernel_support: KernelSupport::NotSupported,
706 enablement_check: EnablementCheck::AlwaysIfSupported,
707};
708
709static UNKNOWN_FEATURE_INFO: FeatureInfo = FeatureInfo {
713 feature_type: FeatureType::Unknown,
714 min_legacy_version: None,
715 feature_requirements: &[],
716 kernel_support: KernelSupport::NotSupported,
717 enablement_check: EnablementCheck::AlwaysIfSupported,
718};
719
720impl TableFeature {
721 #[cfg(test)]
722 pub(crate) const NO_LIST: Option<Vec<TableFeature>> = None;
723 #[cfg(test)]
724 pub(crate) const EMPTY_LIST: Vec<TableFeature> = vec![];
725
726 pub(crate) fn feature_type(&self) -> FeatureType {
727 match self {
728 TableFeature::CatalogManaged
729 | TableFeature::CatalogOwnedPreview
730 | TableFeature::ColumnMapping
731 | TableFeature::DeletionVectors
732 | TableFeature::TimestampWithoutTimezone
733 | TableFeature::TypeWidening
734 | TableFeature::TypeWideningPreview
735 | TableFeature::V2Checkpoint
736 | TableFeature::VacuumProtocolCheck
737 | TableFeature::VariantType
738 | TableFeature::VariantTypePreview
739 | TableFeature::VariantShredding
740 | TableFeature::VariantShreddingPreview
741 | TableFeature::AdaptiveMetadataPreview
742 | TableFeature::GeospatialType => FeatureType::ReaderWriter,
743 TableFeature::AppendOnly
744 | TableFeature::DomainMetadata
745 | TableFeature::Invariants
746 | TableFeature::RowTracking
747 | TableFeature::CheckConstraints
748 | TableFeature::ChangeDataFeed
749 | TableFeature::GeneratedColumns
750 | TableFeature::IdentityColumns
751 | TableFeature::InCommitTimestamp
752 | TableFeature::IcebergCompatV1
753 | TableFeature::IcebergCompatV2
754 | TableFeature::IcebergCompatV3
755 | TableFeature::ClusteredTable
756 | TableFeature::MaterializePartitionColumns => FeatureType::WriterOnly,
757 TableFeature::AllowColumnDefaults => FeatureType::WriterOnly,
758 TableFeature::Unknown(_) => FeatureType::Unknown,
759 #[cfg(feature = "nanosecond-timestamps")]
760 TableFeature::TimestampNanos => FeatureType::ReaderWriter,
761 }
762 }
763
764 pub(crate) fn is_valid_for_legacy_reader(&self, reader_version: i32) -> bool {
767 matches!(&self.info().min_legacy_version, Some(v) if reader_version >= v.reader)
768 }
769
770 pub(crate) fn is_valid_for_legacy_writer(&self, writer_version: i32) -> bool {
773 matches!(&self.info().min_legacy_version, Some(v) if writer_version >= v.writer)
774 }
775
776 pub(crate) fn info(&self) -> &FeatureInfo {
779 match self {
780 TableFeature::AppendOnly => &APPEND_ONLY_INFO,
782 TableFeature::Invariants => &INVARIANTS_INFO,
783 TableFeature::CheckConstraints => &CHECK_CONSTRAINTS_INFO,
784 TableFeature::ChangeDataFeed => &CHANGE_DATA_FEED_INFO,
785 TableFeature::GeneratedColumns => &GENERATED_COLUMNS_INFO,
786 TableFeature::IdentityColumns => &IDENTITY_COLUMNS_INFO,
787 TableFeature::InCommitTimestamp => &IN_COMMIT_TIMESTAMP_INFO,
788 TableFeature::RowTracking => &ROW_TRACKING_INFO,
789 TableFeature::DomainMetadata => &DOMAIN_METADATA_INFO,
790 TableFeature::IcebergCompatV1 => &ICEBERG_COMPAT_V1_INFO,
791 TableFeature::IcebergCompatV2 => &ICEBERG_COMPAT_V2_INFO,
792 TableFeature::IcebergCompatV3 => &ICEBERG_COMPAT_V3_INFO,
793 TableFeature::ClusteredTable => &CLUSTERED_TABLE_INFO,
794 TableFeature::MaterializePartitionColumns => &MATERIALIZE_PARTITION_COLUMNS_INFO,
795 TableFeature::AllowColumnDefaults => &ALLOW_COLUMN_DEFAULTS_INFO,
796
797 TableFeature::CatalogManaged => &CATALOG_MANAGED_INFO,
799 TableFeature::CatalogOwnedPreview => &CATALOG_OWNED_PREVIEW_INFO,
800 TableFeature::ColumnMapping => &COLUMN_MAPPING_INFO,
801 TableFeature::DeletionVectors => &DELETION_VECTORS_INFO,
802 #[cfg(feature = "nanosecond-timestamps")]
803 TableFeature::TimestampNanos => &TIMESTAMP_NANOSECOND_INFO,
804 TableFeature::TimestampWithoutTimezone => &TIMESTAMP_WITHOUT_TIMEZONE_INFO,
805 TableFeature::TypeWidening => &TYPE_WIDENING_INFO,
806 TableFeature::TypeWideningPreview => &TYPE_WIDENING_PREVIEW_INFO,
807 TableFeature::V2Checkpoint => &V2_CHECKPOINT_INFO,
808 TableFeature::VacuumProtocolCheck => &VACUUM_PROTOCOL_CHECK_INFO,
809 TableFeature::VariantType => &VARIANT_TYPE_INFO,
810 TableFeature::VariantTypePreview => &VARIANT_TYPE_PREVIEW_INFO,
811 TableFeature::VariantShredding => &VARIANT_SHREDDING_INFO,
812 TableFeature::VariantShreddingPreview => &VARIANT_SHREDDING_PREVIEW_INFO,
813 TableFeature::AdaptiveMetadataPreview => &ADAPTIVE_METADATA_PREVIEW_INFO,
814 TableFeature::GeospatialType => &GEOSPATIAL_TYPE_INFO,
815
816 TableFeature::Unknown(_) => &UNKNOWN_FEATURE_INFO,
818 }
819 }
820}
821
822impl ToDataType for TableFeature {
823 fn to_data_type() -> DataType {
824 DataType::STRING
825 }
826}
827
828impl From<TableFeature> for Scalar {
829 fn from(feature: TableFeature) -> Self {
830 Scalar::String(feature.to_string())
831 }
832}
833
834#[cfg(test)] impl TableFeature {
836 pub(crate) fn unknown(s: impl ToString) -> Self {
837 TableFeature::Unknown(s.to_string())
838 }
839}
840
841impl From<String> for TableFeature {
842 fn from(value: String) -> Self {
843 value.as_str().into()
844 }
845}
846
847impl From<&TableFeature> for TableFeature {
848 fn from(value: &TableFeature) -> Self {
849 value.clone()
850 }
851}
852
853pub(crate) fn format_features(features: &[TableFeature]) -> String {
855 let feature_strings: Vec<&str> = features.iter().map(|f| f.as_ref()).collect_vec();
856 format!("[{}]", feature_strings.join(", "))
857}
858
859pub(crate) fn extract_enabled_reader_features(protocol: &Protocol) -> Vec<TableFeature> {
862 match protocol.min_reader_version() {
863 TABLE_FEATURES_MIN_READER_VERSION => protocol
864 .reader_features()
865 .map(|f| f.to_vec())
866 .unwrap_or_default(),
867 v if (1..=2).contains(&v) => LEGACY_READER_FEATURES
868 .iter()
869 .filter(|f| f.is_valid_for_legacy_reader(v))
870 .cloned()
871 .collect(),
872 _ => Vec::new(),
873 }
874}
875
876pub(crate) fn add_feature_to_lists(
878 feature: TableFeature,
879 reader_features: &mut Vec<TableFeature>,
880 writer_features: &mut Vec<TableFeature>,
881) {
882 match feature.feature_type() {
883 FeatureType::ReaderWriter => {
884 if !reader_features.contains(&feature) {
885 reader_features.push(feature.clone());
886 }
887 if !writer_features.contains(&feature) {
888 writer_features.push(feature);
889 }
890 }
891 FeatureType::WriterOnly | FeatureType::Unknown => {
892 if !writer_features.contains(&feature) {
893 writer_features.push(feature);
894 }
895 }
896 }
897}
898
899pub(crate) fn auto_enable_property_driven_features(
905 allowed_table_features: &[TableFeature],
906 table_properties: &TableProperties,
907 reader_features: &mut Vec<TableFeature>,
908 writer_features: &mut Vec<TableFeature>,
909) {
910 for table_feature in allowed_table_features {
911 if let EnablementCheck::EnabledIf(check) = table_feature.info().enablement_check {
912 if check(table_properties) {
913 add_feature_to_lists(table_feature.clone(), reader_features, writer_features);
914 if *table_feature == TableFeature::RowTracking {
915 add_feature_to_lists(
916 TableFeature::DomainMetadata,
917 reader_features,
918 writer_features,
919 );
920 }
921 }
922 }
923 }
924}
925
926pub(crate) fn check_reader_version_range(protocol: &Protocol) -> DeltaResult<()> {
930 require!(
931 protocol.min_reader_version() >= MIN_VALID_RW_VERSION,
932 Error::InvalidProtocol(format!(
933 "min_reader_version must be >= {MIN_VALID_RW_VERSION}, got {}",
934 protocol.min_reader_version()
935 ))
936 );
937 if protocol.min_reader_version() > MAX_VALID_READER_VERSION {
938 return Err(Error::unsupported(format!(
939 "Unsupported minimum reader version {}",
940 protocol.min_reader_version()
941 )));
942 }
943 Ok(())
944}
945
946pub(crate) fn ensure_table_can_be_read(protocol: &Protocol) -> DeltaResult<()> {
951 check_reader_version_range(protocol)?;
952
953 for feature in extract_enabled_reader_features(protocol) {
954 match feature.info().kernel_support {
955 KernelSupport::Supported => {}
956 KernelSupport::NotSupported => {
957 return Err(Error::unsupported(format!(
958 "Feature '{feature}' is not supported by kernel",
959 )));
960 }
961 KernelSupport::Custom(_) => {}
962 }
963 }
964
965 Ok(())
966}
967
968#[cfg(test)]
969mod tests {
970 use rstest::rstest;
971
972 use super::*;
973
974 #[test]
975 fn test_unknown_features() {
976 let mixed_reader = &[
977 TableFeature::DeletionVectors,
978 TableFeature::unknown("cool_feature"),
979 TableFeature::ColumnMapping,
980 ];
981 let mixed_writer = &[
982 TableFeature::DeletionVectors,
983 TableFeature::unknown("cool_feature"),
984 TableFeature::AppendOnly,
985 ];
986
987 let reader_string = serde_json::to_string(mixed_reader).unwrap();
988 let writer_string = serde_json::to_string(mixed_writer).unwrap();
989
990 assert_eq!(
991 &reader_string,
992 "[\"deletionVectors\",\"cool_feature\",\"columnMapping\"]"
993 );
994 assert_eq!(
995 &writer_string,
996 "[\"deletionVectors\",\"cool_feature\",\"appendOnly\"]"
997 );
998
999 let typed_reader: Vec<TableFeature> = serde_json::from_str(&reader_string).unwrap();
1000 let typed_writer: Vec<TableFeature> = serde_json::from_str(&writer_string).unwrap();
1001
1002 assert_eq!(typed_reader.len(), 3);
1003 assert_eq!(&typed_reader, mixed_reader);
1004 assert_eq!(typed_writer.len(), 3);
1005 assert_eq!(&typed_writer, mixed_writer);
1006 }
1007
1008 enum ExpectRead {
1011 Ok,
1012 InvalidProtocol,
1013 Unsupported,
1014 }
1015
1016 #[rstest]
1017 #[case::reader_version_below_minimum(
1018 Protocol::new_unchecked(0, 1, None, None),
1019 ExpectRead::InvalidProtocol
1020 )]
1021 #[case::reader_version_above_maximum(
1022 Protocol::new_unchecked(99, 1, None, None),
1023 ExpectRead::Unsupported
1024 )]
1025 #[case::legacy_reader_v1(Protocol::try_new_legacy(1, 1).unwrap(), ExpectRead::Ok)]
1026 #[case::legacy_reader_v2(Protocol::try_new_legacy(2, 5).unwrap(), ExpectRead::Ok)]
1027 #[case::v3_empty_reader_features(
1028 Protocol::new_unchecked(3, 7, Some(vec![]), Some(vec![])),
1029 ExpectRead::Ok
1030 )]
1031 #[case::supported_explicit_feature(
1032 Protocol::try_new_modern(
1033 [TableFeature::DeletionVectors],
1034 [TableFeature::DeletionVectors],
1035 )
1036 .unwrap(),
1037 ExpectRead::Ok
1038 )]
1039 #[case::unknown_reader_feature(
1040 Protocol::try_new_modern(
1041 [TableFeature::unknown("notARealFeature")],
1042 [TableFeature::unknown("notARealFeature")],
1043 )
1044 .unwrap(),
1045 ExpectRead::Unsupported
1046 )]
1047 #[case::custom_support_feature(
1048 Protocol::try_new_modern(
1049 [TableFeature::CatalogManaged],
1050 [TableFeature::CatalogManaged],
1051 )
1052 .unwrap(),
1053 ExpectRead::Ok
1054 )]
1055 #[cfg_attr(
1058 feature = "adaptive-metadata-in-dev",
1059 case::adaptive_metadata_supported(
1060 Protocol::try_new_modern(
1061 [TableFeature::AdaptiveMetadataPreview],
1062 [TableFeature::AdaptiveMetadataPreview],
1063 )
1064 .unwrap(),
1065 ExpectRead::Ok
1066 )
1067 )]
1068 #[cfg_attr(
1069 not(feature = "adaptive-metadata-in-dev"),
1070 case::adaptive_metadata_gated_off(
1071 Protocol::try_new_modern(
1072 [TableFeature::AdaptiveMetadataPreview],
1073 [TableFeature::AdaptiveMetadataPreview],
1074 )
1075 .unwrap(),
1076 ExpectRead::Unsupported
1077 )
1078 )]
1079 fn validate_protocol_for_read(#[case] protocol: Protocol, #[case] expected: ExpectRead) {
1080 let result = ensure_table_can_be_read(&protocol);
1081 match expected {
1082 ExpectRead::Ok => result.expect("protocol must be readable"),
1083 ExpectRead::InvalidProtocol => assert!(
1084 matches!(result, Err(Error::InvalidProtocol(_))),
1085 "expected InvalidProtocol, got: {result:?}"
1086 ),
1087 ExpectRead::Unsupported => assert!(
1088 matches!(result, Err(Error::Unsupported(_))),
1089 "expected Unsupported, got: {result:?}"
1090 ),
1091 }
1092 }
1093
1094 #[test]
1095 fn test_timestamp_ntz_legacy_alias() {
1096 assert_eq!(
1097 TableFeature::from("timestampNtz"),
1098 TableFeature::TimestampWithoutTimezone
1099 );
1100 assert_eq!(
1101 TableFeature::from("timestampWithoutTimezone"),
1102 TableFeature::TimestampWithoutTimezone
1103 );
1104
1105 assert_eq!(
1106 serde_json::from_str::<TableFeature>("\"timestampNtz\"").unwrap(),
1107 TableFeature::TimestampWithoutTimezone
1108 );
1109 assert_eq!(
1110 serde_json::from_str::<TableFeature>("\"timestampWithoutTimezone\"").unwrap(),
1111 TableFeature::TimestampWithoutTimezone
1112 );
1113
1114 assert_eq!(
1115 TableFeature::TimestampWithoutTimezone.to_string(),
1116 "timestampNtz"
1117 );
1118 assert_eq!(
1119 TableFeature::TimestampWithoutTimezone.as_ref(),
1120 "timestampNtz"
1121 );
1122 assert_eq!(
1123 serde_json::to_string(&TableFeature::TimestampWithoutTimezone).unwrap(),
1124 "\"timestampNtz\""
1125 );
1126 }
1127
1128 #[test]
1129 fn test_roundtrip_table_features() {
1130 use strum::IntoEnumIterator as _;
1131
1132 for feature in TableFeature::iter() {
1133 let expected = match feature {
1134 TableFeature::AppendOnly => "appendOnly",
1135 TableFeature::Invariants => "invariants",
1136 TableFeature::CheckConstraints => "checkConstraints",
1137 TableFeature::ChangeDataFeed => "changeDataFeed",
1138 TableFeature::GeneratedColumns => "generatedColumns",
1139 TableFeature::IdentityColumns => "identityColumns",
1140 TableFeature::InCommitTimestamp => "inCommitTimestamp",
1141 TableFeature::RowTracking => "rowTracking",
1142 TableFeature::DomainMetadata => "domainMetadata",
1143 TableFeature::IcebergCompatV1 => "icebergCompatV1",
1144 TableFeature::IcebergCompatV2 => "icebergCompatV2",
1145 TableFeature::IcebergCompatV3 => "icebergCompatV3",
1146 TableFeature::ClusteredTable => "clustering",
1147 TableFeature::MaterializePartitionColumns => "materializePartitionColumns",
1148 TableFeature::CatalogManaged => "catalogManaged",
1149 TableFeature::CatalogOwnedPreview => "catalogOwned-preview",
1150 TableFeature::ColumnMapping => "columnMapping",
1151 TableFeature::DeletionVectors => "deletionVectors",
1152 #[cfg(feature = "nanosecond-timestamps")]
1153 TableFeature::TimestampNanos => "timestampNanos",
1154 TableFeature::TimestampWithoutTimezone => "timestampNtz",
1155 TableFeature::TypeWidening => "typeWidening",
1156 TableFeature::TypeWideningPreview => "typeWidening-preview",
1157 TableFeature::V2Checkpoint => "v2Checkpoint",
1158 TableFeature::VacuumProtocolCheck => "vacuumProtocolCheck",
1159 TableFeature::VariantType => "variantType",
1160 TableFeature::VariantTypePreview => "variantType-preview",
1161 TableFeature::VariantShredding => "variantShredding",
1162 TableFeature::VariantShreddingPreview => "variantShredding-preview",
1163 TableFeature::AdaptiveMetadataPreview => "adaptiveMetadata-preview",
1164 TableFeature::AllowColumnDefaults => "allowColumnDefaults",
1165 TableFeature::GeospatialType => "geospatial",
1166 TableFeature::Unknown(_) => continue, };
1168
1169 assert_eq!(feature.to_string(), expected);
1171 assert_eq!(feature, TableFeature::from(expected));
1172
1173 let serialized = serde_json::to_string(&feature).unwrap();
1175 assert_eq!(serialized, format!("\"{expected}\""));
1176
1177 let deserialized: TableFeature = serde_json::from_str(&serialized).unwrap();
1178 assert_eq!(deserialized, feature);
1179 }
1180 }
1181}