diff --git a/api/openapi-spec/v1.0.yaml b/api/openapi-spec/v1.0.yaml index 829ffff..be9d582 100644 --- a/api/openapi-spec/v1.0.yaml +++ b/api/openapi-spec/v1.0.yaml @@ -4692,6 +4692,8 @@ paths: search UIs or computing statistics about the result set. The query string uses KQL (Keyword Query Language) syntax for filtering. + Results are sorted by relevance unless the request specifies + `sortProperties`. Modeled on the MS Graph search query endpoint (https://learn.microsoft.com/en-us/graph/api/search-query). Request and @@ -4795,6 +4797,19 @@ paths: size: 25 aggregationFilters: - "audio.artist:\"ǂǂ5361786f6e\"" + search with sorting: + summary: Newest photos first + value: + requests: + - entityTypes: + - driveItem + query: + queryString: "mediatype:photo" + from: 0 + size: 25 + sortProperties: + - name: photo.takenDateTime + isDescending: true responses: '200': description: OK @@ -6762,6 +6777,17 @@ components: `invalidRequest`. items: type: string + sortProperties: + type: array + description: | + Contains the ordered collection of fields to sort the results on, + primary sort key first. At most 5 sort properties. If absent, the + results are sorted by relevance. See `sortProperty.name` for the + set of sortable fields. Ties are broken by relevance, and results + missing the sort property are placed last. Optional. + maxItems: 5 + items: + $ref: '#/components/schemas/sortProperty' searchQuery: type: object description: | @@ -6925,6 +6951,33 @@ components: The value is always a string. Numeric bounds must be provided as their string representation (e.g. `"2000"`). Date bounds must use the `YYYY-MM-DDTHH:mm:ssZ` format. Optional if `from` is provided. + sortProperty: + type: object + description: | + Indicates the order to sort search results in. Follows the + [MS Graph sortProperty](https://learn.microsoft.com/en-us/graph/api/resources/sortproperty) + resource type. + required: + - name + properties: + name: + type: string + description: | + The name of the property to sort the search results by. Required. + + Sortable are the scalar search fields of the search hit's + resource: `name`, `size`, `lastModifiedDateTime`, `mimeType` and + the scalar facet properties such as `photo.takenDateTime`, + `photo.iso`, `audio.artist`, `audio.year` or `image.width`. + Strings sort lexicographically, numbers and dates by value. + Multivalued properties (e.g. `@libre.graph.tags`) and unknown + properties are rejected with `invalidRequest`. + isDescending: + type: boolean + description: | + Set to `true` to specify the sort order as descending. Optional, + defaults to `false` (ascending). + default: false searchResponse: type: object description: | @@ -6953,7 +7006,9 @@ components: properties: hits: type: array - description: A collection of the search results. + description: | + A collection of the search results, ordered by relevance or, when + the request specifies `sortProperties`, by those properties. items: $ref: '#/components/schemas/searchHit' total: