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

Libregraph extensions beyond MS Graph

subAggregations on aggregationOption / searchBucket: nested aggregations, evaluated in a single request
metricKind (sum / min / max / avg) on aggregationOption, with a scalar value on searchAggregation instead of buckets

Both are marked as libregraph extensions in the schema descriptions.

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

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.

The MS Graph token is opaque and varies by bucket type (hex-encoded for terms, range(...) for ranges, with different quoting rules). Rather than commit to that contract, omit the field and let clients construct filters directly from field + key (or the original range definition).

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 from PROPFIND (share indicators, lock state, processing state) afaict

Adds `subAggregations` as an optional array on both the request (`aggregationOption`) and response (`searchBucket`) sides of the search aggregation spec. Lets callers nest term aggregations, e.g. "group by audio.artist, then by audio.album", evaluated in a single request. Explicit libregraph extension beyond MS Graph. Bleve backend emulates via client-side fold over matched hits; OpenSearch would translate to native composite aggregations.

Adds `metricKind` (sum|min|max) to aggregationOption and mirrors `value` + `metricKind` on searchAggregation. When set, the aggregation returns a scalar rather than a bucket list; `size` and `bucketDefinition` are ignored. Libregraph extension, not present in MS Graph. Composable with subAggregations: a metric appears alongside term sub-aggregations inside a parent bucket's subAggregations list, just like in Elasticsearch. The most common use is "for each term bucket, compute a scalar over a numeric field in that bucket's docs", e.g. sum(audio.duration) per audio.album gives total album runtime. Intentionally omits avg/cardinality: avg needs split (sum, count) transport to merge correctly across shards and lands in a follow-up; cardinality is already derivable from a terms sub-aggregation's bucket count.

Adds `avg` as a permitted value on `aggregationOption.metricKind` and `searchAggregation.metricKind`. Distinct from sum/min/max because an average of two averages isn't mergeable: the backend has to carry (sum, count) internally per bucket and only collapse to the scalar `value` at the outermost merge. Wire shape stays symmetrical with sum/min/max: callers still just read `value` off the response; the (sum, count) bookkeeping is entirely service-side.

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

fix: copilot review findings

75917bf

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

fix: copilot findings

bb7d333

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

fix: some more improvements

68fdbaf

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

Draft

dschmidt added 4 commits August 13, 2026 00:40

docs(search): replace em dashes in KQL filter examples

d0dceba

This was referenced Aug 12, 2026

feat(search): sortProperties on searchRequest #61

Draft

feat(search): geohash grid aggregation option #62

Draft

Uh oh!

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

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

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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