feat: add search query endpoint with request examples by dschmidt · Pull Request #34 · opencloud-eu/libre-graph-api

dschmidt · 2026-04-10T09:50:55Z

Added a new search endpoint for querying resources with detailed request and response structures, including examples for various search scenarios.

Based on the MS Graph Search Api of course:

https://learn.microsoft.com/en-us/graph/api/resources/search-api-overview?view=graph-rest-1.0

I'm also willing to implement that endpoint: opencloud-eu/opencloud#3211

Libregraph extensions beyond MS Graph

Everything follows the MS Graph resource types under the same names, except these additions, which carry the @libre.graph. prefix like the other libregraph annotations:

@libre.graph.subAggregations on aggregationOption and searchBucket: nested aggregations, evaluated in a single request
@libre.graph.metricDefinition ({ kind }, kind being sum / min / max / avg) on aggregationOption, mirroring bucketDefinition, with a @libre.graph.metric ({ kind, value }) on searchAggregation instead of buckets

Example request with a sub-aggregation and a metric:

{
  "requests": [{
    "entityTypes": ["driveItem"],
    "query": { "queryString": "mediatype:audio" },
    "size": 0,
    "aggregations": [{
      "field": "audio.artist",
      "size": 10,
      "bucketDefinition": { "sortBy": "count", "isDescending": true },
      "@libre.graph.subAggregations": [
        { "field": "audio.album", "size": 5, "bucketDefinition": { "sortBy": "count" } },
        { "field": "audio.duration", "@libre.graph.metricDefinition": { "kind": "sum" } }
      ]
    }]
  }]
}

And the matching response:

{
  "value": [{
    "searchTerms": ["mediatype:audio"],
    "hitsContainers": [{
      "hits": [],
      "total": 142,
      "moreResultsAvailable": false,
      "aggregations": [{
        "field": "audio.artist",
        "buckets": [{
          "key": "Saxon",
          "count": 42,
          "aggregationFilterToken": "\"ǂǂ5361786f6e\"",
          "@libre.graph.subAggregations": [
            {
              "field": "audio.album",
              "buckets": [
                { "key": "Power & the Glory", "count": 26, "aggregationFilterToken": "\"ǂǂ506f77657220262074686520476c6f7279\"" },
                { "key": "Wheels of Steel", "count": 5, "aggregationFilterToken": "\"ǂǂ576865656c73206f6620537465656c\"" }
              ]
            },
            {
              "field": "audio.duration",
              "@libre.graph.metric": { "kind": "sum", "value": 16073000 }
            }
          ]
        }]
      }]
    }]
  }]
}

aggregationFilterToken

searchBucket.aggregationFilterToken uses the MS Graph encoding: terms buckets carry the key as a quoted, ǂǂ-prefixed hex token, range buckets a range(from, to) expression with min / max for open bounds and to="le" on an open upper bound, spelled exactly like MS Graph does (whitespace is optional when parsing). aggregationFilters only accept server-issued tokens in the {field}:{aggregationFilterToken} form, optionally combined with or(...). The filter matches the bucket key exactly and case-sensitively, so the narrowed result set is the set of matches counted in the bucket.

Copilot

Pull request overview

Adds an OpenAPI definition for a new beta search endpoint modeled after Microsoft Graph Search, including request/response schemas and multiple example payloads to document common search scenarios.

Changes:

Introduces POST /v1beta1/search/query with detailed description and request/response examples.
Adds search-related schemas (searchRequest, searchQuery, searchResponse, aggregation/bucket schemas) under components/schemas.
Wires the new endpoint to the new schemas via $ref to keep the spec structured.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

aduffeck · 2026-04-14T13:30:26Z

@dschmidt Since the search endpoint returns plain drive items I'm wondering how we would handle the additional information the results are currently being enriched with (see https://github.com/opencloud-eu/opencloud/blob/main/services/webdav/pkg/service/v0/search.go#L150-L263 for the current state).

Things like the tags could be derived from the arbitrary metadata (which currently isn't exposed afaict), but do you have an idea how we would handle the oc:has-preview (depends on a server-side list of supported mimetypes) and oc:favorite (depends on the user running the search and the favorites metadata which is not part of the arbitrary metadata) flags.

dschmidt · 2026-04-14T14:51:36Z

Very good questions, thanks!

I assume hasPreview could be expressed using the thumbnails relationship: https://learn.microsoft.com/en-us/graph/api/driveitem-list-thumbnails?view=graph-rest-1.0&tabs=http

favorite is trickier, as it's a user specific value and usually driveItems and all their data are not bound to a user.
Afaict MS Graph has nothing like that - the closest as a concept might be "following", c.f. https://learn.microsoft.com/en-us/graph/api/drive-list-following?view=graph-rest-1.0&tabs=http
But that does not seem to have a prop on the item. Which is very unhandy to work with.

Although this introduces user specific data to the driveItem, We could introduce a custom prop like @libre.graph.favorite or similar.
Maybe even @libre.graph.user.favorite to make it obvious it's user specific.

dschmidt · 2026-04-14T14:56:07Z

The thumbnails relationship is already in the spec, it might still need implementation tho 😅

dschmidt · 2026-04-14T17:52:16Z

Aha, I just realized the follow endpoints map to setting the favorite state... so just @libre.graph.following or @libre.graph.user.following on the driveItem?

If you agree, I can send another PR for that, to keep this one scoped

dschmidt · 2026-04-14T21:02:29Z

#37 👀

dschmidt · 2026-04-15T10:21:25Z

What's also potentially missing: short permissions/allowed actions without loading all shares

Not sure how we want to do that? Thoughts?

butonic · 2026-04-21T13:26:12Z

What's also potentially missing: short permissions/allowed actions without loading all shares

Not sure how we want to do that? Thoughts?

we introduced @libre.graph.permissions.roles.allowedValues and @libre.graph.permissions.actions.allowedValues to let the web ui build the sharing dialog.

see https://docs.opencloud.eu/docs/dev/server/apis/http/graph/permissions for what that looks like or just monitor your browsers network tab when opening the sharing dialog in the web ui.

Let me know if that covers what you have in mind

Adds an optional, `$select`-gated instance annotation on `driveItem` that carries the list of libre.graph actions the caller is allowed to perform on the item. Mirrors the annotation of the same name on the `/permissions` endpoint so clients (e.g. a sharing dialog in a search/listing UI) can get the effective-actions view inline without a separate round-trip per item. - Adds `@libre.graph.permissions.actions.allowedValues` to the `driveItem` schema, marked read-only and documented as only populated when requested. - Adds a reusable `driveItemSelect` component parameter with a narrow enum, following the same pattern as PR #38 (feat/download-url). When both land, the enum values merge. - Wires the new parameter to `GetDriveItem`. Rationale discussed in #34.

dschmidt · 2026-07-02T12:04:29Z

@butonic @aduffeck do we want to hold this back until the additional properties are spec'ed and merged or should we progress here independently? They are not hard to add later and merging this would unblock further work on the search service.

edit: Then again, they are "half approved". If we can settle on the me infix, we can just merge them, I guess?
edit:
As it might not have been completely obvious, I'm talking about

Adds an optional, `$select`-gated instance annotation on `driveItem` that carries the list of libre.graph actions the caller is allowed to perform on the item. Mirrors the annotation of the same name on the `/permissions` endpoint so clients (e.g. a sharing dialog in a search/listing UI) can get the effective-actions view inline without a separate round-trip per item. - Adds `@libre.graph.permissions.actions.allowedValues` to the `driveItem` schema, marked read-only and documented as only populated when requested. - Adds a reusable `driveItemSelect` component parameter with a narrow enum, following the same pattern as PR #38 (feat/download-url). When both land, the enum values merge. - Wires the new parameter to `GetDriveItem`. Rationale discussed in #34.

dschmidt · 2026-07-30T19:11:45Z

Implementations for the issues raised above:

graph: expose following state, tags and allowed actions on driveItems opencloud#3113
feat(search): honest has-preview prop and thumbnails relationship opencloud#3210

I think with those in place we can fully replace the WebDAV search...

dschmidt · 2026-08-09T16:07:04Z

I've found more missing properties that WebDAV PROPFIND provides but driveItems don't cover yet. Spec PRs:

Together with the already merged following/tags/allowedValues annotations these cover everything web currently reads - even from PROPFINDs - (share indicators, lock state, processing state) afaict

Generated from opencloud-eu/libre-graph-api#34 rebased onto main: POST /search/query with hits, aggregations and metrics.

butonic · 2026-10-01T15:21:46Z

+
+            For terms buckets the token is the key encoded as lowercase hex of
+            its UTF-8 bytes, prefixed with `ǂǂ` (U+01C2 twice) and wrapped in
+            double quotes, e.g. `"ǂǂ5361786f6e"` for the key


ms graph does the same weird thing to indicate hex

POST /v1beta1/search/query with searchRequest/searchQuery and the searchResponse/searchHitsContainer/searchHit result types, modeled on the MS Graph search API. The query string is KQL.

aggregationOption with bucketDefinition and manual ranges on the request, searchAggregation/searchBucket on the response, following the MS Graph resource types.

searchBucket carries a server-issued aggregationFilterToken, consumed verbatim through searchRequest.aggregationFilters to narrow a follow-up search to that bucket, matching exactly and case-sensitively. Same encoding MS Graph uses.

@libre.graph.metricDefinition (sum/min/max/avg) on aggregationOption and the @libre.graph.metric result on searchAggregation, the scalar counterpart of bucketDefinition/buckets. Libregraph extension.

@libre.graph.subAggregations nest aggregations within each bucket, on aggregationOption and searchBucket. Libregraph extension.

Libregraph extension: MS Graph search has no $expand and returns no thumbnails on search hits.

dschmidt requested review from butonic, dragotin, fschade, kulmann, micbar and rhafer as code owners April 10, 2026 09:50

dschmidt requested a review from Copilot April 11, 2026 06:56

Copilot started reviewing on behalf of dschmidt April 11, 2026 06:56 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

Comment thread api/openapi-spec/v1.0.yaml

Comment thread api/openapi-spec/v1.0.yaml

Comment thread api/openapi-spec/v1.0.yaml

Comment thread api/openapi-spec/v1.0.yaml Outdated

dschmidt requested a review from Copilot April 11, 2026 08:01

Copilot started reviewing on behalf of dschmidt April 11, 2026 08:02 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

Comment thread api/openapi-spec/v1.0.yaml Outdated

dschmidt requested a review from Copilot April 11, 2026 08:15

Copilot started reviewing on behalf of dschmidt April 11, 2026 08:16 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

dschmidt mentioned this pull request Apr 21, 2026

feat: add @libre.graph.permissions.actions.allowedValues to driveItem #39

Merged

dschmidt mentioned this pull request Jul 30, 2026

feat(search): graph search query endpoint with aggregations opencloud-eu/opencloud#3211

Open

dschmidt mentioned this pull request Aug 12, 2026

feat(search): sortProperties on searchRequest #61

Merged

dschmidt mentioned this pull request Aug 12, 2026

feat(search): geohash grid aggregation option #62

Merged

dschmidt force-pushed the feat/search branch from d0dceba to 12d8885 Compare September 1, 2026 10:13

dschmidt mentioned this pull request Sep 7, 2026

refactor: graph listing opencloud-eu/web#3321

Draft

3 of 7 tasks

dschmidt force-pushed the feat/search branch from 12d8885 to 8f05719 Compare September 7, 2026 17:58

dschmidt force-pushed the feat/search branch 2 times, most recently from ac4bd1d to fb2b5d7 Compare October 1, 2026 07:35

fschade approved these changes Oct 1, 2026

View reviewed changes

butonic reviewed Oct 1, 2026

View reviewed changes

butonic approved these changes Oct 1, 2026

View reviewed changes

dschmidt force-pushed the feat/search branch from fb2b5d7 to d6e08e4 Compare October 1, 2026 15:57

dschmidt added 6 commits October 1, 2026 17:58

feat(search): add the search query endpoint

eb0234e

POST /v1beta1/search/query with searchRequest/searchQuery and the searchResponse/searchHitsContainer/searchHit result types, modeled on the MS Graph search API. The query string is KQL.

feat(search): MS Graph aggregations on the search query

da6a67f

aggregationOption with bucketDefinition and manual ranges on the request, searchAggregation/searchBucket on the response, following the MS Graph resource types.

feat(search): libregraph metric aggregations

7282976

@libre.graph.metricDefinition (sum/min/max/avg) on aggregationOption and the @libre.graph.metric result on searchAggregation, the scalar counterpart of bucketDefinition/buckets. Libregraph extension.

feat(search): libregraph sub-aggregations

c11b6bc

@libre.graph.subAggregations nest aggregations within each bucket, on aggregationOption and searchBucket. Libregraph extension.

feat(search): allow $expand=thumbnails on the search query

d6e08e4

Libregraph extension: MS Graph search has no $expand and returns no thumbnails on search hits.

fschade merged commit 5566217 into main Oct 1, 2026
4 checks passed

fschade deleted the feat/search branch October 1, 2026 16:33

Conversation

dschmidt commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Libregraph extensions beyond MS Graph

aggregationFilterToken

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

aduffeck commented Apr 14, 2026

Uh oh!

dschmidt commented Apr 14, 2026

Uh oh!

dschmidt commented Apr 14, 2026

Uh oh!

dschmidt commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dschmidt commented Apr 14, 2026

Uh oh!

dschmidt commented Apr 15, 2026

Uh oh!

butonic commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dschmidt commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dschmidt commented Jul 30, 2026

Uh oh!

dschmidt commented Aug 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

butonic Oct 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dschmidt commented Apr 10, 2026 •

edited

Loading

dschmidt commented Apr 14, 2026 •

edited

Loading

butonic commented Apr 21, 2026 •

edited

Loading

dschmidt commented Jul 2, 2026 •

edited

Loading

dschmidt commented Aug 9, 2026 •

edited

Loading