Package io.delta.kernel.internal.tablefeatures

Class TableFeature

Object
io.delta.kernel.internal.tablefeatures.TableFeature
Direct Known Subclasses:
TableFeature.LegacyReaderWriterFeature, TableFeature.LegacyWriterFeature, TableFeature.ReaderWriterFeature, TableFeature.WriterFeature
public abstract class TableFeature extends Object
Base class for table features.

A feature can be explicitly supported by a table's protocol when the protocol contains a feature's `name`. Writers (for writer-only features) or readers and writers (for reader-writer features) must recognize supported features and must handle them appropriately.

A table feature that released before Delta Table Features (reader version 3 and writer version 7) is considered as a legacy feature. Legacy features are implicitly supported when (a) the protocol does not support table features, i.e., has reader version less than 3 or writer version less than 7 and (b) the feature's minimum reader/writer version is less than or equal to the current protocol's reader/writer version.

Separately, a feature can be automatically supported by a table's metadata when certain feature-specific table properties are set. For example, `changeDataFeed` is automatically supported when there's a table property `delta.enableChangeDataFeed=true`. See FeatureAutoEnabledByMetadata for details on how to define such features. This is independent of the table's enabled features. When a feature is supported (explicitly or implicitly) by the table protocol but its metadata requirements are not satisfied, then clients still have to understand the feature (at least to the extent that they can read and preserve the existing data in the table that uses the feature).

Important note: uses the default implementation of `equals` and `hashCode` methods. We expect that the feature instances are singletons, so we don't need to compare the fields.

  • Constructor Details

    • TableFeature

      public TableFeature(String featureName, int minReaderVersion, int minWriterVersion)
      Constructor. Does validations to make sure:
      • Feature name is not null or empty and has valid characters
      • minReaderVersion is always 0 for writer features
      Parameters:
      featureName - a globally-unique string indicator to represent the feature. All characters must be letters (a-z, A-Z), digits (0-9), '-', or '_'. Words must be in camelCase.
      minReaderVersion - the minimum reader version this feature requires. For a feature that can only be explicitly supported, this is either `0` (i.e writerOnly feature) or `3` (the reader protocol version that supports table features), depending on the feature is writer-only or reader-writer. For a legacy feature that can be implicitly supported, this is the first protocol version which the feature is introduced.
      minWriterVersion - the minimum writer version this feature requires. For a feature that can only be explicitly supported, this is the writer protocol `7` that supports table features. For a legacy feature that can be implicitly supported, this is the first protocol version which the feature is introduced.

  • Method Details

    • featureName

      public String featureName()
      Returns:
      the name of the table feature.

    • isReaderWriterFeature

      public boolean isReaderWriterFeature()
      Returns:
      true if this feature is applicable to both reader and writer, false if it is writer-only.

    • minReaderVersion

      public int minReaderVersion()
      Returns:
      the minimum reader version this feature requires

    • minWriterVersion

      public int minWriterVersion()
      Returns:
      the minimum writer version that this feature requires.

    • isLegacyFeature

      public boolean isLegacyFeature()
      Returns:
      if this feature is a legacy feature?

    • requiredFeatures

      public Set<TableFeature> requiredFeatures()
      Set of table features that this table feature depends on. I.e. the set of features that need to be enabled if this table feature is enabled.
      Returns:
      the set of table features that this table feature depends on.

    • hasKernelReadSupport

      public boolean hasKernelReadSupport()
      Does Kernel has support to read a table containing this feature? Default implementation returns true. Features should override this method if they have special requirements or not supported by the Kernel yet.
      Returns:
      true if Kernel has support to read a table containing this feature.

    • hasKernelWriteSupport

      public boolean hasKernelWriteSupport(Metadata metadata)
      Does Kernel has support to write a table containing this feature? Default implementation returns true. Features should override this method if they have special requirements or not supported by the Kernel yet.
      Parameters:
      metadata - the metadata of the table. Sometimes checking the metadata is necessary to know the Kernel can write the table or not.
      Returns:
      true if Kernel has support to write a table containing this feature.

    • getTableFeatureSupportKey

      public String getTableFeatureSupportKey()
      Gets the key that turns on support for the respective table feature.
      Returns:
      the feature support key for the respective feature.