Apache Beam Python FlatMap 变换实战指南:从 1 对 1 映射到 1 对多扁平化

原创2026-10-11 20:49:101,664 阅读
文章标签:批处理流处理大数据

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

从这里可以看到三个关键实现事实:

  1. FlatMap 是 ParDo 的特化封装:它内部构造了一个 ParDo(CallableWrapperDoFn(fn), ...),借助 ParDo 的分布式执行框架逐元素调用用户函数;
  2. fn 默认值是 identity(即 def identity(x): return x),所以不传函数时,输入元素本身必须是 iterable,FlatMap 直接将其扁平化;
  3. 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 的元素摊平输出。

源码见 flatmap_nofunction.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()
      | 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 中"一对多展开 + 扁平化"的核心工具,掌握要点如下:

  1. 映射函数必须返回 iterable,其元素即输出 PCollection 的元素;返回空 iterable 等价于过滤。
  2. 不传函数时使用 identity,专门用于把 PCollection 的 iterable 元素扁平化。
  3. 函数可以是内建函数、命名函数、lambda、生成器,也可以用 FlatMapTuple 解包 (key, value) 元组。
  4. 额外参数通过 *args/**kwargs 透传;跨 PCollection 的动态数据用 Side Input(Singleton / Iter / List / Dict)注入,并注意内存约束。
  5. 在底层,FlatMap 是 ParDo 加 CallableWrapperDoFn 的封装,Map 与 Filter 又分别基于 FlatMap 实现,理解这一脉络即可自如地在四个变换间切换。
登录后查看全文
beam