PyMongo聚合管道文本搜索报错及部分匹配问题咨询

你碰到的两个问题属于两类独立问题：

• 抛出FieldPath field names may not start with '$'错误是聚合管道写法错误：你在$sort阶段直接引用了尚未生成的score字段，$meta: textScore不能绑定在未定义的字段上使用，要么直接在sort阶段调用$meta表达式，要么提前在$addFields/$project阶段计算出score字段后再排序。
• 调整代码后仅能返回整词匹配结果、无法匹配3个字符的部分内容，是MongoDB原生文本索引的固有能力边界：默认的文本索引仅支持整词分词匹配，不支持任意子串、前缀模糊匹配。比如搜索关键词whit时，只有字段值中存在独立的whit整词才会命中，字段值为white时两者属于不同分词项，无法被匹配到，这个问题和代码写法无关。

根据你的数据量规模二选一即可：

方案1：10万条以内数据量，轻量实现 #

如果集合数据量不大，不需要复杂分词能力，直接用正则匹配+自定义相关性评分即可，完全支持3个及以上字符的部分匹配需求，排序权重可以根据业务灵活调整：

import re
search_key = "whit" # 替换为前端传入的搜索关键词
# 转义正则特殊字符，避免用户传入正则符号导致查询逻辑异常
escaped_key = re.escape(search_key)

pipeline = [
    # 第一步：过滤出username或full_name包含搜索关键词的文档，不区分大小写
    {
        "$match": {
            "$or": [
                {"username": {"$regex": escaped_key, "$options": "i"}},
                {"full_name": {"$regex": escaped_key, "$options": "i"}}
            ]
        }
    },
    # 第二步：计算自定义相关性得分，权重可根据业务需求自行调整
    {
        "$addFields": {
            "score": {
                "$sum": [
                    # username匹配得分
                    {"$cond": [{"$eq": ["$username", search_key]}, 100, 0]}, # username完全匹配加100分
                    {"$cond": [{"$regexMatch": {"input": "$username", "regex": f"^{escaped_key}", "options": "i"}}, 30, 0]}, # username前缀匹配加30分
                    {"$cond": [{"$regexMatch": {"input": "$username", "regex": escaped_key, "options": "i"}}, 10, 0]}, # username子串匹配加10分
                    # full_name匹配得分
                    {"$cond": [{"$eq": ["$full_name", search_key]}, 80, 0]}, # full_name完全匹配加80分
                    {"$cond": [{"$regexMatch": {"input": "$full_name", "regex": f"^{escaped_key}", "options": "i"}}, 20, 0]}, # full_name前缀匹配加20分
                    {"$cond": [{"$regexMatch": {"input": "$full_name", "regex": f"\\b{escaped_key}", "options": "i"}}, 15, 0]}, # full_name内单词前缀匹配加15分
                    {"$cond": [{"$regexMatch": {"input": "$full_name", "regex": escaped_key, "options": "i"}}, 5, 0]}, # full_name子串匹配加5分
                ]
            }
        }
    },
    # 第三步：按相关性得分倒序排序
    {"$sort": {"score": -1}},
    # 第四步：返回需要的字段
    {"$project": {"username": 1, "full_name": 1, "image": 1, "score": 1}}
]

users = users_db.aggregate(pipeline)

这个方案无额外依赖，逻辑完全可控，足以覆盖大部分中小规模业务的搜索需求。

方案2：10万条以上数据量，生产级高性能实现 #

如果集合数据量较大，正则查询性能无法满足要求，不要继续使用MongoDB原生文本索引，直接对接专用搜索引擎实现：

• 选型可以用Elasticsearch或者更轻量的MeiliSearch，给username、full_name字段建立搜索索引，配置最小分词长度为3，开启前缀匹配能力
• 搜索请求先打到搜索引擎，拿到按相关性排序的文档ID后，再回MongoDB批量查询对应的完整用户信息
• 专用搜索引擎天生对短文本模糊匹配、自定义权重、相关性排序有专门优化，性能远高于MongoDB正则和原生文本索引，是生产环境大规模数据搜索的标准方案。

附：如果只是需要修复原生文本搜索的报错、不需要部分匹配能力，正确的管道写法参考如下，两种写法都可以解决字段路径报错问题：

# 写法1：sort阶段直接调用textScore
pipeline1 = [
    {"$match": {"$text": {"$search": "whit"}}},
    {"$sort": {"$meta": "textScore"}},
    {"$project": {"username": 1, "full_name": 1, "image": 1}}
]

# 写法2：提前生成score字段再排序
pipeline2 = [
    {"$match": {"$text": {"$search": "whit"}}},
    {"$addFields": {"score": {"$meta": "textScore"}}},
    {"$sort": {"score": -1}},
    {"$project": {"username": 1, "full_name": 1, "image": 1, "score": 1}}
]

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