Skip to main content

buoyant_kernel/table_features/
mod.rs

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
49/// Minimum reader/writer protocol version that the kernel can handle.
50pub const MIN_VALID_RW_VERSION: i32 = 1;
51
52/// Maximum reader protocol version that the kernel can handle.
53pub const MAX_VALID_READER_VERSION: i32 = 3;
54
55/// Maximum writer protocol version that the kernel can handle.
56pub const MAX_VALID_WRITER_VERSION: i32 = 7;
57
58/// Minimum reader version for tables that use table features.
59/// When set to 3, the protocol requires an explicit `readerFeatures` array.
60pub const TABLE_FEATURES_MIN_READER_VERSION: i32 = 3;
61
62/// Minimum writer version for tables that use table features.
63/// When set to 7, the protocol requires an explicit `writerFeatures` array.
64pub const TABLE_FEATURES_MIN_WRITER_VERSION: i32 = 7;
65
66/// Prefix for table feature override properties.
67/// Properties with this prefix (e.g., `delta.feature.deletionVectors`) are used to
68/// explicitly turn on support for the feature in the protocol.
69pub const SET_TABLE_FEATURE_SUPPORTED_PREFIX: &str = "delta.feature.";
70
71/// Value to add support for a table feature when used with [`SET_TABLE_FEATURE_SUPPORTED_PREFIX`].
72/// Example: `"delta.feature.deletionVectors" -> "supported"`
73pub const SET_TABLE_FEATURE_SUPPORTED_VALUE: &str = "supported";
74
75/// Table features represent protocol capabilities required to correctly read or write a given
76/// table.
77/// - Readers must implement all features required for correct table reads.
78/// - Writers must implement all features required for correct table writes.
79///
80/// Each variant corresponds to one such feature. A feature is either:
81/// - **ReaderWriter** (must be supported by both readers and writers), or
82/// - **WriterOnly** (applies only to writers).
83/// There are no ReaderOnly features. See `TableFeature::feature_type` for the category of each.
84///
85/// The kernel currently supports all reader features.
86#[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)]
103// ^^ We must derive EnumIter only after internal_api adjusts visibility. Otherwise, internal-api
104// builds will fail because the now-public `TableFeature::iter()` returns a pub(crate) type.
105pub(crate) enum TableFeature {
106    //////////////////////////
107    // Writer-only features //
108    //////////////////////////
109    /// Append Only Tables
110    AppendOnly,
111    /// Table invariants
112    Invariants,
113    /// Check constraints on columns
114    CheckConstraints,
115    /// CDF on a table
116    ChangeDataFeed,
117    /// Columns with generated values
118    GeneratedColumns,
119    /// ID Columns
120    IdentityColumns,
121    /// Monotonically increasing timestamps in the CommitInfo
122    InCommitTimestamp,
123    /// Row tracking on tables
124    RowTracking,
125    /// domain specific metadata
126    DomainMetadata,
127    /// Iceberg V1 compatibility support
128    IcebergCompatV1,
129    /// Iceberg V2 compatibility support
130    IcebergCompatV2,
131    /// Iceberg V3 compatibility support
132    IcebergCompatV3,
133    /// The Clustered Table feature facilitates the physical clustering of rows
134    /// that share similar values on a predefined set of clustering columns.
135    #[strum(serialize = "clustering")]
136    #[serde(rename = "clustering")]
137    ClusteredTable,
138    /// Materialize partition columns in parquet data files.
139    MaterializePartitionColumns,
140    /// Column Default Values.
141    AllowColumnDefaults,
142
143    ///////////////////////////
144    // ReaderWriter features //
145    ///////////////////////////
146    /// CatalogManaged tables:
147    /// <https://github.com/delta-io/delta/blob/master/protocol_rfcs/catalog-managed.md>
148    CatalogManaged,
149    #[strum(serialize = "catalogOwned-preview")]
150    #[serde(rename = "catalogOwned-preview")]
151    CatalogOwnedPreview,
152    /// Mapping of one column to another
153    ColumnMapping,
154    /// Deletion vectors for merge, update, delete
155    DeletionVectors,
156    /// Nanosecond resolution timestamps
157    #[cfg(feature = "nanosecond-timestamps")]
158    #[strum(serialize = "timestampNanos")]
159    #[serde(rename = "timestampNanos")]
160    TimestampNanos,
161    /// Timestamps without timezone support. The canonical protocol feature name is `timestampNtz`.
162    ///
163    /// `timestampWithoutTimezone` is not a Delta protocol feature name, but some existing tables
164    /// carry it in their reader/writer feature arrays. Kernel accepts it on read for compatibility
165    /// with those tables and always writes the canonical `timestampNtz`. See
166    /// <https://github.com/delta-io/delta-kernel-rs/issues/2557>.
167    #[strum(to_string = "timestampNtz", serialize = "timestampWithoutTimezone")]
168    #[serde(rename = "timestampNtz", alias = "timestampWithoutTimezone")]
169    TimestampWithoutTimezone,
170
171    // Allow columns to change type
172    TypeWidening,
173    #[strum(serialize = "typeWidening-preview")]
174    #[serde(rename = "typeWidening-preview")]
175    TypeWideningPreview,
176    /// version 2 of checkpointing
177    V2Checkpoint,
178    /// vacuumProtocolCheck ReaderWriter feature ensures consistent application of reader and
179    /// writer protocol checks during VACUUM operations
180    VacuumProtocolCheck,
181    /// This feature enables support for the variant data type, which stores semi-structured data.
182    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    /// Iceberg V4 adaptive metadata tree as the table's native content metadata format.
191    ///
192    /// TODO(#2866): gated by the `adaptive-metadata-in-dev` cargo feature until fully supported.
193    #[strum(serialize = "adaptiveMetadata-preview")]
194    #[serde(rename = "adaptiveMetadata-preview")]
195    AdaptiveMetadataPreview,
196    /// Geospatial type support (geometry and geography columns)
197    #[strum(serialize = "geospatial")]
198    #[serde(rename = "geospatial")]
199    GeospatialType,
200
201    #[serde(untagged)]
202    #[strum(default)]
203    Unknown(String),
204}
205
206/// ReaderWriter features that can be supported by legacy readers (min_reader_version < 3).
207/// Only ColumnMapping qualifies with min_reader_version = 2.
208pub(crate) static LEGACY_READER_FEATURES: [TableFeature; 1] = [TableFeature::ColumnMapping];
209
210/// Writer and ReaderWriter features that can be supported by legacy writers (min_writer_version <
211/// 7). These are features with min_writer_version in range [1, 6].
212pub(crate) static LEGACY_WRITER_FEATURES: [TableFeature; 7] = [
213    // Writer-only features (min_writer < 7)
214    TableFeature::AppendOnly,       // min_writer = 2
215    TableFeature::Invariants,       // min_writer = 2
216    TableFeature::CheckConstraints, // min_writer = 3
217    TableFeature::ChangeDataFeed,   // min_writer = 4
218    TableFeature::GeneratedColumns, // min_writer = 4
219    TableFeature::IdentityColumns,  // min_writer = 6
220    // ReaderWriter features (min_writer < 7)
221    TableFeature::ColumnMapping, // min_writer = 5
222];
223
224/// Classifies table features by their type
225#[derive(Debug, Clone, Copy, PartialEq, Eq)]
226pub(crate) enum FeatureType {
227    /// Feature only affects write operations
228    WriterOnly,
229    /// Feature affects both read and write operations (must appear in both feature lists)
230    ReaderWriter,
231    /// Unknown feature type (for forward compatibility)
232    Unknown,
233}
234
235/// Defines how a feature's enablement is determined
236#[derive(Debug, Clone, Copy)]
237pub(crate) enum EnablementCheck {
238    /// Feature is enabled if it's supported (appears in protocol feature lists)
239    AlwaysIfSupported,
240    /// Feature is enabled if supported AND the provided function returns true when checking table
241    /// properties
242    EnabledIf(fn(&TableProperties) -> bool),
243}
244
245/// Represents the type of operation being performed on a table
246#[derive(Debug, Clone, Copy, PartialEq, Eq)]
247#[internal_api]
248pub(crate) enum Operation {
249    /// Read operations on regular table data
250    Scan,
251    /// Read operations on change data feed data
252    Cdf,
253    /// Write operations on regular table data
254    Write,
255}
256
257/// Defines whether the Rust kernel has implementation support for a feature's operation
258pub(crate) enum KernelSupport {
259    /// Kernel has full support for any operation on this feature
260    Supported,
261    /// Kernel does not support this operation on this feature
262    NotSupported,
263    /// Custom logic to determine support based on operation type and table properties.
264    /// For example: Column Mapping may support Scan but not CDF, or CDF writes may only
265    /// be supported when AppendOnly is true.
266    Custom(fn(&Protocol, &TableProperties, Operation) -> DeltaResult<()>),
267}
268
269/// Types of requirements for feature dependencies
270#[derive(Debug)]
271pub(crate) enum FeatureRequirement {
272    /// Feature must be supported (in protocol)
273    Supported(TableFeature),
274    /// Feature must be enabled (supported + property set)
275    Enabled(TableFeature),
276    /// Feature must NOT be supported
277    NotSupported(TableFeature),
278    /// Feature must NOT be enabled (may be supported but property must not activate it)
279    NotEnabled(TableFeature),
280    /// Custom validation logic run against the protocol and table properties.
281    Custom(fn(&Protocol, &TableProperties) -> DeltaResult<()>),
282}
283
284/// Minimum protocol versions for legacy (pre-feature-list) inference.
285pub(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
296/// Rich metadata about a table feature including version requirements, dependencies, and support
297/// status
298pub(crate) struct FeatureInfo {
299    /// The type of feature (WriterOnly, ReaderWriter, or Unknown)
300    pub feature_type: FeatureType,
301    /// Minimum legacy protocol versions for version-based feature inference.
302    /// `Some` for features that predate feature lists and can be inferred from protocol version.
303    /// `None` for features that require explicit feature lists (reader v3+ / writer v7+).
304    pub min_legacy_version: Option<MinReaderWriterVersion>,
305    /// Requirements this feature has (features + custom validations)
306    pub feature_requirements: &'static [FeatureRequirement],
307    /// Rust kernel's support for this feature (may vary by Operation type)
308    ///
309    /// Note: `kernel_support` validation depends on `feature_type`:
310    /// WriterOnly features: Only checked during `Operation::Write`
311    /// ReaderWriter features: Checked during all operations (Scan/Write/CDF)
312    /// Read operations (Scan/CDF) only validate reader features, so `kernel_support` for
313    /// WriterOnly features are never invoked for Scan/CDF regardless of the custom check logic.
314    pub kernel_support: KernelSupport,
315    /// How to check if this feature is enabled in a table
316    pub enablement_check: EnablementCheck,
317}
318
319// Static FeatureInfo instances for each table feature
320static 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
328// Although kernel marks invariants as "Supported", invariants must NOT actually be present in the
329// table schema. Kernel will fail to write to any table that actually uses invariants (see check in
330// TableConfiguration::ensure_write_supported). This is to allow legacy tables with the Invariants
331// feature enabled but not in use.
332static 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
386// TODO(#2538): Currently we reject `Transaction::commit` when it contains staged remove-file
387// actions on RowTracking-supported (and not-suspended) tables because
388//   1. kernel does not yet materialize stable row IDs / commit versions on write, which blocks COW
389//      rewrites,
390//   2. kernel does not yet validate if remove actions correctly reserved row IDs / commit versions.
391// Unblock after both 1 and 2 are supported.
392//
393// TODO: When kernel writes the materialized `row_id` / `row_commit_version` columns, they must
394// use the reserved parquet field IDs defined by the protocol on IcebergCompatV3 tables, not
395// auto-assigned IDs.
396static 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
414// TODO(#1125): IcebergCompatV1 requires schema type validation to block Map, Array, and Void types.
415// This validation is not yet implemented. The feature is marked as NotSupported for writes until
416// proper validation is added.
417//
418// See Delta Spark: IcebergCompat.scala CheckNoListMapNullType (lines 422-433)
419// See Java Kernel: IcebergWriterCompatMetadataValidatorAndUpdater.java
420// UNSUPPORTED_TYPES_CHECK See https://github.com/delta-io/delta/blob/master/PROTOCOL.md#writer-requirements-for-icebergcompatv1 for more requirements to support
421static 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
436// TODO(#1125): IcebergCompatV2 requires schema type validation. Unlike V1, V2 allows Map and Array
437// types but needs validation against an allowlist of supported types.
438// This validation is not yet implemented. The feature is marked as NotSupported for writes until
439// proper validation is added.
440
441// See Delta Spark: IcebergCompat.scala CheckTypeInV2AllowList (lines 450-459)
442// See Java Kernel: IcebergCompatMetadataValidatorAndUpdater.java V2_SUPPORTED_TYPES
443// See https://github.com/delta-io/delta/blob/master/PROTOCOL.md#writer-requirements-for-icebergcompatv2 for more requirements to support.
444static 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
459/// IcebergCompatV3 ensures tables can be converted to Apache Iceberg V3.
460///
461/// Spec: <https://github.com/delta-io/delta/blob/master/protocol_rfcs/iceberg-compat-v3.md>
462///
463/// TODO(#2492): Implement the schema-evolution requirements for IcebergCompatV3.
464/// TODO: Support ALTER TABLE on tables with IcebergCompatV3 enabled.
465///
466/// Requirements to enforce when the corresponding write paths are supported:
467/// - Geo types: when supported, they must not be usable as partition columns on IcebergCompatV3
468///   tables.
469/// - REPLACE TABLE: when supported, partition columns must not change across the replace.
470/// - Timestamp parquet encoding: when kernel can write INT96 or INT64, IcebergCompatV3 tables must
471///   always use INT64; INT96 is forbidden.
472/// - ALTER TABLE SET/UNSET TBLPROPERTIES: when supported, reject any property change that would
473///   disable IcebergCompatV3 on an existing table.
474/// - Void type: when delta-spark supports VOID type on icebergCompatV3 tables, add it to V3's type
475///   allowlist (`is_v3_supported_type` in `iceberg_compat::v3`).
476///
477/// Tracking issue: <https://github.com/delta-io/delta-kernel-rs/issues/2492>
478static 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        // Unlike V1/V2, V3 intentionally permits DeletionVectors per the RFC. No
485        // `NotEnabled(DeletionVectors)` requirement is needed.
486        //
487        // V1/V2 may remain in `writerFeatures` (supported) as long as they are not active,
488        // hence `NotEnabled` rather than `NotSupported`.
489        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    // The kernel can read DV-bearing tables and install connector-authored DV descriptors via
564    // `Transaction::update_deletion_vectors`, including through the FFI
565    // `transaction_update_deletion_vectors` path.
566    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    // TODO(#2492): When type widening is supported on ALTER TABLE, restrict the allowed widenings
598    // on IcebergCompatV3 tables to the subset permitted by Iceberg V3 schema-evolution rules.
599    // Ref: <https://iceberg.apache.org/spec/#schema-evolution>
600    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    // TODO(#2492): When type widening is supported on ALTER TABLE, restrict the allowed widenings
609    // on IcebergCompatV3 tables to the subset permitted by Iceberg V3 schema-evolution rules.
610    // Ref: <https://iceberg.apache.org/spec/#schema-evolution>
611    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
663// Dependencies per the adaptiveMetadata RFC (delta-io/delta#6978) "Table Feature Enablement"
664// section. Enforcement is covered by `test_adaptive_metadata_feature_requirements`.
665// TODO(#2866): drop the `adaptive-metadata-in-dev` gate once adaptiveMetadata is fully supported.
666static 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
692// TODO(#2949): drop the `geo-type-in-dev` gate once full geospatial support ships.
693static 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
709/// By definition, kernel cannot know how to handle unknown features and must assume they're always
710/// enabled if supported in protocol. However, the read path ignores all writer-only features,
711/// including unknown ones. Unknown features are never inferred from legacy protocol versions.
712static 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    /// Returns true if this feature can be inferred from a legacy reader protocol version.
765    /// Always returns false for modern features (use feature lists instead).
766    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    /// Returns true if this feature can be inferred from a legacy writer protocol version.
771    /// Always returns false for modern features (use feature lists instead).
772    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    /// Returns rich metadata about this table feature including protocol version requirements,
777    /// dependencies, and kernel support status.
778    pub(crate) fn info(&self) -> &FeatureInfo {
779        match self {
780            // Writer-only features
781            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            // ReaderWriter features
798            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            // Unknown features: not supported by kernel, no legacy version inference.
817            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)] // currently only used in tests
835impl 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
853/// Formats a slice of table features using Delta's standard serialization (camelCase).
854pub(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
859/// Extract the reader features enabled for `protocol`. For `min_reader_version == 3` returns the
860/// explicit `reader_features` list; for `1..=2` returns the legacy-inferred features.
861pub(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
876/// Add `feature` to the appropriate feature list(s) for its type, skipping duplicates.
877pub(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
899/// Enable each `allowed_table_features` entry whose [`EnablementCheck::EnabledIf`] check is
900/// satisfied by `table_properties`, appending it to `reader_features`/`writer_features`
901/// (deduplicated). Features with [`EnablementCheck::AlwaysIfSupported`] are skipped since they need
902/// no property-driven enablement. `RowTracking` additionally pulls in its `DomainMetadata`
903/// dependency.
904pub(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
926/// Enforce that `protocol.min_reader_version()` lies within
927/// [`MIN_VALID_RW_VERSION`]..=[`MAX_VALID_READER_VERSION`]. Below the minimum yields
928/// [`Error::InvalidProtocol`]; above the maximum yields [`Error::Unsupported`].
929pub(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
946/// Protocol-level check that the kernel can read tables governed by `protocol`.
947///
948/// Unlike `TableConfiguration::ensure_operation_supported`, this does not require a
949/// `Metadata` action or any table properties.
950pub(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    /// Expected outcome of `ensure_table_can_be_read` for a given protocol: either readable,
1009    /// or an error of a specific variant.
1010    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    // adaptiveMetadata-preview is gated by the `adaptive-metadata-in-dev` cargo feature: readable
1056    // only when the flag is on, otherwise rejected as unsupported.
1057    #[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, // tested in test_unknown_features
1167            };
1168
1169            // strum
1170            assert_eq!(feature.to_string(), expected);
1171            assert_eq!(feature, TableFeature::from(expected));
1172
1173            // json
1174            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}