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 UserDefinedType

Logical type of a user-defined object structured type. Structured types contain zero, one or more attributes. Each attribute consists of a name and a type. A type cannot be defined so that one of its attribute types (transitively) uses itself.

There are two kinds of structured types. Types that are stored in a catalog and are identified by an ObjectIdentifier or anonymously defined, unregistered types (usually reflectively extracted) that are identified by an implementation Class.

Logical properties

A structured type can declare a super type and allows single inheritance for more complex type hierarchies, similar to JVM-based languages.

A structured type can be declared final for preventing further inheritance (default behavior) or not final for allowing subtypes.

A structured type can be declared not instantiable if a more specific type is required or instantiable if instances can be created from this type (default behavior).

A structured type declares 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.

Physical properties

A structured type can be defined fully logically (e.g. by using a CREATE TYPE DDL). The implementation class is optional and only used at the edges of the table ecosystem (e.g. when bridging to a function or connector). 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:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	StructuredType.Builder A builder for a StructuredType.
static class	StructuredType.StructuredAttribute Defines an attribute of a StructuredType.
static class	StructuredType.StructuredComparison Defines equality properties for scalar evaluation.

Field Summary

Fields

Modifier and Type	Field and Description
static String	FORMAT

Method Summary

Modifier and Type	Method and Description
<R> R	accept(LogicalTypeVisitor<R> visitor)
String	asSummaryString() Returns a string that summarizes this type for printing to a console.
LogicalType	copy(boolean isNullable) Returns a deep copy of this type with possibly different nullability.
boolean	equals(Object o)
List<StructuredType.StructuredAttribute>	getAttributes()
List<LogicalType>	getChildren()
StructuredType.StructuredComparison	getComparison()
Class<?>	getDefaultConversion() Returns the default conversion class.
Optional<Class<?>>	getImplementationClass()
Optional<StructuredType>	getSuperType()
int	hashCode()
boolean	isInstantiable()
static StructuredType.Builder	newBuilder(Class<?> implementationClass) Creates a builder for a StructuredType that is not stored in a catalog and is identified by an implementation Class.
static StructuredType.Builder	newBuilder(ObjectIdentifier objectIdentifier) Creates a builder for a StructuredType that has been stored in a catalog and is identified by an ObjectIdentifier.
static StructuredType.Builder	newBuilder(ObjectIdentifier objectIdentifier, Class<?> implementationClass) Creates a builder for a StructuredType that has been stored in a catalog and is identified by an ObjectIdentifier.
boolean	supportsInputConversion(Class<?> clazz) Returns whether an instance of the given class can be represented as a value of this logical type when entering the table ecosystem.
boolean	supportsOutputConversion(Class<?> clazz) Returns whether a value of this logical type can be represented as an instance of the given class when leaving the table ecosystem.

Methods inherited from class org.apache.flink.table.types.logical.UserDefinedType

asSerializableString, getDescription, getObjectIdentifier, isFinal

Methods inherited from class org.apache.flink.table.types.logical.LogicalType

conversionSet, copy, getTypeRoot, is, is, isAnyOf, isAnyOf, isNullable, toString, withNullability

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FORMAT

public static final String FORMAT

See Also:

Constant Field Values

Method Detail

newBuilder

public static StructuredType.Builder newBuilder(ObjectIdentifier objectIdentifier)

Creates a builder for a StructuredType that has been stored in a catalog and is identified by an ObjectIdentifier.

newBuilder

public static StructuredType.Builder newBuilder(ObjectIdentifier objectIdentifier,
                                                Class<?> implementationClass)

Creates a builder for a StructuredType that has been stored in a catalog and is identified by an ObjectIdentifier. The optional implementation class defines supported conversions.

newBuilder

public static StructuredType.Builder newBuilder(Class<?> implementationClass)

Creates a builder for a StructuredType that is not stored in a catalog and is identified by an implementation Class.

getAttributes

public List<StructuredType.StructuredAttribute> getAttributes()

isInstantiable

public boolean isInstantiable()

getComparison

public StructuredType.StructuredComparison getComparison()

getSuperType

public Optional<StructuredType> getSuperType()

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

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:

LogicalType.getDefaultConversion()

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:

LogicalType.getDefaultConversion()

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:

LogicalType.supportsInputConversion(Class), LogicalType.supportsOutputConversion(Class)

getChildren

public List<LogicalType> getChildren()

Specified by:

getChildren in class LogicalType

accept

public <R> R accept(LogicalTypeVisitor<R> visitor)

Specified by:

accept in class LogicalType

equals

public boolean equals(Object o)

Overrides:

equals in class UserDefinedType

hashCode

public int hashCode()

Overrides:

hashCode in class UserDefinedType