From 51e23eb73e5480c2b4042d9d7a9eb2ff7c4a3979 Mon Sep 17 00:00:00 2001
From: Nilay1999 <nilayparmar19@gmail.com>
Date: Thu, 12 Feb 2026 00:32:09 +0530
Subject: [PATCH] =?UTF-8?q?chore:=20=F0=9F=93=9D=20add=20changeset=20for?=
 =?UTF-8?q?=20predicate-based=20entity=20querying?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Nilay1999 <nilayparmar19@gmail.com>
---
 .changeset/rich-ducks-ring.md         | 15 ++++++++
 packages/catalog-client/report.api.md | 51 +++++++++++++++++++++++++++
 2 files changed, 66 insertions(+)
 create mode 100644 .changeset/rich-ducks-ring.md

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<EntityPredicate>;
+}
+
+// @public
+export interface EntityPredicateAny {
+  // (undocumented)
+  $any: Array<EntityPredicate>;
+}
+
+// @public
+export interface EntityPredicateExists {
+  // (undocumented)
+  $exists: boolean;
+}
+
+// @public
+export interface EntityPredicateIn {
+  // (undocumented)
+  $in: Array<string | number | boolean>;
+}
+
+// @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;