archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Search: Document event context, groups and orders.
pull/977/head
Erik Johnston 9 years ago
parent 7b63c042fb 95255bcdf5
commit c96848d1bc
2 changed files with 242 additions and 14 deletions
Show Stats Download Patch File Download Diff File

209
api/client-server/search.yaml
Unescape Escape View File

@ -39,6 +39,14 @@ paths:
], ],
"search_term": "martians and men" "search_term": "martians and men"
} }
},
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
} }
} }
properties: properties:
@ -66,8 +74,66 @@ paths:
type: object type: object
title: Filter title: Filter
description: |- description: |-
The filter to apply to search results. This takes a `filter <https://matrix.org/docs/spec/%CLIENT_RELEASE_LABEL%/client_server.html#filtering>`_.
This has the same format as 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.
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
description: |-
Requests that the server partitions the result set
based on the provided list of keys.
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_term"]
required: ["search_categories"] required: ["search_categories"]
responses: responses:
@ -93,10 +159,10 @@ paths:
type: number type: number
description: Total number of results found description: Total number of results found
results: results:
type: object type: array
title: Results title: Results
description: Mapping of event_id to result. description: List of results in the requested order.
additionalProperties: items:
type: object type: object
title: Result title: Result
description: The result object. description: The result object.
@ -107,24 +173,139 @@ paths:
this result matches the search. Higher is this result matches the search. Higher is
closer. closer.
result: result:
type: object type: object
title: Event title: Event
description: The event that matched. description: The event that matched.
allOf: allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml" - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
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
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
description: Events just before the result.
items:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
events_after:
type: array
title: Events After
description: Events just after the result.
items:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: object
title: Current state
description: |-
The current state for every room in the results.
This is included if the request had the
``include_state`` key set with a value of ``true``.
additionalProperties:
type: array
title: Room State
items:
type: object
title: Event
allOf:
- "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
groups:
type: object
title: Groups
description: Any groups that were requested.
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 in the group, 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
next_batch:
type: string
title: Next Batch
description: |-
Token that can be used to get the next batch of
results, if exists.
examples: examples:
application/json: |- application/json: |-
{ {
"search_categories": { "search_categories": {
"room_events": { "room_events": {
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"order": 1,
"next_batch": "BdgFsdfHSf-dsFD",
"results": [
"$144429830826TWwbB:localhost"
]
}
}
},
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 24, "count": 24,
"results": { "results": [
"$144429830826TWwbB:localhost": { {
"rank": 0.00424866, "rank": 0.00424866,
"result": { "result": {
"age": 526228296, "age": 526228296,
"content": { "content": {
"body": "Test content", "body": "Test content martians and men",
"msgtype": "m.text" "msgtype": "m.text"
}, },
"event_id": "$144429830826TWwbB:localhost", "event_id": "$144429830826TWwbB:localhost",
@ -134,7 +315,7 @@ paths:
"sender": "@test:localhost" "sender": "@test:localhost"
} }
} }
} ]
} }
} }
} }

47
specification/modules/search.rst
Unescape Escape View File

@ -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 the search query matching 1000s of results and the server truncating the
response. 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 Security considerations
----------------------- -----------------------
The server must only return results that the user has permission to see. The server must only return results that the user has permission to see.

Write Preview
Loading…
Cancel
Save