@sisense/sdk-data 2.12.0 → 2.14.0

package/dist/dimensional-model/filters/factory.d.ts

@@ -721,6 +721,146 @@ export declare const topRanking: (attribute: Attribute, measure: Measure, count:
  * @returns A filter instance
  */
 export declare const bottomRanking: (attribute: Attribute, measure: Measure, count: number, config?: BaseFilterConfig) => Filter;
+/**
+ * Creates a filter that returns the top N values of the last dimension,
+ * independently for each unique combination of all preceding dimensions.
+ *
+ * This filter applies ranking within groups rather than globally. It shows the top N values
+ * of the rightmost dimension for every unique combination of the other dimensions to its left.
+ * The order of dimensions in your query determines the grouping behavior.
+ *
+ * **Key Differences from {@link topRanking}:**
+ * - `topRanking`: Filters a specific dimension globally (you specify which dimension)
+ * - `measureTopRanking`: Always filters the last/rightmost dimension, grouped by all others
+ *
+ * **How it works:**
+ * - With 1 dimension: Returns the top N values of that dimension
+ * - With 2+ dimensions: Returns the top N values of the LAST dimension for each combination of the others
+ *
+ * @example
+ * **Example 1: Single dimension (equivalent to topRanking) - Query with one dimension [Category]**
+ * ```ts
+ * // Returns top 5 Categories by total revenue
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ * Result: 5 categories (e.g., Cell Phones, Computers, TVs, etc.)
+ *
+ * This produces the same result as:
+ * ```ts
+ * filterFactory.topRanking(
+ *   DM.Commerce.Category,
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ *
+ * **Note:** With only one dimension, there are no groups to rank within,
+ * so the behavior is identical to `topRanking`.
+ *
+ * @example
+ * **Example 2: Two dimensions - Query with dimensions [Gender, Category]**
+ * ```ts
+ * // Returns top 2 Categories for each Gender
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 2 categories each = 6 rows
+ * - Male: Top 2 categories by revenue
+ * - Female: Top 2 categories by revenue
+ * - Unspecified: Top 2 categories by revenue
+ *
+ * @example
+ * **Example 3: Three dimensions - Query with dimensions [Gender, Age Range, Category]**
+ * ```ts
+ * // Returns top 2 Categories for each (Gender, Age Range) combination
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 7 age ranges × 2 categories per combination = ~42 rows
+ *
+ * @param measure - Base measure to rank by
+ * @param count - Number of items to return per group (applies to the last dimension)
+ * @param config - Optional configuration for the filter
+ * @returns A filter instance
+ */
+export declare const measureTopRanking: (measure: BaseMeasure, count: number, config?: BaseFilterConfig) => Filter;
+/**
+ * Creates a filter that returns the bottom N values of the last dimension,
+ * independently for each unique combination of all preceding dimensions.
+ *
+ * This filter applies ranking within groups rather than globally. It shows the bottom N values
+ * of the rightmost dimension for every unique combination of the other dimensions to its left.
+ * The order of dimensions in your query determines the grouping behavior.
+ *
+ * **Key Differences from {@link bottomRanking}:**
+ * - `bottomRanking`: Filters a specific dimension globally (you specify which dimension)
+ * - `measureBottomRanking`: Always filters the last/rightmost dimension, grouped by all others
+ *
+ * **How it works:**
+ * - With 1 dimension: Returns the bottom N values of that dimension
+ * - With 2+ dimensions: Returns the bottom N values of the LAST dimension for each combination of the others
+ *
+ * @example
+ * **Example 1: Single dimension (equivalent to bottomRanking) - Query with one dimension [Category]**
+ * ```ts
+ * // Returns bottom 5 Categories by revenue
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ * Result: 5 categories with lowest revenue (e.g., Accessories, Cables, etc.)
+ *
+ * This produces the same result as:
+ * ```ts
+ * filterFactory.bottomRanking(
+ *   DM.Commerce.Category,
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ *
+ * **Note:** With only one dimension, there are no groups to rank within,
+ * so the behavior is identical to `bottomRanking`.
+ *
+ * @example
+ * **Example 2: Two dimensions - Query with dimensions [Gender, Category]**
+ * ```ts
+ * // Returns bottom 2 Categories for each Gender
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 2 categories each = 6 rows
+ * - Male: Bottom 2 categories by revenue
+ * - Female: Bottom 2 categories by revenue
+ * - Unspecified: Bottom 2 categories by revenue
+ *
+ * @example
+ * **Example 3: Three dimensions - Query with dimensions [Gender, Age Range, Category]**
+ * ```ts
+ * // Returns bottom 2 Categories for each (Gender, Age Range) combination
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 7 age ranges × 2 categories per combination = ~42 rows
+ *
+ * @param measure - Base measure to rank by
+ * @param count - Number of items to return per group (applies to the last dimension)
+ * @param config - Optional configuration for the filter
+ * @returns A filter instance
+ */
+export declare const measureBottomRanking: (measure: BaseMeasure, count: number, config?: BaseFilterConfig) => Filter;
 /**
  * Creates a filter that contains a list of dependent/cascading filters,
  * where each filter depends on the results or state of the previous ones in the array.

package/dist/dimensional-model/filters/factory.js

@@ -2,7 +2,7 @@
 /* eslint-disable max-params */
 /* eslint-disable @typescript-eslint/no-shadow */
 import { withComposeCodeForFilter, withComposeCodeForFilterRelations, } from '../compose-code-utils.js';
-import { CascadingFilter, CustomFilter, DateOperators, DateRangeFilter, ExcludeFilter, LogicalAttributeFilter, LogicalOperators, MeasureFilter, MembersFilter, NumericFilter, NumericOperators, RankingFilter, RankingOperators, RelativeDateFilter, TextFilter, TextOperators, } from './filters.js';
+import { CascadingFilter, CustomFilter, DateOperators, DateRangeFilter, ExcludeFilter, LogicalAttributeFilter, LogicalOperators, MeasureFilter, MeasureRankingFilter, MembersFilter, NumericFilter, NumericOperators, RankingFilter, RankingOperators, RelativeDateFilter, TextFilter, TextOperators, } from './filters.js';
 // LOGICAL FILTERS
 /**
  * Creates a filter representing the union of multiple filters on the same attribute. The resulting
@@ -746,19 +746,146 @@ export const topRanking = withComposeCodeForFilter((attribute, measure, count, c
  * @returns A filter instance
  */
 export const bottomRanking = withComposeCodeForFilter((attribute, measure, count, config) => new RankingFilter(attribute, measure, RankingOperators.Bottom, count, config), 'bottomRanking');
-const relate = (node) => {
-    if (Array.isArray(node)) {
-        const [first, ...rest] = node;
-        return rest.length === 0
-            ? relate(first)
-            : {
-                operator: 'AND',
-                left: relate(first),
-                right: relate(rest),
-            };
-    }
-    return node;
-};
+/**
+ * Creates a filter that returns the top N values of the last dimension,
+ * independently for each unique combination of all preceding dimensions.
+ *
+ * This filter applies ranking within groups rather than globally. It shows the top N values
+ * of the rightmost dimension for every unique combination of the other dimensions to its left.
+ * The order of dimensions in your query determines the grouping behavior.
+ *
+ * **Key Differences from {@link topRanking}:**
+ * - `topRanking`: Filters a specific dimension globally (you specify which dimension)
+ * - `measureTopRanking`: Always filters the last/rightmost dimension, grouped by all others
+ *
+ * **How it works:**
+ * - With 1 dimension: Returns the top N values of that dimension
+ * - With 2+ dimensions: Returns the top N values of the LAST dimension for each combination of the others
+ *
+ * @example
+ * **Example 1: Single dimension (equivalent to topRanking) - Query with one dimension [Category]**
+ * ```ts
+ * // Returns top 5 Categories by total revenue
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ * Result: 5 categories (e.g., Cell Phones, Computers, TVs, etc.)
+ *
+ * This produces the same result as:
+ * ```ts
+ * filterFactory.topRanking(
+ *   DM.Commerce.Category,
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ *
+ * **Note:** With only one dimension, there are no groups to rank within,
+ * so the behavior is identical to `topRanking`.
+ *
+ * @example
+ * **Example 2: Two dimensions - Query with dimensions [Gender, Category]**
+ * ```ts
+ * // Returns top 2 Categories for each Gender
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 2 categories each = 6 rows
+ * - Male: Top 2 categories by revenue
+ * - Female: Top 2 categories by revenue
+ * - Unspecified: Top 2 categories by revenue
+ *
+ * @example
+ * **Example 3: Three dimensions - Query with dimensions [Gender, Age Range, Category]**
+ * ```ts
+ * // Returns top 2 Categories for each (Gender, Age Range) combination
+ * filterFactory.measureTopRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 7 age ranges × 2 categories per combination = ~42 rows
+ *
+ * @param measure - Base measure to rank by
+ * @param count - Number of items to return per group (applies to the last dimension)
+ * @param config - Optional configuration for the filter
+ * @returns A filter instance
+ */
+export const measureTopRanking = withComposeCodeForFilter((measure, count, config) => new MeasureRankingFilter(measure, RankingOperators.Top, count, config), 'measureTopRanking');
+/**
+ * Creates a filter that returns the bottom N values of the last dimension,
+ * independently for each unique combination of all preceding dimensions.
+ *
+ * This filter applies ranking within groups rather than globally. It shows the bottom N values
+ * of the rightmost dimension for every unique combination of the other dimensions to its left.
+ * The order of dimensions in your query determines the grouping behavior.
+ *
+ * **Key Differences from {@link bottomRanking}:**
+ * - `bottomRanking`: Filters a specific dimension globally (you specify which dimension)
+ * - `measureBottomRanking`: Always filters the last/rightmost dimension, grouped by all others
+ *
+ * **How it works:**
+ * - With 1 dimension: Returns the bottom N values of that dimension
+ * - With 2+ dimensions: Returns the bottom N values of the LAST dimension for each combination of the others
+ *
+ * @example
+ * **Example 1: Single dimension (equivalent to bottomRanking) - Query with one dimension [Category]**
+ * ```ts
+ * // Returns bottom 5 Categories by revenue
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ * Result: 5 categories with lowest revenue (e.g., Accessories, Cables, etc.)
+ *
+ * This produces the same result as:
+ * ```ts
+ * filterFactory.bottomRanking(
+ *   DM.Commerce.Category,
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   5
+ * )
+ * ```
+ *
+ * **Note:** With only one dimension, there are no groups to rank within,
+ * so the behavior is identical to `bottomRanking`.
+ *
+ * @example
+ * **Example 2: Two dimensions - Query with dimensions [Gender, Category]**
+ * ```ts
+ * // Returns bottom 2 Categories for each Gender
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 2 categories each = 6 rows
+ * - Male: Bottom 2 categories by revenue
+ * - Female: Bottom 2 categories by revenue
+ * - Unspecified: Bottom 2 categories by revenue
+ *
+ * @example
+ * **Example 3: Three dimensions - Query with dimensions [Gender, Age Range, Category]**
+ * ```ts
+ * // Returns bottom 2 Categories for each (Gender, Age Range) combination
+ * filterFactory.measureBottomRanking(
+ *   measureFactory.sum(DM.Commerce.Revenue),
+ *   2
+ * )
+ * ```
+ * Result: 3 genders × 7 age ranges × 2 categories per combination = ~42 rows
+ *
+ * @param measure - Base measure to rank by
+ * @param count - Number of items to return per group (applies to the last dimension)
+ * @param config - Optional configuration for the filter
+ * @returns A filter instance
+ */
+export const measureBottomRanking = withComposeCodeForFilter((measure, count, config) => new MeasureRankingFilter(measure, RankingOperators.Bottom, count, config), 'measureBottomRanking');
 // CASCADING FILTERS
 /**
  * Creates a filter that contains a list of dependent/cascading filters,
@@ -815,6 +942,26 @@ export const cascading = withComposeCodeForFilter((filters, config) => new Casca
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export var logic;
 (function (logic) {
+    /**
+     * Relates a filter or filter relations node
+     *
+     * @param node - Filter or filter relations node
+     * @returns Related filter or filter relations node
+     * @internal
+     */
+    const relate = (node) => {
+        if (Array.isArray(node)) {
+            const [first, ...rest] = node;
+            return rest.length === 0
+                ? relate(first)
+                : {
+                    operator: 'AND',
+                    left: relate(first),
+                    right: relate(rest),
+                };
+        }
+        return node;
+    };
     /**
      * Creates an 'AND' filter relations
      *

package/dist/dimensional-model/filters/filters.d.ts

@@ -1,5 +1,5 @@
 import { DimensionalElement } from '../base.js';
-import { Attribute, BaseFilterConfig, CompleteBaseFilterConfig, CompleteMembersFilterConfig, Filter, LevelAttribute, Measure, MembersFilterConfig } from '../interfaces.js';
+import { Attribute, BaseFilterConfig, BaseMeasure, CompleteBaseFilterConfig, CompleteMembersFilterConfig, Filter, LevelAttribute, Measure, MembersFilterConfig } from '../interfaces.js';
 import { AnyObject, JSONObject } from '../types.js';
 /**
  * Different text operators that can be used with text filters
@@ -70,6 +70,7 @@ export declare const FilterTypes: {
     readonly exclude: "exclude";
     readonly measure: "measure";
     readonly ranking: "ranking";
+    readonly measureRanking: "measure-ranking";
     readonly text: "text";
     readonly numeric: "numeric";
     readonly dateRange: "dateRange";
@@ -298,6 +299,32 @@ export declare class RankingFilter extends AbstractFilter {
      */
     filterJaql(): any;
 }
+/**
+ * @internal
+ */
+export declare class MeasureRankingFilter extends AbstractFilter {
+    /**
+     * @internal
+     */
+    readonly __serializable: string;
+    count: number;
+    operator: string;
+    measure: BaseMeasure;
+    constructor(measure: BaseMeasure, operator: string, count: number, config?: BaseFilterConfig, composeCode?: string);
+    /**
+     * gets the element's ID
+     */
+    get id(): string;
+    /**
+     * Gets a serializable representation of the element
+     */
+    serialize(): JSONObject;
+    /**
+     * Gets JAQL representing this Filter instance
+     */
+    filterJaql(): any;
+    jaql(nested?: boolean | undefined): any;
+}
 /**
  * @internal
  */
@@ -427,6 +454,13 @@ export declare function isNumericFilter(filter: Filter & AnyObject): filter is N
  * @internal
  */
 export declare function isRankingFilter(filter: Filter & AnyObject): filter is RankingFilter;
+/**
+ * Checks if a filter is a MeasureRankingFilter.
+ *
+ * @param filter - The filter to check.
+ * @internal
+ */
+export declare function isMeasureRankingFilter(filter: Filter & AnyObject): filter is MeasureRankingFilter;
 /**
  * Checks if a filter is a MeasureFilter.
  *

package/dist/dimensional-model/filters/filters.js

@@ -77,6 +77,7 @@ export const FilterTypes = {
     exclude: 'exclude',
     measure: 'measure',
     ranking: 'ranking',
+    measureRanking: 'measure-ranking',
     text: 'text',
     numeric: 'numeric',
     dateRange: 'dateRange',
@@ -517,6 +518,59 @@ export class RankingFilter extends AbstractFilter {
         return result;
     }
 }
+/**
+ * @internal
+ */
+export class MeasureRankingFilter extends AbstractFilter {
+    constructor(measure, operator, count, config, composeCode) {
+        super(measure.attribute, FilterTypes.measureRanking, config, composeCode);
+        /**
+         * @internal
+         */
+        this.__serializable = 'MeasureRankingFilter';
+        this.count = count;
+        this.operator = operator;
+        this.measure = measure;
+    }
+    /**
+     * gets the element's ID
+     */
+    get id() {
+        return `${this.operator}_${this.count}_measure_${this.measure.id}`;
+    }
+    /**
+     * Gets a serializable representation of the element
+     */
+    serialize() {
+        const result = super.serialize();
+        result.measure = this.measure.serialize();
+        result.count = this.count;
+        result.operator = this.operator;
+        return result;
+    }
+    /**
+     * Gets JAQL representing this Filter instance
+     */
+    filterJaql() {
+        const result = {};
+        result[this.operator] = this.count;
+        return result;
+    }
+    jaql(nested) {
+        if (this.config.disabled) {
+            return AbstractFilter.disabledJaql(nested);
+        }
+        const result = super.jaql(nested);
+        if (isDimensionalBaseMeasure(this.measure)) {
+            Object.entries(this.measure.jaql().jaql).forEach(([key, value]) => {
+                result.jaql[key] = value;
+            });
+        }
+        // Add type: 'measure' for measure-based filters
+        result.jaql.type = 'measure';
+        return result;
+    }
+}
 /**
  * @internal
  */
@@ -734,6 +788,15 @@ export function isNumericFilter(filter) {
 export function isRankingFilter(filter) {
     return filter && filter.__serializable === 'RankingFilter';
 }
+/**
+ * Checks if a filter is a MeasureRankingFilter.
+ *
+ * @param filter - The filter to check.
+ * @internal
+ */
+export function isMeasureRankingFilter(filter) {
+    return filter && filter.__serializable === 'MeasureRankingFilter';
+}
 /**
  * Checks if a filter is a MeasureFilter.
  *
@@ -805,31 +868,24 @@ export function createFilter(json) {
     switch (json.filterType) {
         case FilterTypes.logicalAttribute:
             return new LogicalAttributeFilter(json.filters.map((f) => createFilter(f)), json.operator);
-            break;
         case FilterTypes.members:
             return new MembersFilter(create(json.attribute), json.members);
-            break;
         case FilterTypes.exclude:
             return new ExcludeFilter(createFilter(json.filter), json.input && createFilter(json.input));
-            break;
         case FilterTypes.measure:
             return new MeasureFilter(create(json.attribute), create(json.measure), json.operatorA, json.valueA, json.operatorB, json.valueB);
-            break;
         case FilterTypes.ranking:
             return new RankingFilter(create(json.attribute), create(json.measure), json.operator, json.count);
-            break;
+        case FilterTypes.measureRanking:
+            return new MeasureRankingFilter(create(json.measure), json.operator, json.count);
         case FilterTypes.numeric:
             return new NumericFilter(create(json.attribute), json.operatorA, json.valueA, json.operatorB, json.valueB);
-            break;
         case FilterTypes.text:
             return new TextFilter(create(json.attribute), json.operatorA, json.valueA);
-            break;
         case FilterTypes.relativeDate:
             return new RelativeDateFilter(create(json.attribute), json.offset, json.count, json.operator, json.anchor);
-            break;
         case FilterTypes.dateRange:
             return new DateRangeFilter(create(json.attribute), json.valueA, json.valueB);
-            break;
     }
     throw new TranslatableError('errors.filter.unsupportedType', {
         filterType: json.filterType,

package/dist/dimensional-model/filters/utils/condition-filter-util.js

@@ -181,6 +181,10 @@ export const createMeasureFilterFromConditionFilterJaql = (measure, conditionFil
             return filterFactory.measureBetween(measure, conditionFilterJaql.from, conditionFilterJaql.to, { guid });
         case ConditionFilterType.IS_NOT_BETWEEN:
             return filterFactory.exclude(filterFactory.measureBetween(measure, (_a = conditionFilterJaql.exclude) === null || _a === void 0 ? void 0 : _a.from, (_b = conditionFilterJaql.exclude) === null || _b === void 0 ? void 0 : _b.to, { guid }), undefined, { guid });
+        case ConditionFilterType.TOP:
+            return filterFactory.measureTopRanking(measure, conditionFilterJaql[ConditionFilterType.TOP], { guid });
+        case ConditionFilterType.BOTTOM:
+            return filterFactory.measureBottomRanking(measure, conditionFilterJaql[ConditionFilterType.BOTTOM], { guid });
     }
     throw new TranslatableError('errors.filter.unsupportedConditionFilter', {
         filter: JSON.stringify(conditionFilterJaql),

package/dist/dimensional-model/interfaces.d.ts

@@ -498,6 +498,11 @@ export interface PivotAttribute {
     attribute: Attribute;
     includeSubTotals?: boolean;
     sort?: PivotRowsSort;
+    /**
+     * Custom name to override the default attribute name in pivot table headers.
+     * If provided, this will be used as the display title in the pivot table.
+     */
+    name?: string;
 }
 /**
  * Runs type guard check for PivotAttribute.