Apache Beam Python FlatMap 变换实战指南:从 1 对 1 映射到 1 对多扁平化
Apache Beam Python FlatMap 变换实战指南:从 1 对 1 映射到 1 对多扁平化
Apache Beam 的 FlatMap 是 Python SDK 中最常用的 elementwise(逐元素)变换之一,它把一个输入元素通过 1 对多映射函数展开成零个或多个输出元素,并把这些输出“扁平化”地汇入结果 PCollection。本文以官方文档 flatmap.md 为核心骨架,结合 apache_beam.transforms.core 的源码实现与仓库内 10 个可运行的示例,系统讲解 FlatMap 的 10 种典型用法,包括自定义函数、lambda、生成器、元组解包、多参数函数以及三种 Side Input 形态,帮助你在一线开发中准确选择映射变换。
FlatMap 是什么:1 对多映射的扁平化变换
FlatMap 对 PCollection 中的每一个元素应用一个简单的 1-to-many(一对多)映射函数,映射产生的"多个"结果元素会被**扁平化(flatten)**进最终的输出集合。官方文档对它的定义是:
Applies a simple 1-to-many mapping function over each element in the collection. The many elements are flattened into the resulting collection.
它的约束非常清晰:FlatMap 接受一个返回 iterable 的函数,该 iterable 中的每一个元素,都会成为结果 PCollection 中的一个元素。也就是说:
- 输入 1 个元素 → 函数返回 0 个、1 个或多个元素的 iterable;
- 每个 iterable 元素被"摊平"后独立进入输出
PCollection; - 因此
FlatMap天然支持过滤(返回空 iterable 即丢弃该元素)与展开(把一个元素拆成多个)两种能力。
在仓库源码 core.py 中,FlatMap 的函数签名与语义如下:
def FlatMap(fn=identity, *args, **kwargs):
"""FlatMap 类似于 ParDo,但通过一个 callable 来指定变换。
callable 必须为输入 PCollection 的每个元素返回一个 iterable,
这些 iterable 的元素会被扁平化进输出 PCollection。
如果不给 callable,则输入 PCollection 的所有元素本身必须是 iterable,
它们会被直接扁平化进输出 PCollection。
"""
label = 'FlatMap(%s)' % ptransform.label_from_callable(fn)
if not callable(fn):
raise TypeError(
'FlatMap can be used only with callable objects. '
'Received %r instead.' % (fn))
pardo = ParDo(CallableWrapperDoFn(fn), *args, **kwargs)
pardo.label = label
return pardo
从这里可以看到三个关键实现事实:
FlatMap是ParDo的特化封装:它内部构造了一个ParDo(CallableWrapperDoFn(fn), ...),借助ParDo的分布式执行框架逐元素调用用户函数;fn默认值是identity(即def identity(x): return x),所以不传函数时,输入元素本身必须是 iterable,FlatMap直接将其扁平化;fn必须可调用,否则抛出TypeError;典型的错误是把DoFn实例传给FlatMap(DoFn只能用于ParDo)。
底层执行:CallableWrapperDoFn
用户传入的普通函数会被包装进 CallableWrapperDoFn(定义于 core.py):
class CallableWrapperDoFn(DoFn):
def __init__(self, fn, fullargspec=None):
if not callable(fn):
raise TypeError('Expected a callable object instead of: %r' % fn)
self._fn = fn
if isinstance(fn, (types.BuiltinFunctionType,
types.MethodType, types.FunctionType)):
self.process = fn
else:
# 对于 set / list 这类可调用但非函数的情况
self.process = lambda element: fn(element)
super().__init__()
- 对普通函数、方法、内建函数,直接把
fn作为 DoFn 的process方法(process的返回值即该元素产生的 iterable); - 对
list、set等可调用对象,用lambda element: fn(element)包装; - 类型推导
default_type_hints会对函数返回值执行strip_iterable(),把外层容器类型剥掉——这正是"扁平化"语义在类型层面的体现:函数输出的是可迭代容器,而PCollection中的元素是容器内部的元素。
实战示例:10 种 FlatMap 用法
官方文档围绕一个"果蔬(produce)"数据集组织了 10 个示例:输入 PCollection 中每个元素包含图标、名称、生长时长等信息,通过不同方式调用 FlatMap,让每个输入元素产生零个或多个输出元素。仓库中这些示例的完整源码位于 sdks/python/apache_beam/examples/snippets/transforms/elementwise/ 目录下,均以 beam-playground 元信息标记,可直接在 Playground 中运行,也可本地执行验证。
示例 1:使用预定义函数 str.split
使用 Python 内建函数 str.split 作为映射函数:它接收单个 str 元素,按空白字符拆分并输出一个 str 列表。管道对每个输入字符串执行拆分,产生零个或多个元素。
源码见 flatmap_simple.py:
import apache_beam as beam
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
'🍓Strawberry 🥕Carrot 🍆Eggplant',
'🍅Tomato 🥔Potato',
])
| 'Split words' >> beam.FlatMap(str.split)
| beam.Map(print))
输出:
🍓Strawberry
🥕Carrot
🍆Eggplant
🍅Tomato
🥔Potato
示例 2:使用自定义函数
自定义函数 split_words 以 ',' 为分隔符拆分输入 str,返回 list。这是最常见的用法:把业务逻辑封装成命名函数,提升可读性和可测试性。
源码见 flatmap_function.py:
import apache_beam as beam
def split_words(text):
return text.split(',')
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
'🍓Strawberry,🥕Carrot,🍆Eggplant',
'🍅Tomato,🥔Potato',
])
| 'Split words' >> beam.FlatMap(split_words)
| beam.Map(print))
示例 3:不传函数(身份映射扁平化)
FlatMap 最常见的用途之一是把"PCollection 的 iterable"扁平化为"元素的 PCollection"。此时不指定函数参数,FlatMap 使用默认的 identity 映射函数(即源码中的 fn=identity),直接把每个输入 iterable 的元素摊平输出。
import apache_beam as beam
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create(
[['🍓Strawberry', '🥕Carrot', '🍆Eggplant'], ['🍅Tomato', '🥔Potato']])
| 'Split words' >> beam.FlatMap()
| beam.Map(print))
输出为 5 个独立的 str 元素(与示例 1、2 的结果相同)。注意:不传函数时,每个输入元素本身必须是 iterable,否则运行时无法扁平化。
示例 4:使用 lambda 函数
同样做"列表的扁平化",但改用 lambda:beam.FlatMap(lambda elements: elements)。lambda 直接返回收到的输入 iterable,语义与示例 3 完全等价,适合逻辑简单的场景。
源码见 flatmap_lambda.py:
import apache_beam as beam
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
['🍓Strawberry', '🥕Carrot', '🍆Eggplant'],
['🍅Tomato', '🥔Potato'],
])
| 'Flatten lists' >> beam.FlatMap(lambda elements: elements)
| beam.Map(print))
示例 5:使用生成器(generator)
映射函数也可以写成生成器:generate_elements 通过 yield 逐个产出元素。生成器每次 yield 的结果就是输出 PCollection 中的一个元素。这种写法特别适合需要对 iterable 做额外处理(如过滤、转换)后再逐个产出的场景,且天然具有惰性求值、内存友好的特点。
源码见 flatmap_generator.py:
import apache_beam as beam
def generate_elements(elements):
for element in elements:
yield element
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
['🍓Strawberry', '🥕Carrot', '🍆Eggplant'],
['🍅Tomato', '🥔Potato'],
])
| 'Flatten lists' >> beam.FlatMap(generate_elements)
| beam.Map(print))
示例 6:FlatMapTuple 处理键值对
如果 PCollection 中的元素是 (key, value) 元组,可以用 FlatMapTuple 把元组解包为多个函数参数。它的定义位于 core.py:
beam.FlatMapTuple(lambda a, b, ...: ...)
# 等价于
beam.FlatMap(lambda element, ...: fn(*element, ...))
源码见 flatmap_tuple.py:
import apache_beam as beam
def format_plant(icon, plant):
if icon:
yield '{}{}'.format(icon, plant)
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
('🍓', 'Strawberry'),
('🥕', 'Carrot'),
('🍆', 'Eggplant'),
('🍅', 'Tomato'),
('🥔', 'Potato'),
(None, 'Invalid'),
])
| 'Format' >> beam.FlatMapTuple(format_plant)
| beam.Map(print))
这里 format_plant 的两个参数 icon、plant 分别对应元组的两个元素;当 icon 为 None 时生成器不产出任何元素,因此 ('None', 'Invalid') 这一条会被静默过滤掉——再次体现"返回空 iterable 即丢弃"的过滤语义。注意 FlatMapTuple 要求 Side Input 必须有默认值,否则会抛出 TypeError: Side inputs must have defaults for FlatMapTuple.(见 core.py)。
示例 7:多参数函数
FlatMap 支持接收多参数的函数,额外的参数以位置参数或关键字参数的形式传给映射函数。split_words 同时接收 text 与 delimiter 两个参数。
源码见 flatmap_multiple_arguments.py:
import apache_beam as beam
def split_words(text, delimiter=None):
return text.split(delimiter)
with beam.Pipeline() as pipeline:
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
'🍓Strawberry,🥕Carrot,🍆Eggplant',
'🍅Tomato,🥔Potato',
])
| 'Split words' >> beam.FlatMap(split_words, delimiter=',')
| beam.Map(print))
参数传递机制在源码中表现为:FlatMap(fn, *args, **kwargs) 会把 *args/**kwargs 原样透传给 ParDo,最终由 CallableWrapperDoFn 以这些额外参数调用 fn。delimiter 有默认值 None,因此该函数既可作为普通映射使用,也可通过关键字参数定制分隔符。
Side Input(侧输入)的三种形态
当映射逻辑需要额外数据(如另一条 PCollection 计算出的平均值、参考字典、合法取值集合)时,可以把这些数据作为 Side Input 传给 FlatMap。Beam 提供三种接入形态,各有适用场景。
示例 8:Singleton(单值)侧输入
如果侧输入 PCollection 只有一个值(例如另一次计算的均值),用 beam.pvalue.AsSingleton(pcollection) 把它作为单值传给函数。本例中用一个只含 ',' 的 PCollection 充当分隔符。
源码见 flatmap_side_inputs_singleton.py:
import apache_beam as beam
with beam.Pipeline() as pipeline:
delimiter = pipeline | 'Create delimiter' >> beam.Create([','])
plants = (
pipeline
| 'Gardening plants' >> beam.Create([
'🍓Strawberry,🥕Carrot,🍆Eggplant',
'🍅Tomato,🥔Potato',
])
| 'Split words' >> beam.FlatMap(
lambda text,
delimiter: text.split(delimiter),
delimiter=beam.pvalue.AsSingleton(delimiter),
)
| beam.Map(print))
注意:lambda 的 delimiter 参数在调用时由 Side Input 注入,与示例 7 中"直接把 ',' 写死在关键字参数里"不同——前者数据来自另一条 PCollection,可在运行时动态计算。
示例 9:Iterator(迭代器)侧输入
如果侧输入 PCollection 包含多个值,用 beam.pvalue.AsIter(pcollection) 以迭代器方式惰性访问元素:元素按需逐个取出,因此可以遍历大到放不进内存的 PCollection。本例用一个合法生长时长集合(annual、biennial、perennial)来校验并归一化植物的 duration 字段。
源码见 flatmap_side_inputs_iter.py:
import apache_beam as beam
def normalize_and_validate_durations(plant, valid_durations):
plant['duration'] = plant['duration'].lower()
if plant['duration'] in valid_durations:
yield plant
with beam.Pipeline() as pipeline:
valid_durations = pipeline | 'Valid durations' >> beam.Create([
'annual',
'biennial',
'perennial',
])
valid_plants = (
pipeline
| 'Gardening plants' >> beam.Create([
{'icon': '🍓', 'name': 'Strawberry', 'duration': 'Perennial'},
{'icon': '🥕', 'name': 'Carrot', 'duration': 'BIENNIAL'},
{'icon': '🍆', 'name': 'Eggplant', 'duration': 'perennial'},
{'icon': '🍅', 'name': 'Tomato', 'duration': 'annual'},
{'icon': '🥔', 'name': 'Potato', 'duration': 'unknown'},
])
| 'Normalize and validate durations' >> beam.FlatMap(
normalize_and_validate_durations,
valid_durations=beam.pvalue.AsIter(valid_durations),
)
| beam.Map(print))
输出中 Potato(duration='unknown')不在合法集合内,被过滤掉。官方文档特别提示:也可以使用 beam.pvalue.AsList(pcollection) 以 list 形式传入侧输入,但这要求所有元素都能放进内存;AsIter 则没有这个限制。
示例 10:Dictionary(字典)侧输入
如果侧输入 PCollection 足够小、能整体放进内存,可以用 beam.pvalue.AsDict(pcollection) 把它转成字典传入。每个元素必须是 (key, value) 对。本例把时长编码 0/1/2 映射为 annual/biennial/perennial,并替换合法植物的 duration。
源码见 flatmap_side_inputs_dict.py:
import apache_beam as beam
def replace_duration_if_valid(plant, durations):
if plant['duration'] in durations:
plant['duration'] = durations[plant['duration']]
yield plant
with beam.Pipeline() as pipeline:
durations = pipeline | 'Durations dict' >> beam.Create([
(0, 'annual'),
(1, 'biennial'),
(2, 'perennial'),
])
valid_plants = (
pipeline
| 'Gardening plants' >> beam.Create([
{'icon': '🍓', 'name': 'Strawberry', 'duration': 2},
{'icon': '🥕', 'name': 'Carrot', 'duration': 1},
{'icon': '🍆', 'name': 'Eggplant', 'duration': 2},
{'icon': '🍅', 'name': 'Tomato', 'duration': 0},
{'icon': '🥔', 'name': 'Potato', 'duration': -1},
])
| 'Replace duration if valid' >> beam.FlatMap(
replace_duration_if_valid,
durations=beam.pvalue.AsDict(durations),
)
| beam.Map(print))
Potato 的 duration=-1 不在字典键中,被过滤。官方文档明确提醒:AsDict 要求 PCollection 所有元素都能放进内存;如果放不进内存,请改用 beam.pvalue.AsIter(pcollection)。
三种 Side Input 形态速查
| 形态 | API | 适用场景 | 内存要求 |
|---|---|---|---|
| Singleton | beam.pvalue.AsSingleton(pc) |
侧输入只有一个值(如均值、阈值) | 单值 |
| Iterator | beam.pvalue.AsIter(pc) |
侧输入有多个值,需要惰性遍历 | 无需全部驻留内存,可处理超大数据 |
| List | beam.pvalue.AsList(pc) |
侧输入有多个值且需重复随机访问 | 所有元素必须能放进内存 |
| Dict | beam.pvalue.AsDict(pc) |
侧输入是 (key, value) 对,需按键查找 |
所有元素必须能放进内存 |
与 Map、Filter、ParDo 的关系
官方文档在 "Related transforms" 一节给出了三个最相关的变换,可以帮你选型:
- Filter:如果函数只是决定"输出还是不输出某个元素",用
Filter更合适。事实上源码 core.py 的注释明确指出Filter就是FlatMap的一种特化——用 callable 过滤掉不满足条件的元素。 - Map:行为与
FlatMap相同,但每个输入恰好产生一个输出。从实现看,core.py 中Map内部正是FlatMap的封装:它把用户函数包成lambda x: [fn(x)](返回值始终是单元素列表),再交给FlatMap执行。 - ParDo:最通用的逐元素映射操作,支持多输出集合(
Tags)、DoFn生命周期方法、状态与定时器等高级能力;FlatMap本质上是"只输出一个主集合、使用普通 callable 的 ParDo"。
选型总结:只需要"一进一出"用 Map;需要"一进多出 / 零出"用 FlatMap;只做布尔过滤用 Filter;需要窗口、状态、多输出等复杂能力时升级到 ParDo。
测试验证:仓库内的配套用例
仓库为以上 10 个示例提供了完整的单元测试:flatmap_test.py 中 FlatMapTest 对每个示例函数逐一断言输出内容(check_plants / check_valid_plants),并使用 @mock.patch 将 print 替换为 str 以捕获打印结果:
def test_flatmap_simple(self):
flatmap_simple.flatmap_simple(check_plants)
def test_flatmap_nofunction(self):
flatmap_nofunction.flatmap_nofunction(check_plants)
def test_flatmap_tuple(self):
flatmap_tuple.flatmap_tuple(check_plants)
def test_flatmap_side_inputs_dict(self):
flatmap_side_inputs_dict.flatmap_side_inputs_dict(check_valid_plants)
此外,核心层测试 core_test.py 中的 FlatMapTest 直接验证 FlatMap 的行为语义(包括空 iterable 过滤、非 callable 抛 TypeError 等)。本地运行方式:
# 运行示例级测试
python -m apache_beam.examples.snippets.transforms.elementwise.flatmap_test
小结
FlatMap 是 Beam Python 中"一对多展开 + 扁平化"的核心工具,掌握要点如下:
- 映射函数必须返回 iterable,其元素即输出
PCollection的元素;返回空 iterable 等价于过滤。 - 不传函数时使用
identity,专门用于把PCollection的 iterable 元素扁平化。 - 函数可以是内建函数、命名函数、lambda、生成器,也可以用
FlatMapTuple解包(key, value)元组。 - 额外参数通过
*args/**kwargs透传;跨PCollection的动态数据用 Side Input(Singleton / Iter / List / Dict)注入,并注意内存约束。 - 在底层,
FlatMap是ParDo加CallableWrapperDoFn的封装,Map与Filter又分别基于FlatMap实现,理解这一脉络即可自如地在四个变换间切换。