From bed4174d86545cf28c85970f4ce0636902ff1157 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fredrik=20Adel=C3=B6w?= Date: Thu, 26 Feb 2026 15:51:59 +0100 Subject: [PATCH] docs: add design for predicate-based facets filtering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 Signed-off-by: Fredrik Adelöw --- ...02-26-facets-predicate-filtering-design.md | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/plans/2026-02-26-facets-predicate-filtering-design.md diff --git a/docs/plans/2026-02-26-facets-predicate-filtering-design.md b/docs/plans/2026-02-26-facets-predicate-filtering-design.md new file mode 100644 index 0000000000..9b086fb8df --- /dev/null +++ b/docs/plans/2026-02-26-facets-predicate-filtering-design.md @@ -0,0 +1,43 @@ +# Predicate-based filtering for the catalog facets endpoint + +## Problem + +The `/entity-facets` endpoint only supports the old filter query parameter syntax. The `queryEntities` endpoint already has a POST variant that accepts predicate-based filtering (`$all`, `$any`, `$not`, `$exists`, `$in`, `$contains`, `$hasPrefix`). We need the same capability for facets. + +## Approach + +Mirror the pattern from `queryEntities`: add a POST variant of `/entity-facets` that accepts a JSON body with a `query` predicate, while keeping the existing GET endpoint for backward compatibility. + +## Changes + +### Client types (`packages/catalog-client/src/types/api.ts`) + +Add optional `query: FilterPredicate` field to `GetEntityFacetsRequest`. When both `filter` and `query` are provided, the client converts `filter` to a predicate and merges them with `$all`. + +### Client implementation (`packages/catalog-client/src/CatalogClient.ts`) + +If `query` is present, route to a new private method that POSTs to `/entity-facets`. Otherwise, use existing GET endpoint. + +### OpenAPI schema (`plugins/catalog-backend/src/schema/openapi.yaml`) + +Add POST operation `QueryEntityFacetsByPredicate` on `/entity-facets` with JSON body containing required `facets` array and optional `query` (JsonObject). + +### Generated OpenAPI client + +Add `queryEntityFacetsByPredicate` method. + +### Backend internal types (`plugins/catalog-backend/src/catalog/types.ts`) + +Add optional `query?: FilterPredicate` to `EntityFacetsRequest`. + +### Backend router (`plugins/catalog-backend/src/service/createRouter.ts`) + +Add POST handler that validates the query predicate with zod and calls `entitiesCatalog.facets`. + +### DefaultEntitiesCatalog.facets + +Pass `query` through to `applyEntityFilterToQuery` alongside existing `filter`. + +### AuthorizedEntitiesCatalog.facets + +No changes needed — permission conditions merge into `filter` only.