Package org.apache.flink.table.types.logical

Class StructuredType

java.lang.Object
org.apache.flink.table.types.logical.LogicalType
org.apache.flink.table.types.logical.UserDefinedType
org.apache.flink.table.types.logical.StructuredType
All Implemented Interfaces:
Serializable
@PublicEvolving public final class StructuredType extends org.apache.flink.table.types.logical.UserDefinedType
Logical type of a user-defined object structured type. Structured types contain zero, one or more attributes. Each attribute has a name, a type, and an optional description. A type cannot be defined in such a way that one of its attribute types (transitively) refers to itself.

Compared to RowType, which may also be considered a "struct-like" type, structured types are distinguishable even if they contain the same set of fields. For example, "Visit(amount DOUBLE)" is distinct from "Interaction(amount DOUBLE)" due its identifier.

There are two kinds of structured types:

Catalog Structured Types

This type is currently not fully supported in the planner and is future work.

Types that are stored in a catalog and are identified by an ObjectIdentifier. Some logical properties that align with the SQL standard have been prepared already but are currently not used by the planner:

  • super type and single inheritance for more complex type hierarchies, similar to JVM-based languages.
  • final for preventing further inheritance (default behavior) or not final for allowing subtypes.
  • not instantiable if a more specific type is required or instantiable if instances can be created from this type (default behavior).
  • comparison properties of either none (no equality), equals (only equality and inequality), or full (greater, equals, less).

NOTE: Compared to the SQL standard, this class is incomplete. We might add new features such as method declarations in the future. Also ordering is not supported yet.

The serialized string representation is `cat`.`db`.`t` where cat is the catalog name, db is the database name, and t the user-defined type name.

Inline Structured Types

Types that are unregistered (i.e. declared inline) and are identified by a class name.

The class name does not have to be resolvable in the classpath. It can be used purely to distinguish between two objects containing the same set of attributes. However, in Table API and UDF calls an attempt is being made to resolve the class name to an implementation class. If that fails, Row is used as the getDefaultConversion().

The serialized string representation is STRUCTURED<'c', n0 t0 'd0', n1 t1 'd1', ...> where c is the class name, n is the unique name of a field, t is the logical type of a field, d is the optional description of a field.

Implementation Class

A structured type can be defined fully logically. The implementation class is optional and only used at the edges of the table ecosystem (e.g. when bridging to a function or collecting results). Serialization and equality (hashCode/equals) are handled by the runtime based on the logical type. In other words: hashCode/equals of an implementation class are not used. Custom equality, casting logic, and further overloaded operators will be supported once we allow defining methods on structured types.

An implementation class must offer a default constructor with zero arguments or a full constructor that assigns all attributes. Other physical properties such as the conversion classes of attributes are defined by a DataType when a structured type is used.

See Also:

  • Field Details

  • Method Details

    • newBuilder

      public static StructuredType.Builder newBuilder(ObjectIdentifier objectIdentifier)
      Creates a builder for a StructuredType that is identified by an ObjectIdentifier.

    • newBuilder

      public static StructuredType.Builder newBuilder(ObjectIdentifier objectIdentifier, Class<?> implementationClass)
      Creates a builder for a StructuredType that identified by an ObjectIdentifier but with a resolved implementation class.

    • newBuilder

      public static StructuredType.Builder newBuilder(Class<?> implementationClass)
      Creates a builder for a StructuredType that is identified by a class name derived from the given implementation class.

    • newBuilder

      public static StructuredType.Builder newBuilder(String className)
      Creates a builder for a StructuredType that is identified by a class name but without a resolved implementation class (i.e. eventually using FALLBACK_CONVERSION).

    • getAttributes

      public List<StructuredType.StructuredAttribute> getAttributes()

    • isInstantiable

      public boolean isInstantiable()

    • getComparison

      public StructuredType.StructuredComparison getComparison()

    • getSuperType

      public Optional<StructuredType> getSuperType()

    • getClassName

      public Optional<String> getClassName()

    • getImplementationClass

      public Optional<Class<?>> getImplementationClass()

    • copy

      public LogicalType copy(boolean isNullable)
      Description copied from class: LogicalType
      Returns a deep copy of this type with possibly different nullability.
      Specified by:
      copy in class LogicalType
      Parameters:
      isNullable - the intended nullability of the copied type
      Returns:
      a deep copy

    • asSummaryString

      public String asSummaryString()
      Description copied from class: LogicalType
      Returns a string that summarizes this type for printing to a console. An implementation might shorten long names or skips very specific properties.

      Use LogicalType.asSerializableString() for a type string that fully serializes this instance.

      Overrides:
      asSummaryString in class LogicalType
      Returns:
      summary string of this type for debugging purposes

    • asSerializableString

      public String asSerializableString()
      Description copied from class: LogicalType
      Returns a string that fully serializes this instance. The serialized string can be used for transmitting or persisting a type.

      See LogicalTypeParser for the reverse operation.

      Specified by:
      asSerializableString in class LogicalType
      Returns:
      detailed string for transmission or persistence

    • supportsInputConversion

      public boolean supportsInputConversion(Class<?> clazz)
      Description copied from class: LogicalType
      Returns whether an instance of the given class can be represented as a value of this logical type when entering the table ecosystem. This method helps for the interoperability between JVM-based languages and the relational type system.

      A supported conversion directly maps an input class to a logical type without loss of precision or type widening.

      For example, java.lang.Long or long can be used as input for BIGINT independent of the set nullability.

      Specified by:
      supportsInputConversion in class LogicalType
      Parameters:
      clazz - input class to be converted into this logical type
      Returns:
      flag that indicates if instances of this class can be used as input into the table ecosystem
      See Also:

    • supportsOutputConversion

      public boolean supportsOutputConversion(Class<?> clazz)
      Description copied from class: LogicalType
      Returns whether a value of this logical type can be represented as an instance of the given class when leaving the table ecosystem. This method helps for the interoperability between JVM-based languages and the relational type system.

      A supported conversion directly maps a logical type to an output class without loss of precision or type widening.

      For example, java.lang.Long or long can be used as output for BIGINT if the type is not nullable. If the type is nullable, only java.lang.Long can represent this.

      Specified by:
      supportsOutputConversion in class LogicalType
      Parameters:
      clazz - output class to be converted from this logical type
      Returns:
      flag that indicates if instances of this class can be used as output from the table ecosystem
      See Also:

    • getDefaultConversion

      public Class<?> getDefaultConversion()
      Description copied from class: LogicalType
      Returns the default conversion class. A value of this logical type is expected to be an instance of the given class when entering or is represented as an instance of the given class when leaving the table ecosystem if no other conversion has been specified.

      For example, java.lang.Long is the default input and output for BIGINT.

      Specified by:
      getDefaultConversion in class LogicalType
      Returns:
      default class to represent values of this logical type
      See Also:

    • getChildren

      public List<LogicalType> getChildren()
      Specified by:
      getChildren in class LogicalType

    • accept

      public <R> R accept(org.apache.flink.table.types.logical.LogicalTypeVisitor<R> visitor)
      Specified by:
      accept in class LogicalType

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class org.apache.flink.table.types.logical.UserDefinedType

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class org.apache.flink.table.types.logical.UserDefinedType

    • resolveClass

      public static Optional<Class<?>> resolveClass(ClassLoader classLoader, String className)
      Restores an implementation class from the class name component of a serialized string representation.

      Note: This method does not perform any kind of validation. The logical type system should not be destabilized by incorrectly implemented classes. This is also why classes won't get initialized. At this stage, only the class existence (i.e. metadata) in classloader matters.