SQLAlchemy原生SQL通过IN子句绑定集合参数仅返回单值的问题

• 数据库表结构如下：

Username    city        Type 
 Anna       Paris        abc 
 Marc       london       abc
 erica      rome         AF 
 Sara       Newyork      cbd 
 silvia      paris        AD

• 已定义待匹配的类型集合：

typelist = {'abc', 'cbd'}

• 预期查询结果为返回Type列匹配集合内任意值的全部记录：

Username    city        Type 
 Anna       Paris        abc 
 Marc       london       abc
 Sara       Newyork      cbd 

当前尝试的查询代码为：

sql = "SELECT * FROM table WHERE data IN :values" 
query = sqlalchemy.text(sql).bindparams(values=tuple(typelist))
conn.engine.execute(query)

执行后未返回全部匹配结果，仅得到单条记录：

Username    city        Type 
 Sara       Newyork      cbd 

• 核心问题是普通命名参数绑定无法适配IN子句的多值语法要求。你使用的:values是单值占位符，传入tuple类型的参数时，数据库驱动不会自动将集合拆分为多个独立的绑定值，只会把整个参数当成单个标量解析。这种单值解析的逻辑没有统一标准，不同驱动可能随机取tuple中的单个值做匹配，因此出现了只返回部分结果的异常。
• 代码中存在两处易引发问题的笔误：
  • WHERE子句中匹配的列名写为data，和实际表结构中的Type列不匹配
  • 表名table是SQL保留关键字，直接使用会触发语法错误，需要做转义或替换为合法表名

方案1：适配原生text()查询的IN多值绑定 #

使用SQLAlchemy内置的expanding参数绑定机制，专门处理IN子句的多值展开，SQLAlchemy会自动把传入的集合拆分为对应数量的独立占位符，避免SQL注入风险：

# 修正列名、表名笔误，Type列用反引号转义避免和类型关键字冲突
sql = "SELECT * FROM `user_table` WHERE `Type` IN :values" 
query = sqlalchemy.text(sql).bindparams(
    sqlalchemy.bindparam("values", expanding=True)
)
# 传入集合即可，SQLAlchemy会自动处理展开逻辑
conn.engine.execute(query, {"values": list(typelist)})

方案2：使用ORM链式查询的内置in_()方法 #

如果使用SQLAlchemy ORM定义了表模型，直接调用列对象的in_()方法即可，框架会自动处理多值绑定逻辑：

from sqlalchemy import select
# 假设User是对应业务表的ORM模型
stmt = select(User).where(User.Type.in_(typelist))
result = conn.execute(stmt).scalars().all()

注意：不要通过字符串拼接的方式把集合值拼接到SQL语句中构造IN子句，会存在严重的SQL注入安全风险。

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