Django自定义全文搜索排序如何使用PostgreSQL @@匹配运算符

Django内置的django.contrib.postgres.search模块没有直接暴露@@全文匹配运算符的表达式接口，你可以通过自定义数据库表达式或者参数化原生SQL片段两种方式，实现需要的自定义排名逻辑，完全兼容QuerySet的链式调用。

方案1：纯ORM表达式实现（无硬编码SQL） #

通过Django提供的Func基类自定义数据库函数和运算符，完全遵循ORM的表达式逻辑，自动适配数据库转义，无注入风险：

1. 首先自定义需要的表达式组件

from django.db.models import F, FloatField, IntegerField, Value
from django.db.models.expressions import Func, ExpressionWrapper
from django.db.models.functions import Coalesce
from django.contrib.postgres.search import SearchVector, SearchQuery

# 实现tsvector和tsquery的@@匹配，返回整数类型的匹配结果（1=匹配，0=不匹配）
class TSMatch(Func):
    arity = 2
    function = ""
    arg_joiner = " @@ "
    output_field = IntegerField()

    def as_sql(self, compiler, connection, **extra_context):
        base_sql, params = super().as_sql(compiler, connection, **extra_context)
        return f"({base_sql})::int", params

# 封装正则切分字符串为数组的函数
class RegexpSplit(Func):
    function = "regexp_split_to_array"
    arity = 2

# 封装数组长度计算函数
class ArrLen(Func):
    function = "array_length"
    arity = 2

2. 在QuerySet中注解自定义排名字段

# 替换为实际的搜索关键词
search_keyword = "my search query"

queryset = MyModel.objects.annotate(
    # 构建英文分词的向量和查询表达式
    title_vec=SearchVector("title", config="english"),
    title_query=SearchQuery(search_keyword, config="english", search_type="plain"),
    # 匹配标记：匹配为1，不匹配为0
    is_match=TSMatch(F("title_vec"), F("title_query")),
    # 计算title字段的单词总数
    title_word_count=ArrLen(RegexpSplit(F("title"), Value(r"\s+")), Value(1)),
    # 计算最终自定义排名，空内容默认返回0
    custom_rank=Coalesce(
        ExpressionWrapper(
            F("is_match") * 1.0 / F("title_word_count"),
            output_field=FloatField()
        ),
        Value(0.0)
    )
# 按自定义排名倒序排序
).order_by("-custom_rank")

方案2：参数化原生SQL片段（代码更简洁） #

如果不需要完全抽象的ORM表达式，可以用RawSQL传入参数化的原生SQL片段，搜索词通过参数位置传递，同样可以避免SQL注入风险，代码量更少：

from django.db.models import FloatField, Value
from django.db.models.expressions import RawSQL
from django.db.models.functions import Coalesce

search_keyword = "my search query"

queryset = MyModel.objects.annotate(
    custom_rank=Coalesce(
        RawSQL(
            """
            (to_tsvector('english', title) @@ plainto_tsquery('english', %s))::int::float
            / array_length(regexp_split_to_array(title, '\s+'), 1)
            """,
            (search_keyword,),
            output_field=FloatField()
        ),
        Value(0.0)
    )
).order_by("-custom_rank")

扩展说明 #

• 两种方案生成的SQL和手写的原生逻辑完全一致，不匹配时排名为0，匹配时排名为1/字段单词总数
• 如果需要对多个字段（比如content、description）计算排名，只需要为每个字段单独编写对应的rank注解，最后将多个rank值求和作为总排序值即可
• 加入Coalesce是为了处理字段为空的边界情况，避免空值导致排序异常

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