diff --git a/.changeset/rich-ducks-ring.md b/.changeset/rich-ducks-ring.md new file mode 100644 index 0000000000..0ba4b86961 --- /dev/null +++ b/.changeset/rich-ducks-ring.md @@ -0,0 +1,15 @@ +--- +'@backstage/catalog-client': minor +'@backstage/plugin-catalog-backend': minor +--- + +New POST /entities/by-query endpoint + +- Supports predicate-based entity filtering using advanced query operators ($all, $any, $in, $not, $exists) +- Enables complex nested queries for more powerful entity searches +- Provides cursor-based pagination for efficient result traversal + +Updated Catalog Client + +- Enhanced queryEntities() method to automatically route requests to POST endpoint when query predicate is provided +- Validates mutual exclusivity between filter (legacy) and query (predicate-based) parameters diff --git a/packages/catalog-client/report.api.md b/packages/catalog-client/report.api.md index 58fc4bc8a1..10e5b5d684 100644 --- a/packages/catalog-client/report.api.md +++ b/packages/catalog-client/report.api.md @@ -231,6 +231,56 @@ export type EntityOrderQuery = order: 'asc' | 'desc'; }>; +// @public +export type EntityPredicate = + | EntityPredicateAll + | EntityPredicateAny + | EntityPredicateNot + | boolean + | number + | string + | { + [key: string]: EntityPredicateValue; + }; + +// @public +export interface EntityPredicateAll { + // (undocumented) + $all: Array; +} + +// @public +export interface EntityPredicateAny { + // (undocumented) + $any: Array; +} + +// @public +export interface EntityPredicateExists { + // (undocumented) + $exists: boolean; +} + +// @public +export interface EntityPredicateIn { + // (undocumented) + $in: Array; +} + +// @public +export interface EntityPredicateNot { + // (undocumented) + $not: EntityPredicate; +} + +// @public +export type EntityPredicateValue = + | EntityPredicateExists + | EntityPredicateIn + | boolean + | number + | string; + // @public export interface GetEntitiesByRefsRequest { entityRefs: string[]; @@ -320,6 +370,7 @@ export type QueryEntitiesInitialRequest = { limit?: number; offset?: number; filter?: EntityFilterQuery; + query?: EntityPredicate; orderFields?: EntityOrderQuery; fullTextFilter?: { term: string;