Django查询集过滤时integer转smallint失败的问题排查

你遇到的类型转换错误，核心原因是枚举值类型与数据库字段类型的匹配问题：

• Genre枚举继承自IntegerChoices，其值是Python标准int类型
• 数据库中genres字段是smallint[]类型（对应Django的PositiveSmallIntegerField嵌套ArrayField）
• 写入数据时，Django会通过字段转换器自动把int转成smallint，但查询过滤阶段的类型处理逻辑不同，导致psycopg2无法直接将integer转为smallint[]

方案1：最简单的修正——传入包含枚举值的列表 #

对于ArrayField的__contains查询，Django期望传入的是可迭代对象（而非单个值），直接把枚举值放到列表中即可触发正确的类型转换：

genre = Genre.scifi
# 正确过滤包含该类型的书籍
Book.objects.filter(genres__contains=[genre.value])

方案2：显式类型转换（更严谨） #

如果需要严格对齐数据库字段类型，可以用Django ORM的Cast和Value函数，强制将枚举值转为smallint类型：

from django.db.models import Value, Cast
from django.db.models.fields import SmallIntegerField
from django.contrib.postgres.fields import ArrayField

genre = Genre.scifi

# 单个元素包含查询
Book.objects.filter(
    genres__contains=Cast(Value(genre.value), output_field=SmallIntegerField())
)

# 匹配整个数组的查询（比如genres恰好等于[1]）
Book.objects.filter(
    genres=Cast(Value([genre.value]), output_field=ArrayField(SmallIntegerField()))
)

方案3：自定义SmallIntegerChoices（长期复用） #

如果你的项目中有多个类似的小整数枚举需求，可以自定义一个基础Choices类，统一处理类型逻辑：

from django.db.models import IntegerChoices

class SmallIntegerChoices(IntegerChoices):
    def __repr__(self):
        return f"<{self.__class__.__name__}.{self.name}: {self.value}>"
    
    def __int__(self):
        return self.value

# 继承自定义类定义枚举
class Genre(SmallIntegerChoices):
    fantasy = 0, "奇幻"
    scifi = 1, "科幻"
    real = 2, "现实"

之后使用枚举值过滤时，依然配合方案1或方案2的方式即可，这个类主要是统一枚举的行为规范。

• 不要尝试直接用genres=genre过滤，因为genres是数组字段，单个枚举值（int类型）与数组类型不匹配，必然会触发错误
• PostgreSQL对类型匹配的要求比MySQL等数据库更严格，所以这种类型转换问题在PostgreSQL中更常见

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