# 搜索结果定制

虽然 Typesense 让提供优质搜索结果变得非常简单直观，但有时您可能希望提升某些文档的排名，或者从查询结果中排除特定文档。

通过使用覆盖规则(overrides)，您可以为特定查询包含或排除指定的文档。

优先级

当同时使用同义词和覆盖规则时，覆盖规则会优先处理，因为这些规则可能包含替换查询的指令。同义词将在修改后的查询上生效。

# 创建或更新覆盖规则

# 包含或排除文档

在以下示例中，我们将：

使用 includes 条件将 ID 为 422 和 54 的文档分别放置在第一和第二位置
使用 excludes 条件从结果中移除 ID 为 287 的文档

Typesense 允许您同时使用 includes 和 excludes，或仅使用其中一种来进行结果定制。

请注意，我们这里对精确匹配 apple 查询应用这些覆盖规则。如果想匹配所有包含 apple 单词的查询，则应改用 contains 匹配方式。

# 示例响应

# 为规则添加标签

您可以为重写规则添加标签，然后通过直接引用标签名称来触发内容定制。

{
    "overrides": [
        {
            "id": "tagging-example",
            "includes": [{"id": "1348","position": 1}],
            "rule": {
                "match": "exact",
                "query": "iphone pro",
                "tags": ["apple", "iphone"]
            }
        }
    ]
}

现在，当我们搜索集合时，可以通过 override_tags 参数传递一个或多个标签来直接触发匹配这些标签的定制规则：

{
   "override_tags": "apple,iphone"
}

关于规则标签工作方式的补充说明

如果 override1 标记了 tagA,tagB，override2 仅标记了 tagA，而 override3 没有标记：

如果搜索设置 override_tags 为 tagA，我们只考虑包含 tagA 的重写规则（override1 和 override2），按照常规逻辑处理——按重写名称的字母顺序排列，如果 stop_processing 为 false 则处理两者。
如果搜索设置 override_tags 为 tagA,tagB，我们会先评估同时包含 tagA 和 tagB 的规则，然后是包含 tagA 或 tagB 的规则，但不处理未标记任何标签的重写规则。在每组内部，我们按重写名称的字母顺序评估，如果 stop_processing 为 false 则处理多个规则。
如果搜索未设置 override_tags，我们只考虑没有关联任何标签的规则。

# 动态过滤

在以下示例中，我们将对符合规则的查询动态应用过滤器。

当这个覆盖规则生效后，任何包含品牌名称的查询都会自动应用对应的品牌过滤条件。此外，品牌名称也会从原始查询词中移除，使得搜索仅针对剩余的词进行。

例如，如果有人搜索 sony ericsson phone，查询会被重写为 phone 并直接应用 sony ericsson 品牌过滤。如果你不希望从查询中移除匹配的词，可以将 remove_matched_tokens 设置为 false。默认情况下，这个参数设为 true。

注意

用于动态过滤查询的字段，在模式定义中应该设置 facet: true。

# 人工筛选与过滤

includes 用于将文档固定在结果中的特定位置，但当使用 filter_curated_hits: true 时，这些文档可能会被过滤掉。

当这种情况发生时，Typesense 会将由 includes 添加的剩余文档在结果中"上移"。例如，假设您有一个产品记录集合，按 ranking 字段排序后如下所示：

1. ABC123 (有库存)
2. DEF456 (已售罄)
3. XYZ999 (已售罄)
4. QWE127 (有库存)
5. BNM847 (有库存)
6. JKL999 (有库存)
7. CVB333 (有库存)

假设创建了一个使用 includes 将以下记录固定到特定位置的覆盖规则。该覆盖规则还设置了 filter_curated_hits 为 true，因此如果由 includes 添加的文档不匹配任何 filter_by 条件，它们可能会被过滤掉：

- QWE127 固定在位置 1
- DEF456 固定在位置 2
- CVB333 固定在位置 3

当此覆盖规则应用于搜索时，结果将是：

1. QWE127 (有库存) <- 由 includes 设置的位置
2. DEF456 (已售罄) <- 由 includes 设置的位置
3. CVB333 (有库存) <- 由 includes 设置的位置
4. ABC123 (有库存)
5. XYZ999 (已售罄)
6. BNM847 (有库存)
7. JKL999 (有库存)

如果在搜索中添加了 status:=in stock 过滤器，则已售罄的记录将被移除。这包括 DEF456，即使它是覆盖规则试图通过 includes 添加的记录之一（因为它已售罄且覆盖规则设置了 filter_curated_hits: true）。最终结果是来自覆盖规则的两个有库存记录出现在位置 1 和 2，其余记录位于它们下方：

1. QWE127 (有库存) <- 由 includes 设置的位置
2. CVB333 (有库存) <- 由 includes 设置的位置（上移）
3. ABC123 (有库存)
4. BNM847 (有库存)
5. JKL999 (有库存)

文档 CVB333 "上移"到位置 2，取代了 DEF456（已被过滤掉）。

# 覆盖规则参数

# 定义

PUT ${TYPESENSE_HOST}/collections/:collection/overrides/:id

# 参数

参数名	是否必填	描述
rule.query	`rule.query` 和 `rule.filter_by` 必须二选一	指定需要被覆盖的搜索查询内容
rule.match	否	指定查询词的匹配方式为 `exact`（精确匹配）或 `contains`（包含匹配）。当设置 `rule.query` 时必须指定
rule.filter_by	`rule.query` 和 `rule.filter_by` 必须二选一	当搜索查询中的 `filter_by` 参数完全匹配此处指定的字符串时（包括反引号、空格、括号等），该覆盖规则将生效
rule.tags	否	与此覆盖规则关联的标签值列表
excludes	否	应从搜索结果中排除的文档 `id` 列表
includes	否	应包含在搜索结果中的文档 `id` 列表及其对应的 `positions`（位置）
metadata	否	当此规则被触发时，在 Search API 响应中返回一个自定义 JSON 对象。可用于在前端显示预定义消息（例如：促销横幅）
filter_by	否	应用于匹配覆盖规则的任何搜索查询的过滤条件
sort_by	否	应用于匹配覆盖规则的任何搜索查询的排序条件
replace_query	否	当搜索查询匹配覆盖规则时，用此值替换当前搜索查询
remove_matched_tokens	否	指定是否应从搜索查询中移除与覆盖规则匹配的查询词默认值：`true`
filter_curated_hits	否	设为 `true` 时，查询的过滤条件也会应用于精选记录默认值：`false`
effective_from_ts	否	Unix 时间戳，表示覆盖规则开始生效的日期/时间。可用于创建未来某个时间点才开始应用的覆盖规则
effective_to_ts	否	Unix 时间戳，表示覆盖规则停止生效的日期/时间。可用于创建仅在一段时间内有效的覆盖规则
stop_processing	否	设为 `true` 时，覆盖规则处理将在第一个匹配规则处停止。设为 `false` 时，覆盖处理会继续并按顺序触发多个覆盖动作覆盖规则按其 `id` 字段的字典顺序处理默认值：`true`

# 在范围限定的 API 密钥中使用覆盖规则

当使用嵌入了过滤条件的范围限定 API 密钥时，您可以配置覆盖规则来适配这些过滤后的查询。为此，需要确保覆盖规则的 rule.filter_by 字段与 Typesense 最终构建的过滤字符串完全匹配。

当一个带有过滤条件的范围限定 API 密钥与包含自身过滤条件的搜索查询一起使用时，Typesense 会按照以下格式组合它们：

(request_filter) && (scoped_api_key_filter)

特别注意其中的括号以及用空格分隔的 && 连接符。

例如：

如果您的范围限定 API 密钥嵌入了以下条件：{"filter_by":"country: AU"}
而您的搜索请求包含：filter_by=title:hold
最终的过滤字符串将变为：(title:hold) && (country: AU)

要使覆盖规则在给定的过滤条件和范围限定 API 密钥下触发，您覆盖规则定义中的 rule.filter_by 字段必须严格匹配上述第 3 点中的字符串。

# 列出所有覆盖规则

列出与指定集合关联的所有覆盖规则。

注意：默认情况下会返回所有覆盖规则，但您可以使用 offset 和 limit 参数进行分页查询。

# 示例响应

# 定义

GET ${TYPESENSE_HOST}/collections/:collection/overrides

# 检索覆盖规则

获取与集合关联的单个覆盖规则。

# 示例响应

# 定义

GET ${TYPESENSE_HOST}/collections/:collection/overrides/:id

# 删除覆盖规则

删除与集合关联的覆盖规则。

# 示例响应

# 定义

DELETE ${TYPESENSE_HOST}/collections/:collection/overrides/:id

← API 密钥集合别名 →