### 服务器端搜索

搜索 API 允许客户端对用户所加入过的所有房间中的事件进行全文搜索，包括用户已经离开的房间。仅搜索用户有权限查看的事件，例如，用户离开房间后发生的事件将不会被包含。

#### 客户端行为

服务器端搜索有一个统一的 HTTP API，具体文档如下。

{{% http-api spec="client-server" api="search" %}}

#### 搜索类别

搜索 API 允许客户端按不同类别进行搜索。目前唯一被明确定义的类别是 `room_events`。

##### `room_events`

该类别包含所有用户有权限查看的事件，包括用户已经离开的房间中的事件。搜索会在特定事件类型的特定键值上进行。

支持检索的字段包括：

-   `m.room.message` 事件的 `content.body`
-   `m.room.name` 事件的 `content.name`
-   `m.room.topic` 事件的 `content.topic`

加密的房间（端对端加密）不会被包含在搜索范围内。

搜索结果包含一个 `rank` 键，可用于按相关度排序结果。`rank` 值越高，结果越相关。

`count` 字段用于大致表示总结果数。Homeserver 可能会返回一个估计值，而非精确值。

#### 排序方式

客户端可以指定服务器返回结果的排序方式。允许的两种排序方式为：

-   `rank`：首先返回最相关的结果。
-   `recent`：首先返回最新的结果。

默认排序方式为 `rank`。

#### 分组

客户端可以请求返回带有分组信息的结果，例如按 `room_id` 分组。在这种情况下，响应中会包含每个不同 `room_id` 的分组条目。每个分组条目至少包含该分组内的 `event_id` 列表，也可能包含关于该分组的其他元数据。

当前要求支持的分组方式有：

-   `room_id`
-   `sender`

#### 分页

服务器响应中各处可能会返回一个 `next_batch` 键。它用于对结果进行分页。若需获取更多结果，客户端应使用相同的请求，并将 `next_batch` 查询参数设置为该标记。

分页的范围取决于 `next_batch` 标记返回的位置。例如，在分组内使用该标记将返回该分组中的更多结果。

目前支持的 `next_batch` 标记位置有：

-   `search_categories.<category>.next_batch`
-   `search_categories.<category>.groups.<group_key>.<group_id>.next_batch`

即使存在更多匹配结果，服务器也可以选择不支持分页。在这种情况下，响应中不得返回 `next_batch` 标记。

#### 安全性注意事项

服务器只能返回用户有权限查看的结果。