SQLAlchemy中的full-table-tuple是什么？该如何正确使用？

问题根源 #

之前尝试直接传入裸元组列表无法运行，是因为SQLAlchemy对full-table-tuple格式的多行数据识别有明确规则：单独把元组列表传给values()时，会被误解析为单一行的位置参数，而非多行数据集，自然无法正常执行。要正确使用元组格式的批量插入，必须在传入元组数据集的同时，显式指定每个元组元素对应的表列，完成列和值的映射绑定。

full-table-tuple 正确使用示例 #

构造可存入set的数据集 #

元组本身是可哈希类型，只要元组内的所有值都是可哈希的，就可以直接放入set自动去重，解决dict无法存入set的问题。存储的元组需要提前固定好元素顺序，和后续指定的列顺序严格对应：

from sqlalchemy.dialects.postgresql import insert as psql_insert

# 元组格式的行数据直接存入set，重复行会自动过滤
row_set = {
    (1, 2),
    (3, 4),
    (1, 2),
}

执行带UPSERT的批量插入 #

调用values()方法时，第一个参数传入可迭代的元组数据集，后续位置参数按元组元素的顺序依次传入对应的表列对象，SQLAlchemy就会正确识别为多行元组格式的插入数据，后续的冲突处理逻辑和原有字典列表写法完全兼容：

session.execute(
    psql_insert(SomeTable)
    .values(
        row_set,
        # 按元组元素的顺序，依次指定对应的表列
        SomeTable.c.column_1,
        SomeTable.c.column_2
    )
    .on_conflict_do_nothing()
)

注意事项 #

• values()方法中传入的列参数顺序，必须和元组内的元素顺序严格一一对应，否则会出现值写入错误列的问题；优先引用表模型的列对象定义顺序，不要硬编码字符串列名，避免匹配错误。
• 只有当所有待插入的列值都是可哈希类型（数字、字符串、日期类型等）时，才能组成可哈希的元组存入set；如果列值包含列表、字典这类不可哈希类型，无法使用set存储。
• 这种写法的执行性能、UPSERT行为和原有字典列表写法完全一致，不会有额外开销，也支持on_conflict_do_update等复杂的冲突处理逻辑。

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