【免费下载链接】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 描述的是"一个值的数据类型"。根据文档定义,它承担两项职责:
- 声明逻辑类型(logical type):逻辑类型独立于任何物理表示,与 SQL 标准的"数据类型"术语保持一致。它是强制的,定义了值在语义层面的类型——例如"这是一个 VARCHAR 字符串"。
- 给出物理表示提示(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) | TINYINT | 1 字节有符号整数,-128 ~ 127 |
DataTypes.SMALLINT(nullable=True) | SMALLINT | 2 字节有符号整数,-32,768 ~ 32,767 |
DataTypes.INT(nullable=True) | INT | 32 位有符号整数,-2,147,483,648 ~ 2,147,483,647 |
DataTypes.BIGINT(nullable=True) | BIGINT | 8 字节有符号整数,约 ±9.2×10¹⁸ |
DataTypes.FLOAT(nullable=True) | FLOAT | 4 字节单精度浮点数 |
DataTypes.DOUBLE(nullable=True) | DOUBLE | 8 字节双精度浮点数 |
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
创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考



