feat: add ranking expression support for topN and bottomN filters

Author: AStaroverov

lib/model/common/src/drivers/pframe/query/query_common.ts

@@ -477,6 +477,56 @@ export interface ExprIsIn<I, T extends string | number> {
   set: T[];
 }
 
+// ============ Ranking Expression ============
+
+/**
+ * Ranking function kind.
+ *
+ * - `rank` - Standard rank: 1,2,2,4 (gaps after ties)
+ * - `denseRank` - Dense rank: 1,2,2,3 (no gaps)
+ * - `rowNumber` - Row number: 1,2,3,4 (no ties)
+ */
+export type RankingKind = "rank" | "denseRank" | "rowNumber";
+
+/**
+ * Ranking expression (window function).
+ *
+ * Assigns ranks to records within partitions based on explicit ordering.
+ * Each unique combination of axis values is a record.
+ * Records are grouped by `partitionBy` values, then ordered by `orderBy` expression
+ * within each partition. Ties are broken deterministically by axis values.
+ *
+ * **Output**: Numeric rank value.
+ *
+ * @template I - The expression type (for recursion)
+ * @template A - Axis selector type
+ * @template C - Column selector type
+ *
+ * @example
+ * // Rank rows by score descending
+ * { type: 'ranking', kind: 'rank', orderBy: scoreRef, ascending: false }
+ *
+ * // Dense rank within partitions
+ * {
+ *   type: 'ranking',
+ *   kind: 'denseRank',
+ *   orderBy: valueRef,
+ *   ascending: true,
+ *   partitionBy: [{ type: 'axis', id: 'sample' }]
+ * }
+ */
+export interface ExprRanking<I, A, C> {
+  type: "ranking";
+  /** Ranking function kind */
+  kind: RankingKind;
+  /** Expression to order by */
+  orderBy: I;
+  /** Ascending or descending order */
+  ascending?: boolean;
+  /** Partition specification — ranking is computed independently within each partition */
+  partitionBy?: (QueryAxisSelector<A> | QueryColumnSelector<C>)[];
+}
+
 // ============ Reference Expression Types ============
 
 /**

lib/model/common/src/drivers/pframe/query/query_data.ts

@@ -15,6 +15,7 @@ import type {
   ExprStringEquals,
   ExprStringRegex,
   ExprNumericUnary,
+  ExprRanking,
   QueryAxisSelector,
   QueryColumn,
   QuerySparseToDenseColumn,
@@ -118,6 +119,7 @@ export type DataQueryExpression =
   | ExprLogicalUnary<DataQueryExpression>
   | ExprLogicalVariadic<DataQueryExpression>
   | ExprIsIn<DataQueryExpression, string>
-  | ExprIsIn<DataQueryExpression, number>;
+  | ExprIsIn<DataQueryExpression, number>
+  | ExprRanking<DataQueryExpression, number, number>;
 
 export type DataQueryBooleanExpression = InferBooleanExpressionUnion<DataQueryExpression>;

lib/model/common/src/drivers/pframe/query/query_spec.ts

@@ -15,6 +15,7 @@ import type {
   ExprStringEquals,
   ExprStringRegex,
   ExprNumericUnary,
+  ExprRanking,
   QueryAxisSelector,
   QueryColumn,
   QuerySparseToDenseColumn,
@@ -137,6 +138,7 @@ export type SpecQueryExpression =
   | ExprLogicalUnary<SpecQueryExpression>
   | ExprLogicalVariadic<SpecQueryExpression>
   | ExprIsIn<SpecQueryExpression, string>
-  | ExprIsIn<SpecQueryExpression, number>;
+  | ExprIsIn<SpecQueryExpression, number>
+  | ExprRanking<SpecQueryExpression, SingleAxisSelector, PObjectId>;
 
 export type SpecQueryBooleanExpression = InferBooleanExpressionUnion<SpecQueryExpression>;

sdk/model/src/filters/converters/filterToQuery.ts

@@ -254,8 +254,29 @@ function leafToSpecQueryExpr<Leaf extends FilterSpecLeaf<string>>(
       };
 
     case "topN":
+      return {
+        type: "numericComparison",
+        operand: "le",
+        left: {
+          type: "ranking",
+          kind: "rank",
+          orderBy: resolveColumnRef(filter.column),
+          ascending: false,
+        },
+        right: { type: "constant", value: filter.n },
+      };
     case "bottomN":
-      throw new Error(`Filter type "${filter.type}" is not supported in query expressions`);
+      return {
+        type: "numericComparison",
+        operand: "le",
+        left: {
+          type: "ranking",
+          kind: "rank",
+          orderBy: resolveColumnRef(filter.column),
+          ascending: true,
+        },
+        right: { type: "constant", value: filter.n },
+      };
 
     case undefined:
       throw new Error("Filter type is undefined");

sdk/ui-vue/src/components/PlTableFilters/PlTableFiltersV2.vue

@@ -84,6 +84,8 @@ const supportedFilters = [
   "patternFuzzyContainSubsequence",
   "equal",
   "notEqual",
+  "topN",
+  "bottomN",
 ] as (typeof PlAdvancedFilterSupportedFilters)[number][];
 
 // getSuggestOptions - provide discrete values from column annotations