You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/specification/modules/search.rst

88 lines
2.8 KiB
ReStructuredText

Server Side Search
==================
.. _module:search:
The search API allows clients to perform full text search across events in all
rooms that the user has been in, including those that they have left. Only
events that the user is allowed to see will be searched, e.g. it won't include
9 years ago
events in rooms that happened after you left.
Client behaviour
----------------
{{search_http_api}}
Search Categories
-----------------
The search API allows clients to search in different categories of items.
Currently the only specified category is ``room_events``.
``room_events``
~~~~~~~~~~~~~~~
This category covers all events that the user is allowed to see, including
events in rooms that they have left. The search is performed on certain keys of
certain event types.
The supported keys to search over are:
- ``content.body`` in ``m.room.message``
- ``content.name`` in ``m.room.name``
- ``content.topic`` in ``m.room.topic``
The search will *not* include rooms that are end to end encrypted.
9 years ago
The results include a ``rank`` key that can be used to sort the results by
revelancy. The higher the ``rank`` the more relevant the result is.
9 years ago
The value of ``count`` may not match the number of results. For example due to
the search query matching 1000s of results and the server truncating the
response.
Ordering
--------
The client can specify the ordering that the server returns results in. The two
allowed orderings are:
- ``rank``, which returns the most relevant results first.
- ``recent``, which returns the most recent results first.
The default ordering is ``rank``.
Groups
------
The client can request that the results are returned along with grouping
information, e.g. grouped by ``room_id``. In this case the response will
contain a group entry for each distinct value of ``room_id``. Each group entry
contains at least a list of the ``event_ids`` that are in that group, as well
as potentially other metadata about the group.
Pagination
----------
The server may return a ``next_batch`` key at various places in the response.
These are used to paginate the results. To fetch more results, the client
should send the *same* request to the server with a ``next_batch`` query
parameter set to that of the token.
The scope of the pagination is defined depending on where the ``next_batch``
token was returned. For example, using a token inside a group will return more
results from within that group.
The currently supported locations for the ``next_batch`` token are:
- ``search_categories.<category>.next_batch``
- ``search_categories.<category>.groups.<group_key>.<group_id>.next_batch``
A server need not support pagination, even if there are more matching results.
In which case they must not return a ``next_batch`` token in the response.
Security considerations
-----------------------
The server must only return results that the user has permission to see.