Merge pull request #169 from matrix-org/erikj/search_yet_agian
Search: Document event context, groups and orders.
This commit is contained in:
Erik Johnston
commit
c96848d1bc
2 changed files with 242 additions and 14 deletions
|
|
@ -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"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
]
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue