PyFlink Table 数据类型(Data Types)完全指南:从逻辑类型到物理表示

  • 大数据
  • 流处理
  • 批处理
  • 数据工程

【免费下载链接】flink

项目地址: https://gitcode.com/gh_mirrors/fli/flink
点击查看 免费下载

本指南基于 Flink 仓库中 PyFlink Table API 的官方数据类型文档(flink-python/docs/reference/pyflink.table/data_types.rst),系统讲解 pyflink.table.types 模块中 DataTypes 的完整类型体系。你将掌握如何为 Table 与 SQL 作业声明输入/输出类型、如何组合复杂嵌套类型(ROW/MAP/ARRAY)、如何控制可空性,以及类型转换(to_sql_type/from_sql_type)背后的底层实现原理,可直接用于编写 PyFlink 作业、注册 UDF 与定义 Schema。

DataType 的两大职责:逻辑类型与物理提示

在 Table 生态系统中,DataType 描述的是"一个值的数据类型"。根据文档定义,它承担两项职责:

  1. 声明逻辑类型(logical type):逻辑类型独立于任何物理表示,与 SQL 标准的"数据类型"术语保持一致。它是强制的,定义了值在语义层面的类型——例如"这是一个 VARCHAR 字符串"。
  2. 给出物理表示提示(physical hints):提示是可选的,告诉优化器数据在物理层面应该如何表示。在 Table 生态系统的边界(如与 DataStream API、外部连接器交互的位置)上,物理提示是必需的,因为它指出了实现方期望的数据格式。

从源码实现看,这一设计落在 flink-python/pyflink/table/types.py 的 DataType 基类中:每个类型实例都携带 nullable 标志(是否允许为 None),并且可以通过 bridged_to() 方法附加转换类提示:

class DataType(object):
    def __init__(self, nullable=True):
        self._nullable = nullable
        self._conversion_cls = ''

    def bridged_to(self, conversion_cls) -> 'DataType':
        """
        Adds a hint that data should be represented using the given class when entering
        or leaving the table ecosystem.
        """
        self._conversion_cls = conversion_cls
        return self

DataType 还基于 __dict__ 实现了值相等比较(__eq__/__hash__),这意味着两个字段相同、可空性相同的类型实例是相等的,这在测试断言和类型合并中非常有用。

基础原子类型:字符串、二进制、布尔与数值

AtomicType 是所有非数组/行/映射类型的基类,其下细分为 NumericType(数值)、IntegralType(整型)、FractionalType(浮点/小数)等层级(见 types.py 类结构)。DataTypes 是这些类型的静态工厂,所有方法都返回对应的类型实例。

字符与二进制字符串

方法签名说明取值范围
DataTypes.CHAR(length, nullable=True)定长字符串 CHAR(n)length 取值 1 ~ 2147483647(0x7fffffff)
DataTypes.VARCHAR(length, nullable=True)变长字符串 VARCHAR(n)length 为最大长度,取值同上;当前 length 必须为 0x7fffffff
DataTypes.STRING(nullable=True)VARCHAR(2147483647) 的快捷方式无需传 length
DataTypes.BINARY(length, nullable=True)定长二进制 BINARY(n)(字节序列)length 取值 1 ~ 2147483647
DataTypes.VARBINARY(length, nullable=True)变长二进制 VARBINARY(n)length 为最大字节数,取值同上
DataTypes.BYTES(nullable=True)VARBINARY(2147483647) 的快捷方式无需传 length

对应实现可见 CharType/VarCharType/BinaryType/VarBinaryType。例如:

from pyflink.table.types import DataTypes

s1 = DataTypes.CHAR(10)          # char(10),定长
s2 = DataTypes.VARCHAR(100)      # varchar(100),变长
s3 = DataTypes.STRING()          # varchar(2147483647),等价于 DataTypes.VARCHAR(0x7fffffff)
b1 = DataTypes.BINARY(4)         # binary(4),4 字节定长
b2 = DataTypes.BYTES()           # varbinary(2147483647)

布尔与数值类型

方法签名SQL 语义取值范围 / 说明
DataTypes.BOOLEAN(nullable=True)BOOLEAN三值逻辑 TRUE / FALSE / UNKNOWN
DataTypes.TINYINT(nullable=True)TINYINT1 字节有符号整数,-128 ~ 127
DataTypes.SMALLINT(nullable=True)SMALLINT2 字节有符号整数,-32,768 ~ 32,767
DataTypes.INT(nullable=True)INT32 位有符号整数,-2,147,483,648 ~ 2,147,483,647
DataTypes.BIGINT(nullable=True)BIGINT8 字节有符号整数,约 ±9.2×10¹⁸
DataTypes.FLOAT(nullable=True)FLOAT4 字节单精度浮点数
DataTypes.DOUBLE(nullable=True)DOUBLE8 字节双精度浮点数
DataTypes.DECIMAL(precision, scale, nullable=True)DECIMAL(p, s)precision 取值 1 ~ 38;scale 取值 0 ~ precision

DECIMAL 是最需要关注的数值类型:它必须拥有固定的精度(数字总位数)与刻度(小数点右侧位数)。例如 (5, 2) 可表示 [-999.99, 999.99]。源码实现(DecimalType)中还做了参数断言:

assert 1 <= precision <= 38
assert 0 <= scale <= precision

其默认构造参数为 (10, 0);当从 Python 的 decimal.Decimal 对象推断 Schema 时,会得到 DecimalType(38, 18)。该类型面向金额、精度敏感统计等场景,可避免 FLOAT/DOUBLE 的浮点误差。

时间类型:DATE、TIME 与 TIMESTAMP

方法签名语义与取值范围
DataTypes.DATE(nullable=True)年-月-日,范围 0000-01-01 ~ 9999-12-31(相比 SQL 标准起点为公元 0 年)
DataTypes.TIME(precision=0, nullable=True)无时区时间,hour:minute:second[.fractional],范围 00:00:00.000000000 ~ 23:59:59.999999999;precision 取值 0 ~ 9
DataTypes.TIMESTAMP(precision=6, nullable=True)无时区时间戳,范围 0000-01-01 00:00:00.000000000 ~ 9999-12-31 23:59:59.999999999;precision 取值 0 ~ 9,默认 6
DataTypes.TIMESTAMP_WITH_LOCAL_TIME_ZONE(precision=6, nullable=True)带本地时区的时间戳;内部以 long 存储纳秒精度时间字段及 UTC 偏移
DataTypes.TIMESTAMP_LTZ(precision=6, nullable=True)前者的别名快捷方式
d = DataTypes.DATE()               # date
t = DataTypes.TIME(3)              # time(3)
ts = DataTypes.TIMESTAMP(3)        # timestamp(3)
ts_ltz = DataTypes.TIMESTAMP_LTZ(3)  # timestamp(3) with local time zone

时间类型有两个值得注意的点:

  • 与 SQL 标准相比,Flink 的时间类型不支持闰秒(23:59:60 与 23:59:61);
  • TIMESTAMP 描述的是"挂钟上的本地时间"(如生日),不存储也不表示时区,因此无法在缺少偏移或时区信息的情况下代表时间轴上的某个瞬间;而 TIMESTAMP_WITH_LOCAL_TIME_ZONE 将值内部存储为 long,记录所有日期时间字段(纳秒精度)以及相对 UTC/Greenwich 的偏移,适合跨时区的事件时间处理场景。

需要说明的是,当前仓库实现中若干时间类型存在精度限制标注(如 TIME 目前精度必须为 0、TIMESTAMP 目前精度必须为 3 等),实际使用时请以所依赖 Flink 版本的具体校验为准。

复杂类型:ARRAY、MAP、MULTISET 与 ROW

复杂类型用于描述结构化数据,是嵌套 Schema 的核心构建块。

ARRAY

DataTypes.ARRAY(element_type, nullable=True) 描述"具有相同子类型元素的数组"。相比 SQL 标准,数组的最大基数无法指定,固定为 2147483647;任意合法类型均可作为子类型:

arr = DataTypes.ARRAY(DataTypes.STRING())   # 字符串数组
arr2 = DataTypes.ARRAY(DataTypes.DOUBLE(False))  # 不可空 double 数组

MAP 与 MULTISET

  • DataTypes.MAP(key_type, value_type, nullable=True):键值映射。不允许重复键,每个键最多映射一个值;对键类型没有限制,但保证唯一性是用户的责任。MAP 是 SQL 标准的扩展。
  • DataTypes.MULTISET(element_type, nullable=True):多重集(bag)。与集合不同,它允许同一元素出现多次,每个唯一值映射到某个多重度(multiplicity)。
m = DataTypes.MAP(DataTypes.STRING(), DataTypes.BIGINT())   # map<string, bigint>
ms = DataTypes.MULTISET(DataTypes.INT())                    # multiset<int>

ROW 与 FIELD

DataTypes.ROW(row_fields, nullable=True) 描述字段序列,每个字段由字段名、字段类型和可选描述构成。表的一行正是行类型,行中每一列对应行类型中序号相同的字段。相比 SQL 标准,可选的字段描述简化了复杂结构的处理。

字段通过 DataTypes.FIELD(name, data_type, description=None) 创建。实际使用中,RowType 还支持链式 .add() 方式逐个添加字段——这在仓库测试 test_types.py 中有大量验证:

from pyflink.table.types import DataTypes

# 方式一:传入 FIELD 列表
row = DataTypes.ROW([
    DataTypes.FIELD("id", DataTypes.BIGINT()),
    DataTypes.FIELD("name", DataTypes.STRING(nullable=True)),
])

# 方式二:链式 add(测试中同样被支持)
row2 = (DataTypes.ROW()
        .add("f1", DataTypes.STRING(nullable=True))
        .add("f2", DataTypes.STRING(nullable=True)))

# 字段可携带描述
row3 = DataTypes.ROW([DataTypes.FIELD("f1", DataTypes.STRING(nullable=True),
                                      "a description")])

RowType 还提供字段访问与切片能力(row.fields、row[0:1] 等),见 RowType 实现。嵌套使用即可描述任意复杂的结构化数据:

schema = DataTypes.ROW([
    DataTypes.FIELD("user", DataTypes.ROW([
        DataTypes.FIELD("name", DataTypes.STRING()),
        DataTypes.FIELD("age", DataTypes.INT()),
    ])),
    DataTypes.FIELD("tags", DataTypes.ARRAY(DataTypes.STRING())),
])

特殊类型:NULL、LIST_VIEW、MAP_VIEW 与 INTERVAL

NULL

DataTypes.NULL() 表示"无类型的 null 值"类型。NULL 类型除 null(None)外没有其他值,因此可以转换为任何可空类型。它帮助表示 API 调用中使用 null 字面量时的未知类型,也可桥接到 JSON、Avro 等定义了该类型的格式。NULL 类型是 SQL 标准的扩展,且当前实现中 NullType 尚未完全支持。

LIST_VIEW 与 MAP_VIEW

  • DataTypes.LIST_VIEW(element_type):ListView 的数据类型,只能用于聚合函数(Aggregate Function)的 accumulator 类型声明。
  • DataTypes.MAP_VIEW(key_type, value_type):MapView 的数据类型,同样仅限聚合函数 accumulator 声明使用。
# 在 UDAF 的 accumulator 中使用
from pyflink.table.types import DataTypes

accumulator_type = DataTypes.ROW([
    DataTypes.FIELD("seen", DataTypes.LIST_VIEW(DataTypes.STRING())),
    DataTypes.FIELD("total", DataTypes.BIGINT()),
])

INTERVAL 与时间分辨率

INTERVAL 描述时间间隔,有两种类型:day-time 间隔(最高纳秒粒度)与 year-month 间隔(最高月粒度)。其"分辨率"由 SECOND、MINUTE、HOUR、DAY、MONTH、YEAR 这六个辅助方法构造:

方法参数说明
DataTypes.SECOND(precision=6)0 ~ 9秒及(可能的小数秒)分辨率
DataTypes.MINUTE()—分钟分辨率
DataTypes.HOUR()—小时分辨率
DataTypes.DAY(precision=2)1 ~ 6天分辨率(默认 2 位)
DataTypes.MONTH()—月分辨率
DataTypes.YEAR(precision=2)1 ~ 4年分辨率(默认 2 位)

用法:

from pyflink.table.types import DataTypes

# day-time 间隔:INTERVAL(DAY(2), SECOND(9))
interval_dt = DataTypes.INTERVAL(DataTypes.DAY(2), DataTypes.SECOND(9))

# year-month 间隔:INTERVAL(YEAR(4), MONTH())
interval_ym = DataTypes.INTERVAL(DataTypes.YEAR(4), DataTypes.MONTH())

间隔值在不同分辨率下的表示方式统一:例如"70 秒"总是以 day-to-second 格式(默认精度)表示为 +00 00:01:10.000000;"50 个月"总是以 year-to-month 格式表示为 +04-02。day-time 间隔取值范围为 -999999 23:59:59.999999999 ~ +999999 23:59:59.999999999,year-month 间隔取值范围为 -9999-11 ~ +9999-11。当前实现中 INTERVAL 的参数化存在限制(year-month 的上分辨率必须为 MONTH、day-time 的上分辨率必须为 SECOND,且不支持下分辨率),详见 INTERVAL 实现。

可空性控制与类型方法

每个 DataType 实例都通过 nullable 参数声明"该类型是否允许为 null(None)"。DataTypes 工厂方法统一接受 nullable: bool = True 参数。此外,DataType 基类还提供了一组常用方法(types.py L79-L120):

  • not_null():返回该类型的副本,并设置 nullable=False;
  • nullable():返回副本,设置 nullable=True;
  • type_name():返回类型的 SQL 风格名称(如 INT、VARCHAR);
  • bridged_to(conversion_cls):附加物理表示提示(见第一节);
  • need_conversion():该类型是否需要在 Python 对象与内部 SQL 对象之间转换,用于避免对 Array/Multiset/Map/Row 类型做不必要转换;
  • to_sql_type(obj) / from_sql_type(obj):Python 对象与内部 SQL 对象之间的双向转换入口。

典型用法——声明一个所有字段均不可空的 Schema:

from pyflink.table.types import DataTypes

schema = DataTypes.ROW([
    DataTypes.FIELD("id", DataTypes.BIGINT().not_null()),
    DataTypes.FIELD("name", DataTypes.STRING().not_null()),
    DataTypes.FIELD("score", DataTypes.DECIMAL(10, 2, nullable=False)),
])

从源码看类型体系的实现细节

pyflink.table.types 模块(共约 2800 行)中,所有类型类形成一个清晰的继承树,便于读者按需扩展自定义类型:

DataType
├── AtomicType(非数组/行/映射的原子类型)
│   ├── NullType
│   ├── NumericType
│   │   ├── IntegralType → TinyIntType / SmallIntType / IntType / BigIntType
│   │   └── FractionalType → FloatType / DoubleType / DecimalType
│   ├── CharType / VarCharType / BinaryType / VarBinaryType / BooleanType
│   ├── DateType / TimeType / TimestampType / LocalZonedTimestampType / ZonedTimestampType
│   └── YearMonthIntervalType / DayTimeIntervalType
└── ArrayType / ListViewType / MapType / MapViewType / MultisetType / RowType / RawType / UserDefinedType
  • 类型推断与合并:模块内部提供 _infer_type(从 Python 对象推断类型)与 _merge_type(合并类型)逻辑,仓库测试 test_types.py 验证了整数对象会被推断为 BIGINT(包括 2³¹、2⁷¹ 等大数),且 BIGINT 与 NULL 合并仍为 BIGINT;
  • Row 构建的健壮性:测试还验证了 ROW().add() 在只传名字不传类型时会抛出 ValueError(test_types.py L293),并对 RowType 的相等性、切片等行为做了覆盖;
  • 跨 API 桥接:DataTypes 在 table_schema.py、sources.py、sinks.py、udf.py 中被广泛引用,用于声明 Source/Sink 的 Schema 与 UDF 的入参出参类型——这正是文档所说"物理提示在 Table 生态边界处必需"的落地场景。

实战:构建一张带类型的表

将上述类型组合起来,即可完整定义一个 PyFlink Table 的 Schema 并创建虚拟表:

from pyflink.table import EnvironmentSettings, TableEnvironment
from pyflink.table.types import DataTypes

env_settings = EnvironmentSettings.in_streaming_mode()
t_env = TableEnvironment.create(env_settings)

schema = DataTypes.ROW([
    DataTypes.FIELD("order_id", DataTypes.BIGINT().not_null()),
    DataTypes.FIELD("user_name", DataTypes.STRING()),
    DataTypes.FIELD("amount", DataTypes.DECIMAL(10, 2)),
    DataTypes.FIELD("items", DataTypes.ARRAY(DataTypes.STRING())),
    DataTypes.FIELD("attrs", DataTypes.MAP(DataTypes.STRING(), DataTypes.STRING())),
    DataTypes.FIELD("order_time", DataTypes.TIMESTAMP_LTZ(3)),
])

# 将类型应用于虚拟表 DDL
t_env.execute_sql(
    "CREATE TEMPORARY TABLE orders ("
    "  order_id BIGINT NOT NULL,"
    "  user_name STRING,"
    "  amount DECIMAL(10, 2),"
    "  items ARRAY<STRING>,"
    "  attrs MAP<STRING, STRING>,"
    "  order_time TIMESTAMP_LTZ(3)"
    ") WITH ('connector' = 'datagen')"
)

# 在 Python API 中使用 DataTypes 构造的 Schema 进行查询与转换
t_env.from_elements([(1, 'alice', 10.5)], DataTypes.ROW([
    DataTypes.FIELD("id", DataTypes.BIGINT()),
    DataTypes.FIELD("name", DataTypes.STRING()),
    DataTypes.FIELD("score", DataTypes.DOUBLE()),
]))

可以看到:DataTypes 工厂方法对应 SQL DDL 中每个类型关键字(BIGINT、DECIMAL(10,2)、ARRAY<STRING> 等),而 nullable 参数对应 DDL 的 NULL/NOT NULL 约束,两者表达的是同一套类型系统——理解 pyflink.table.types 中的类型声明,也就掌握了 PyFlink Table/SQL API 的 Schema 定义语言。更多类型使用示例可继续查阅 table_schema.py 与 test_types.py 中的完整测试覆盖。

  • 大数据
  • 流处理
  • 批处理
  • 数据工程

【免费下载链接】flink

项目地址: https://gitcode.com/gh_mirrors/fli/flink
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值