Type.Union

Remarks

Type.Union computes the least upper bound of a list of types — the most specific type that is a supertype of all types in the list. In simpler terms, it returns the most general type to which all provided types are assignable.

Key behaviors:

- Type.Union({type number, type nullable number}) returns type nullable number — the nullable form is a supertype of the non-nullable form - Type.Union({type number, type text}) returns type any — since number and text share no common supertype more specific than any - Type.Union({type text, type text}) returns type text — identical types produce that type unchanged - Type.Union({}) with an empty list returns type none — the bottom type (a type with no inhabitants)

Type.Union is used in generic transformation functions that need to determine a compatible output type when merging values from multiple sources that may have different types. It is also useful in custom connector schema inference — when building a schema from heterogeneous fields, the union type gives the most specific annotation that fits all observed types.

Note that type any in the result means the engine found no shared structure. In practice, a result of type any means the column or value will not have useful type annotations and operations on it may be slower or require explicit type casts.