如何创建带唯一索引/列的Pandas DataFrame，添加重复项报错？

好问题！其实Pandas本身并没有直接提供像MySQL那样给指定列设置唯一约束、自动报错的内置参数，但我们完全可以自己实现类似的效果，不用每次都写繁琐的if判断。下面给你两个实用的方案：

方案1：自定义前置检查函数（推荐） #

这个方法会在追加新行前，先检查指定列是否存在重复值，发现重复就直接抛出错误，逻辑清晰且高效。

import pandas as pd

def append_with_unique_check(df, new_row, unique_cols):
    # 把新行转成DataFrame，方便后续比较
    new_df = pd.DataFrame([new_row])
    
    # 检查指定列是否和原DataFrame存在完全匹配的行
    duplicate_rows = df[unique_cols].isin(new_df[unique_cols].iloc[0]).all(axis=1)
    if duplicate_rows.any():
        raise ValueError(f"新行在列{unique_cols}上存在重复值，请检查后重试！")
    
    # 没有重复就追加新行
    return pd.concat([df, new_df], ignore_index=True)

# 用法示例
df = pd.DataFrame({'id': [1, 2, 3], 'name': ['Alice', 'Bob', 'Charlie']})
new_row_valid = {'id': 4, 'name': 'David'}
df = append_with_unique_check(df, new_row_valid, unique_cols=['id'])  # 正常追加

new_row_duplicate = {'id': 2, 'name': 'Eve'}
# 这行会抛出ValueError，因为id=2已经存在
df = append_with_unique_check(df, new_row_duplicate, unique_cols=['id'])

如果需要检查多列组合的唯一性（比如id和name一起不能重复），只需要把unique_cols改成['id', 'name']即可，函数会自动检查这两列的组合是否重复。

方案2：利用临时索引实现验证 #

这个思路是把需要检查唯一性的列临时设置为DataFrame的索引，然后利用df.append()的verify_integrity=True参数（该参数会检查索引的唯一性），完成验证后再恢复原索引。

import pandas as pd

def append_with_unique_cols(df, new_row, unique_cols):
    # 临时将指定列设为索引
    temp_df = df.set_index(unique_cols)
    new_row_df = pd.DataFrame([new_row]).set_index(unique_cols)
    
    try:
        # 用verify_integrity检查索引（即我们要的唯一列）的唯一性
        temp_df = temp_df.append(new_row_df, verify_integrity=True)
    except ValueError as e:
        # 捕获错误并重新包装成更明确的提示
        raise ValueError(f"指定列{unique_cols}存在重复值：{str(e)}")
    
    # 恢复原来的索引结构
    return temp_df.reset_index()

# 用法示例
df = pd.DataFrame({'id': [1, 2, 3], 'name': ['Alice', 'Bob', 'Charlie']})
new_row_duplicate = {'id': 2, 'name': 'Eve'}
# 这行会抛出错误
df = append_with_unique_cols(df, new_row_duplicate, unique_cols=['id'])

补充说明 #

你之前提到的df.append(new_row, verify_integrity=True)其实是检查索引的唯一性，而非所有列的唯一性，这是一个常见的误区哦～如果想实现指定列的唯一约束，上面的两种方法都能满足需求。

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