Pandas分类列分组聚合时值与索引长度不匹配的报错排查

场景复现 #

我们有一个包含4列的示例DataFrame：

import pandas as pd

df_test = pd.DataFrame({
    'date': ['2022-12-01', '2022-12-01', '2022-12-01', '2022-12-02', '2022-12-02', '2022-12-02'],
    'id': ['id1', 'id1', 'id2', 'id3', 'id4', 'id4'],
    'element': ['ip1', 'ip2', 'ip3', 'ip4', 'ip5', 'ip6'],
    'related_id': ['rid1', 'rid2', 'rid3', 'rid4', 'rid5', 'rid6'],
})

需要完成以下操作：

• 按date和id两列分组
• 聚合操作：
  • 将element列聚合为列表
  • 统计related_id列的唯一值数量

针对示例数据，以下代码可正常运行并得到预期结果：

(df_test
.groupby(['date', 'id'], as_index=False)
.agg(elements=('element', pd.Series.to_list),
     distinct_related_ids=('related_id', 'nunique')))

但处理大DataFrame时，执行完全相同的代码会触发如下报错：

ValueError: Length of values (263128) does not match length of index (8156968)

报错堆栈信息：

File "/Users/fvitale/.pyenv/versions/adversary/lib/python3.10/site-packages/pandas/core/groupby/generic.py", line 950, in aggregate
    self._insert_inaxis_grouper_inplace(result)
  File "/Users/fvitale/.pyenv/versions/adversary/lib/python3.10/site-packages/pandas/core/groupby/generic.py", line 1485, in _insert_inaxis_grouper_inplace
    result.insert(0, name, lev)
  File "/Users/fvitale/.pyenv/versions/adversary/lib/python3.10/site-packages/pandas/core/frame.py", line 4821, in insert
    value = self._sanitize_column(value)
  File "/Users/fvitale/.pyenv/versions/adversary/lib/python3.10/site-packages/pandas/core/frame.py", line 4915, in _sanitize_column
    com.require_length_match(value, self.index)
  File "/Users/fvitale/.pyenv/versions/adversary/lib/python3.10/site-packages/pandas/core/common.py", line 571, in require_length_match
    raise ValueError(
ValueError: Length of values (263128) does not match length of index (8156968)

排查发现的关键信息 #

• 拆分大DataFrame为单日数据后，操作可正常运行，仅多日数据会触发报错
• 仅用nunique聚合或单日分组仍会出现相同报错
• 1000万行的合成测试数据未触发错误
• 仅2行且包含分类列的DataFrame可复现该报错
• 截至2023年3月，这是Pandas的未解决bug

原因分析 #

该报错是Pandas分组聚合模块的已知bug，核心触发条件是：

1. 分组键（如date或id）为分类（Categorical）数据类型
2. 分组键包含多个不同的分组值（如多日期）
3. 使用as_index=False参数执行聚合

当满足以上条件时，Pandas在聚合后将分组键插入结果DataFrame时，会错误地使用原始DataFrame的索引长度，而非聚合后的分组数量，导致长度不匹配。

调试与解决方法 #

方法1：将分类列转换为字符串类型 #

提前将分组用的分类列转为普通字符串，避免触发分类类型相关的bug：

# 转换分类列为字符串
df_large['date'] = df_large['date'].astype(str)
df_large['id'] = df_large['id'].astype(str)

# 执行原聚合逻辑
result = (df_large
.groupby(['date', 'id'], as_index=False)
.agg(elements=('element', pd.Series.to_list),
     distinct_related_ids=('related_id', 'nunique')))

方法2：不使用as_index=False，手动重置索引 #

绕过as_index=False的内部逻辑，先保留分组索引，再手动重置：

result = (df_large
.groupby(['date', 'id'])
.agg(elements=('element', pd.Series.to_list),
     distinct_related_ids=('related_id', 'nunique'))
.reset_index())

方法3：分批次处理后合并结果 #

利用单日数据可正常运行的特点，按date拆分后逐个处理，最后合并结果：

# 获取所有唯一日期
unique_dates = df_large['date'].unique()
result_list = []

# 逐个处理单日数据
for dt in unique_dates:
    daily_df = df_large[df_large['date'] == dt]
    daily_result = (daily_df
                   .groupby(['date', 'id'], as_index=False)
                   .agg(elements=('element', pd.Series.to_list),
                        distinct_related_ids=('related_id', 'nunique')))
    result_list.append(daily_result)

# 合并所有结果
final_result = pd.concat(result_list, ignore_index=True)

方法4：使用apply替代agg（注意性能） #

如果上述方法仍有问题，可尝试用apply实现聚合逻辑：

def group_agg_func(group):
    return pd.Series({
        'elements': group['element'].tolist(),
        'distinct_related_ids': group['related_id'].nunique()
    })

result = (df_large
.groupby(['date', 'id'], as_index=False)
.apply(group_agg_func))

内容的提问来源于stack exchange，提问作者Filippo Vitale