feat(search): sortProperties on searchRequest

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: