# 分析与查询建议

Typesense 可以聚合搜索查询，既可用于分析目的，也可用于提供查询建议。

# 启用功能

# 自托管时

要使查询建议和其他分析功能正常工作，需要通过 --enable-search-analytics 和 --analytics-dir 参数显式启用搜索分析功能。

./typesense-server --data-dir=/path/to/data --api-key=abcd \
  --enable-search-analytics=true \
  --analytics-dir=/path/to/analytics-data \
  --analytics-flush-interval=60

--analytics-flush-interval 参数决定了搜索查询聚合数据持久化到建议集合的频率。

设置较小的值（最小值为 60 秒）可以使建议集合更新更频繁。默认值为 3600 秒（每小时一次）。

# 在 Typesense Cloud 上

在 Typesense Cloud 中，我们会自动设置 --enable-search-analytics=true 和 --analytics-flush-interval=300（每5分钟一次）（更多上下文见上文）。

# 为特定查询禁用

要为特定搜索查询禁用分析聚合（例如来自测试脚本的查询），可以在搜索查询参数中设置 enable_analytics: false。

# 查询建议

您可以捕获系统中发生的搜索查询，用于跟踪热门查询或为自动补全功能提供支持。

# 创建查询集合

首先，我们需要创建一个新的集合，用于聚合和记录搜索查询。

这个集合与其他 Typesense 集合类似，不同之处在于它由 Typesense 自动填充，内容来自发送到其他集合的搜索查询。

q 和 count 字段是必填项。

# 创建分析规则

现在我们可以创建一个名为 popular_queries 的分析规则，用于存储在上述创建的集合中最频繁出现的搜索查询。我们通过 limit 参数将热门查询限制为前 1000 条。

这样就完成了！

当您在 products（源）集合上执行搜索时，搜索查询将被聚合并存储到 product_queries（目标）集合中。

查询将根据 Typesense 集群上的 analytics-flush-interval 配置进行聚合并发送到目标集合。

请注意，popular_queries 分析类型只会跟踪有搜索结果的查询。

自动扩展前缀搜索查询:

在创建分析规则时，您可以设置 expand_query: true 让 Typesense 聚合搜索查询的扩展版本。例如，如果用户在输入 sho 时停止输入，而实际获取的是单词 shoe 的结果，将此参数设为 true 将使 Typesense 聚合单词 shoe 而非 sho。默认情况下，该参数为 false，即我们将捕获用户的实际查询（包括前缀查询）而不进行任何扩展。

注意: 在 Typesense Cloud 上，此聚合操作每5分钟执行一次。

# 通过API发送事件

如果您希望通过API将搜索查询作为事件发送，可以创建一个定义了 search 事件的分析规则用于消费。通过将 enable_auto_aggregation 设为 false，只有通过API发送的搜索查询会被聚合。

{
  "name": "product_queries_aggregation",
  "type": "popular_queries",
  "params": {
    "source": {
      "collections": [
        "products"
      ],
      "enable_auto_aggregation": false,
      "events": [
        {
          "type": "search",
          "name": "products_search_event"
        }
      ]
    },
    "destination": {
      "collection": "product_queries"
    },
    "limit": 1000
  }
}

设置此规则后，您现在可以直接通过API将查询作为 search 事件发送。

curl "http://localhost:8108/analytics/events" -X POST \
     -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     -d '{
            "type": "search",
            "name": "products_search_event",
            "data": {
                  "q": "running shoes",
                  "user_id": "1234"
            }
        }'

# 查询建议用户体验

设置好上述分析规则后，热门搜索词将开始出现在目标集合中。

现在你可以像使用其他 Typesense 集合一样使用这个集合中的数据，并向其发送搜索查询，从而为查询建议功能提供支持。

你还可以使用 multi_search 并行地向主索引发送查询，实现查询建议和实际结果并排显示的效果。

# 聚合键

当您向源集合发送搜索查询时，可以选择发送 x-typesense-user-id 参数或 X-TYPESENSE-USER-ID 请求头来标识发起该特定搜索请求的用户。如果未指定，Typesense 默认会使用客户端 IP 地址进行聚合。

由于 Typesense 可用于输入提示搜索（type-ahead searches），只有当查询后至少有 4 秒停顿 时，该搜索查询才会被计入聚合。例如，f -> fo -> foo -> 4 秒停顿 将只记录 foo 查询。

TIP

在本地测试时，请注意这 4 秒停顿规则以及 analytics-flush-interval 配置。

如果您在短时间内向源集合发送大量查询，搜索词可能不会立即出现在目标集合中。

# 无结果查询

与热门查询类似，您也可以跟踪未返回任何结果的查询。这些查询可帮助您识别内容中的空白。

# 为查询创建集合

首先，我们需要创建一个新的集合，用于聚合和记录那些没有返回任何结果的搜索查询。

这个集合和其他 Typesense 集合类似，不同之处在于它由 Typesense 自动填充那些没有命中结果的搜索查询。

q 和 count 字段是必填的。

# 创建分析规则

我们将跟踪在搜索 products 集合时未产生匹配结果的最频繁出现的 1000 条查询。这些查询会被聚合到 no_hits_queries 集合中。

# 事件计数统计受欢迎度

Typesense 允许您追踪特定文档被点击或购买的频率。然后您可以使用这个计数值来根据受欢迎度对搜索结果进行排序。

假设有一个包含 popularity 字段的集合，我们将使用该字段作为计数器：

{
  "name": "products",
  "fields": [
    {"name": "title", "type": "string"},
    {"name": "popularity", "type": "int32", "optional": true}
  ]
}

我们将 popularity 字段标记为 optional，因为我们希望在索引时跳过该字段，让 Typesense 根据用户交互来递增该字段的值。

# 创建分析规则

让我们定义一个 counter（计数器）分析规则，当点击事件发生时该规则将递增指定字段。

计数器规则指定了需要追踪的集合以及计数器值存储的位置。事件参数中的 weight 属性决定了增量的大小。在本例中，每当与文档关联的 click 事件发送到 Typesense 时，我们希望将 popularity 字段的值递增 1。

# 发送点击事件

当计数器规则设置完成后，您就可以开始发送点击事件了，使用我们之前在计数器规则中配置的事件名称（products_click_counter）：

curl "http://localhost:8108/analytics/events" -X POST \
     -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     -d '{
            "type": "click",
            "name": "products_click_event",
            "data": {
                  "doc_id": "1024",
                  "user_id": "111112"
            }
        }'

点击事件会被聚合处理，事件数据中 doc_id 指定的文档 id 对应的 popularity 字段值会增加。聚合频率由 --analytics-flush-interval 选项控制。

TIP

请确保事件负载中发送的 doc_id 与目标集合中实际存储文档的 id 相匹配。

# 聚合多个事件

实际上，您可以设置一个计数器规则，为不同事件赋予不同的权重。

事件类型	描述
click	跟踪针对搜索响应返回文档的点击行为
conversion	跟踪特定文档的转化行为（例如购买）
visit	跟踪特定文档的页面访问，适用于推荐场景

让我们设置一个同时聚合 click 和 conversion 事件的规则。

{
  "name": "products_popularity",
  "type": "counter",
  "params": {
    "source": {
      "collections": [
        "products"
      ],
      "events": [
        {
          "type": "click",
          "weight": 1,
          "name": "products_click_event"
        },
        {
          "type": "conversion",
          "weight": 2,
          "name": "products_purchase_event"
        }
      ]
    },
    "destination": {
      "collection": "products",
      "counter_field": "popularity"
    }
  }
}

现在您可以通过 API 发送 conversion 事件。

curl "http://localhost:8108/analytics/events" -X POST \
     -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
     -d '{
            "type": "conversion",
            "name": "products_purchase_event",
            "data": {
                  "doc_id": "1022",
                  "user_id": "111117"
            }
        }'

由于我们将 conversion 事件的权重配置为 2，因此每次转化事件都会使 products 集合中的 popularity 字段增加 2。

# 列出所有规则

该列表API允许您列出存储在Typesense集群中的所有分析规则。

# 删除规则

删除分析规则将停止新查询的聚合，但已聚合的查询仍会保留在目标集合中。

← JOIN 查询 API 密钥 →