From e2eb0c7ad9c0424450e9e14c3ee24d65d93e45de Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 16 Nov 2015 16:04:23 +0000 Subject: [PATCH 01/18] Add new request options --- api/client-server/v1/search.yaml | 54 ++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml index cc299056..5549ab2c 100644 --- a/api/client-server/v1/search.yaml +++ b/api/client-server/v1/search.yaml @@ -39,6 +39,14 @@ paths: ], "search_term": "martians and men" } + }, + "order_by": "recent", + "groupings": { + "group_by": [ + { + "key": "room_id" + } + ] } } properties: @@ -68,6 +76,52 @@ paths: description: |- The filter to apply to search results. This has the same format as v2 filter API. + order_by: + title: "Ordering" + type: string + enum: ["recent", "rank"] + description: "The order in which to search for results." + event_context: + title: "Event Context" + type: object + description: |- + Configures whether any context for the events + returned are included in the response. + properties: + before_limit: + type: integer + title: "Before limit" + description: |- + How many events before the result are + returned. + after_limit: + type: integer + title: "After limit" + description: |- + How many events after the result are + returned. + groupings: + type: object + title: Groupings + description: |- + Requests the server returns results with information + about how they fit into groups the specified groups. + properties: + group_by: + type: array + title: Groups + description: List of groups to request. + items: + type: object + title: Group + description: Configuration for group. + properties: + key: + type: string + title: Group Key + description: |- + Key that defines the group. + enum: ["room_id", "sender"] required: ["search_term"] required: ["search_categories"] responses: From 5e0e4a851869abd81709deb2677c74657a9ce9dd Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 16 Nov 2015 17:22:56 +0000 Subject: [PATCH 02/18] Document group and context response keys --- api/client-server/v1/search.yaml | 89 +++++++++++++++++++++++++++++--- 1 file changed, 83 insertions(+), 6 deletions(-) diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml index 5549ab2c..e453c523 100644 --- a/api/client-server/v1/search.yaml +++ b/api/client-server/v1/search.yaml @@ -161,15 +161,92 @@ paths: this result matches the search. Higher is closer. result: - type: object - title: Event - description: The event that matched. - allOf: - - "$ref": "core-event-schema/room_event.json" + type: object + title: Event + description: The event that matched. + allOf: + - "$ref": "core-event-schema/room_event.json" + context: + type: object + title: Event Context + description: Context for result, if requested. + properties: + start: + type: string + title: Start Token + description: |- + Pagination token for the start of the chunk + end: + type: string + title: End Token + description: |- + Pagination token for the end of the chunk + events_before: + type: array + title: Events Before + description: Events just before the result. + items: + type: object + title: Event + allOf: + - "$ref": "core-event-schema/room_event.json" + events_after: + type: array + title: Events After + descriptions: Events just after the result. + items: + type: object + title: Event + allOf: + - "$ref": "core-event-schema/room_event.json" + groups: + type: object + title: Groups + description: Any groups that were requseted. + additionalProperties: + type: object + title: Group Key + description: The results for a given group. + additionalProperties: + type: object + title: Group Value + description: |- + The results for a particular group value. + properties: + next_batch: + type: string + title: Next Batch in Group + description: |- + Token that can be used to get the next + batch of results if exists. + order: + type: integer + title: Group Order + description: |- + Key that can be used to order different + groups. + results: + type: array + description: |- + Which results are in this group. + items: + type: string + title: Result Event ID examples: application/json: |- { "search_categories": { + "groups": { + "room_id": { + "!qPewotXpIctQySfjSy:localhost": { + "order": 1, + "next_batch": "BdgFsdfHSf-dsFD", + "results": [ + "$144429830826TWwbB:localhost" + ] + } + } + }, "room_events": { "count": 24, "results": { @@ -178,7 +255,7 @@ paths: "result": { "age": 526228296, "content": { - "body": "Test content", + "body": "Test content martians and men", "msgtype": "m.text" }, "event_id": "$144429830826TWwbB:localhost", From 8991c4fa78c5a3854145a5f3d63e21aa98738bfa Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 16 Nov 2015 18:00:48 +0000 Subject: [PATCH 03/18] Fix schema and example --- api/client-server/v1/search.yaml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml index e453c523..e9598ac3 100644 --- a/api/client-server/v1/search.yaml +++ b/api/client-server/v1/search.yaml @@ -193,7 +193,7 @@ paths: events_after: type: array title: Events After - descriptions: Events just after the result. + description: Events just after the result. items: type: object title: Event @@ -236,18 +236,18 @@ paths: application/json: |- { "search_categories": { - "groups": { - "room_id": { - "!qPewotXpIctQySfjSy:localhost": { - "order": 1, - "next_batch": "BdgFsdfHSf-dsFD", - "results": [ - "$144429830826TWwbB:localhost" - ] - } - } - }, "room_events": { + "groups": { + "room_id": { + "!qPewotXpIctQySfjSy:localhost": { + "order": 1, + "next_batch": "BdgFsdfHSf-dsFD", + "results": [ + "$144429830826TWwbB:localhost" + ] + } + } + }, "count": 24, "results": { "$144429830826TWwbB:localhost": { From ffed14a0cd5693131b6f44a0d67788699804fd12 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 17 Nov 2015 10:02:02 +0000 Subject: [PATCH 04/18] Add next_batch token --- api/client-server/v1/search.yaml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml index e9598ac3..34b3c150 100644 --- a/api/client-server/v1/search.yaml +++ b/api/client-server/v1/search.yaml @@ -218,7 +218,7 @@ paths: title: Next Batch in Group description: |- Token that can be used to get the next - batch of results if exists. + batch of results in the group, if exists. order: type: integer title: Group Order @@ -232,6 +232,12 @@ paths: items: type: string title: Result Event ID + next_batch: + type: string + title: Next Batch + description: |- + Token that can be used to get the next batch of + results, if exists. examples: application/json: |- { From 373c6c827056124a98a70b8a75387e633c53127f Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 17 Nov 2015 11:56:05 +0000 Subject: [PATCH 05/18] Add ordering, pagination and grouping comments --- specification/modules/search.rst | 35 ++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/specification/modules/search.rst b/specification/modules/search.rst index 089953d2..f44bb585 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -40,6 +40,41 @@ 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. + +A server need not support pagination, even if there are more matching results. + + Security considerations ----------------------- The server must only return results that the user has permission to see. From 46870da57d03d4f682fd754e6374d06c4d7a94d9 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Fri, 20 Nov 2015 15:29:36 +0000 Subject: [PATCH 06/18] Add optional profile info and state in search response --- api/client-server/v1/search.yaml | 40 ++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/api/client-server/v1/search.yaml b/api/client-server/v1/search.yaml index 34b3c150..a5cc9422 100644 --- a/api/client-server/v1/search.yaml +++ b/api/client-server/v1/search.yaml @@ -100,6 +100,19 @@ paths: description: |- How many events after the result are returned. + include_profile: + type: boolean + title: "Return profile information" + description: |- + Requests that the server returns the + historic profile information for the users + that sent the events that were returned. + include_state: + type: boolean + title: Include current state + description: |- + Requests the server return the current state for + each room returned. groupings: type: object title: Groupings @@ -181,6 +194,22 @@ paths: title: End Token description: |- Pagination token for the end of the chunk + profile_info: + type: object + title: Profile Information + description: |- + The historic profile information of the + users that sent the events returned. + additionalProperties: + type: object + title: User Profile + properties: + displayname: + type: string + title: Display name + avatar_url: + type: string + title: Avatar Url events_before: type: array title: Events Before @@ -199,6 +228,17 @@ paths: title: Event allOf: - "$ref": "core-event-schema/room_event.json" + state: + type: object + title: Current state + additionalProperties: + type: array + title: Room State + items: + type: object + title: Event + allOf: + - "$ref": "core-event-schema/room_event.json" groups: type: object title: Groups From 23b2497743903d47a7c2b7ebc6e53d4527050eb8 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Dec 2015 15:31:35 +0000 Subject: [PATCH 07/18] Expand on where pagination tokens can be returned --- specification/modules/search.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/specification/modules/search.rst b/specification/modules/search.rst index f44bb585..8227128a 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -72,6 +72,11 @@ 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..next_batch`` +- ``search_categories..groups...next_batch`` + A server need not support pagination, even if there are more matching results. From 5e8bb34f362147b4a5e7056e425f55e6a6555beb Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Dec 2015 15:33:13 +0000 Subject: [PATCH 08/18] Change the results dict to a list --- api/client-server/search.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index a9eaa085..c0ca0016 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -160,10 +160,10 @@ paths: type: number description: Total number of results found results: - type: object + type: array title: Results description: Mapping of event_id to result. - additionalProperties: + items: type: object title: Result description: The result object. @@ -295,8 +295,8 @@ paths: } }, "count": 24, - "results": { - "$144429830826TWwbB:localhost": { + "results": [ + { "rank": 0.00424866, "result": { "age": 526228296, @@ -311,7 +311,7 @@ paths: "user_id": "@test:localhost" } } - } + ] } } } From ca7ef1b5363d788b9fd56743a37a669338b4b4c9 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 1 Dec 2015 15:34:25 +0000 Subject: [PATCH 09/18] Update Results description --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index c0ca0016..698c6448 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -162,7 +162,7 @@ paths: results: type: array title: Results - description: Mapping of event_id to result. + description: List of results in the requested order. items: type: object title: Result From fca8e5abe7dc5de607f8fecc1defa3285e6de2e0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 15:54:08 +0000 Subject: [PATCH 10/18] Add top level next_batch key to example --- api/client-server/search.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 698c6448..f19bf328 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -294,6 +294,7 @@ paths: } } }, + "next_batch": "5FdgFsd234dfgsdfFD", "count": 24, "results": [ { From 1ef9cc37e3e47192b28f48b0700ba51150fc7b4a Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 15:58:31 +0000 Subject: [PATCH 11/18] Typo --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index f19bf328..c7638915 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -242,7 +242,7 @@ paths: groups: type: object title: Groups - description: Any groups that were requseted. + description: Any groups that were requested. additionalProperties: type: object title: Group Key From c61ae86102b465e04de4e9c244b1c69fc91a558f Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:00:15 +0000 Subject: [PATCH 12/18] Specify behaviour if server does not support pagination --- specification/modules/search.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/modules/search.rst b/specification/modules/search.rst index 8227128a..5d820826 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -78,6 +78,7 @@ The currently supported locations for the ``next_batch`` token are: - ``search_categories..groups...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 From 2aef684e7e613a8d13e08cc44f819f1fb8f565a2 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:02:22 +0000 Subject: [PATCH 13/18] Add list of required supported groupings --- specification/modules/search.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/modules/search.rst b/specification/modules/search.rst index 5d820826..bef748c7 100644 --- a/specification/modules/search.rst +++ b/specification/modules/search.rst @@ -60,6 +60,12 @@ 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 ---------- From 118a6aa04022f0747b3ff54b5817af8d6d136203 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Mon, 7 Dec 2015 16:06:25 +0000 Subject: [PATCH 14/18] Reword groupings descriptions --- api/client-server/search.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index c7638915..894e5668 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -117,8 +117,8 @@ paths: type: object title: Groupings description: |- - Requests the server returns results with information - about how they fit into groups the specified groups. + Requests that the server partitions the result set + based on the provided list of keys. properties: group_by: type: array From 4967b092aa5198b8d51f261a7d2746b0a2e13f8b Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 13:37:32 +0000 Subject: [PATCH 15/18] Add description of state response key --- api/client-server/search.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index cd70af75..5985572b 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -230,6 +230,10 @@ paths: state: type: object title: Current state + description: |- + The current state for every room in the results. + This is included if the request had the the + ``include_state`` key set with a value of ``true``. additionalProperties: type: array title: Room State From 9c98c80bdec82226eee658041b5b5eb3a944cea4 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 14:32:01 +0000 Subject: [PATCH 16/18] Fix up filter description --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 5985572b..33570b0f 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -74,7 +74,7 @@ paths: type: object title: Filter description: |- - This has the same format as v2 filter API. + This takes a filter order_by: title: "Ordering" type: string From e1fda6b6b68548df47afa28a3ca06f3904844031 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 15:35:59 +0000 Subject: [PATCH 17/18] Remove double the --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 33570b0f..8552d615 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -232,7 +232,7 @@ paths: title: Current state description: |- The current state for every room in the results. - This is included if the request had the the + This is included if the request had the ``include_state`` key set with a value of ``true``. additionalProperties: type: array From 95255bcdf58f921b584516ea43f5a9e5a728eed0 Mon Sep 17 00:00:00 2001 From: Erik Johnston Date: Tue, 8 Dec 2015 16:02:55 +0000 Subject: [PATCH 18/18] Use rst not html --- api/client-server/search.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 8552d615..60329ce5 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -74,7 +74,7 @@ paths: type: object title: Filter description: |- - This takes a filter + This takes a `filter `_. order_by: title: "Ordering" type: string