Merge pull request #169 from matrix-org/erikj/search_yet_agian

Search: Document event context, groups and orders.

specification/modules/search.rst

@@ -40,6 +40,53 @@ 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.
+
+The current required supported groupings are:
+
+- ``room_id``
+- ``sender``
+
+
+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.