PySpark合并列表字段报错：ValueError: Unexpected tuple '[' with StructType

错误原因 #

你遇到的ValueError: Unexpected tuple '[' with StructType，本质是UDF返回的数据格式和指定的ArrayType(StructType) schema不匹配。PySpark要求数组中的每个元素必须是与Struct结构兼容的字典或元组，但你的UDF返回值里嵌套了多余的列表（比如把每个元素用[]包裹），导致Spark无法解析成Struct类型。

示例场景 #

假设你的目标schema、输入数据如下：

from pyspark.sql.types import StructType, StructField, StringType, IntegerType, ArrayType

# 目标schema：数组元素为包含type和value的Struct
target_schema = ArrayType(StructType([
    StructField("type", StringType(), nullable=False),
    StructField("value", IntegerType(), nullable=False)
]))

# 示例输入DataFrame
sample_data = [
    ([{"type": "ft1", "value": 10}, {"type": "ft2", "value": 20}], [{"type": "rt1", "value": 30}]),
    ([{"type": "ft3", "value": 40}], [{"type": "rt2", "value": 50}, {"type": "rt3", "value": 60}])
]
df = spark.createDataFrame(sample_data, ["FT", "RT"])

错误的UDF示例（导致报错） #

如果你的函数不小心给每个元素套了额外的列表，就会触发错误：

def get_list_ft_rt(ft_list, rt_list):
    combined = []
    # 错误：每个元素被额外包裹了一层列表
    for item in ft_list:
        combined.append([item])
    for item in rt_list:
        combined.append([item])
    return combined

from pyspark.sql.functions import udf
merge_udf = udf(get_list_ft_rt, target_schema)

# 执行后抛出PythonException
df.withColumn("combined", merge_udf("FT", "RT")).show()

解决方案 #

方案1：修正UDF返回格式 #

确保UDF返回的数组中，每个元素是直接的字典（键名与StructField完全匹配）或元组（顺序与StructField定义一致），不要嵌套多余结构：

def get_list_ft_rt(ft_list, rt_list):
    combined = []
    # 直接扩展FT和RT的元素，无需额外嵌套
    combined.extend(ft_list)
    combined.extend(rt_list)
    return combined

# 重新注册UDF
merge_udf = udf(get_list_ft_rt, target_schema)

# 验证结果
df.withColumn("combined", merge_udf("FT", "RT")).show(truncate=False)

方案2：用PySpark内置函数替代UDF（更高效） #

如果FT和RT的元素结构已经与目标StructType一致，直接用内置的concat函数合并数组，无需编写UDF，性能更优：

from pyspark.sql.functions import concat

df.withColumn("combined", concat("FT", "RT")).show(truncate=False)

排查要点 #

• 检查UDF返回的每个元素：禁止嵌套列表，必须是单个字典/元组
• 核对字典键名：必须与StructType中的字段名完全一致（大小写敏感）
• 若用元组返回，顺序必须严格匹配StructField的定义顺序

内容的提问来源于stack exchange，提问作者Jaya Prakash