import { type AllTimeGranularity, type DateAttributeGranularity } from "../../base/dateGranularities.js"; import { type Identifier, type ObjRef, type ObjRefInScope } from "../../objRef/index.js"; /** * Determines how date filters should treat empty values. * * @remarks * - `"include"`: include empty values together with selected date range * - `"exclude"`: exclude empty values from results * - `"only"`: only empty values * * @public */ export type EmptyValues = "include" | "exclude" | "only"; /** * Attribute elements specified by their URI. * * @remarks * NOTE: attribute element URIs MAY NOT be transferable across workspaces. On some backends (such as bear) * same element WILL have different URI in each workspace. In general we recommend using URIs only if your code retrieves * them at runtime from backend using elements query or from the data view's headers. Hardcoding URIs is never a good idea, if * you find yourself doing that, please consider specifying attribute elements by value * * See {@link IAttributeElementsByValue} * * @public */ export interface IAttributeElementsByRef { uris: Array; } /** * Attribute elements specified by their textual value. * * @public */ export interface IAttributeElementsByValue { values: Array; } /** * Attribute elements are used in positive and negative attribute filters. They can be specified either * using URI (primary key) or using textual values of the attribute elements. * * @public */ export type IAttributeElements = IAttributeElementsByRef | IAttributeElementsByValue; /** * Object defining the {@link IPositiveAttributeFilter} object body. * * @public */ export interface IPositiveAttributeFilterBody extends IIdentifiableFilter { /** * Display form whose attribute elements are included in the 'in' list. */ displayForm: ObjRef | ObjRefInScope; /** * Attribute elements to filter in. The attribute elements can be specified either using * their human readable value or by using their URI = the primary key. Using either representation has * the same effect. While using human readable representation may be more readable in the client code, * the using URI will likely have better performance on the backend. */ in: IAttributeElements; } /** * Positive attribute filter essentially adds an `IN ` condition to the execution on the backend. * * @remarks * When the condition is applied on attribute display form which is included in execution, it essentially limits the * attribute elements that will be returned in the results: only those elements that are in the provided list * will be returned. * * The filter can be specified even for attributes that are not included in the execution - such a filter then * MAY influence the results of the execution indirectly: if the execution definition specifies MAQL measures that * use the filtered attribute. * * If the attribute elements in the `in` property are empty, then the filter is NOOP. * @public */ export interface IPositiveAttributeFilter { positiveAttributeFilter: IPositiveAttributeFilterBody; } /** * Object defining the {@link INegativeAttributeFilter} object body. * * @public */ export interface INegativeAttributeFilterBody extends IIdentifiableFilter { /** * Display form whose attribute elements are included in the 'notIn' list. */ displayForm: ObjRef | ObjRefInScope; /** * Attribute elements to filter out. The attribute elements can be specified either using * their human readable value or by using they URI = the primary key. Using either representation has * the same effect. While using human readable representation may be more readable in the client code, * the using URI will likely have better performance on the backend. */ notIn: IAttributeElements; } /** * Negative attribute filter essentially adds an `NOT IN ` condition to the execution on the backend. * * @remarks * When the condition is applied on attribute display form which is included in execution, it essentially limits the * attribute elements that will be returned in the results: only those elements that ARE NOT in the provided list * will be returned. * * The filter can be specified even for attributes that are not included in the execution - such a filter then * MAY influence the results of the execution indirectly: if the execution definition specifies MAQL measures that * use the filtered attribute. * * If the attribute elements in the `notIn` property are empty, then the filter is NOOP. * * @public */ export interface INegativeAttributeFilter { negativeAttributeFilter: INegativeAttributeFilterBody; } /** * Object defining the {@link IArbitraryAttributeFilter} object body. * * @public */ export interface IArbitraryAttributeFilterBody extends IIdentifiableFilter { /** * Display form whose attribute elements are being filtered */ label: ObjRef; /** * Arbitrary values to filter by. * These values don't need to exist as actual attribute elements. * Use null to represent an empty/missing value. */ values: Array; /** * Whether this is a negative filter (NOT IN). * @defaultValue false */ negativeSelection?: boolean; } /** * Arbitrary attribute filter - allows filtering by custom string values that may not exist as attribute elements. * * @remarks * This filter type allows users to specify arbitrary string values for filtering without needing to * load or validate them against actual attribute elements. Useful for custom/external data integration. * * @public */ export interface IArbitraryAttributeFilter { arbitraryAttributeFilter: IArbitraryAttributeFilterBody; } /** * Match filter operators for literal matching. * * @public */ export type MatchFilterOperator = "contains" | "startsWith" | "endsWith"; /** * Object defining the {@link IMatchAttributeFilter} object body. * * @public */ export interface IMatchAttributeFilterBody extends IIdentifiableFilter { /** * Display form to apply the match filter on */ label: ObjRef; /** * Match operator */ operator: MatchFilterOperator; /** * Literal string to match (cannot be empty for valid filter) */ literal: string; /** * Whether the literal matching is case sensitive */ caseSensitive?: boolean; /** * Whether to negate the match (NOT LIKE) */ negativeSelection?: boolean; } /** * Match attribute filter - literal matching filter for attribute values. * * @remarks * This filter type allows literal-based filtering with various operators (contains, startsWith, endsWith). * Supports both positive and negative matching, as well as case-sensitive/insensitive comparison. * * @public */ export interface IMatchAttributeFilter { matchAttributeFilter: IMatchAttributeFilterBody; } /** * Filters results to an absolute date range - from one fixed date to another. * * @public */ export interface IAbsoluteDateFilter { absoluteDateFilter: IAbsoluteDateFilterBody; } /** * Object defining the {@link IAbsoluteDateFilter} object body. * * @public */ export interface IAbsoluteDateFilterBody extends IIdentifiableFilter { /** * Date data set for filtering */ dataSet: ObjRef; /** * Start date (including): this is in format 'YYYY-MM-DD' */ from: string; /** * End date (including): this is in format 'YYYY-MM-DD' */ to: string; /** * How to treat empty date values. */ emptyValueHandling?: EmptyValues; } /** * Filters results to a relative date range. * * @remarks * The relative filtering is always done on some granularity - this specifies * the units in the 'from' and 'to' fields. * * See {@link DateAttributeGranularity}, {@link AllTimeGranularity} and {@link DateGranularity} for further detail. * @public */ export type IRelativeDateFilter = { relativeDateFilter: IRelativeDateFilterBody; } | { relativeDateFilter: IRelativeDateFilterAllTimeBody; } | { relativeDateFilter: IRelativeBoundedDateFilterBody; }; /** * Object defining the {@link IRelativeDateFilter} object body. * * @public */ export interface IRelativeBoundedDateFilterBody extends IRelativeDateFilterBody { boundedFilter: IUpperBoundedFilter | ILowerBoundedFilter; } /** * Object defining the {@link IUpperBoundedFilter} object body. * * @public */ export interface IUpperBoundedFilter { granularity: DateAttributeGranularity; to: number; } /** * Object defining the {@link ILowerBoundedFilter} object body. * * @public */ export interface ILowerBoundedFilter { granularity: DateAttributeGranularity; from: number; } /** * Object defining the {@link IRelativeDateFilter} object body. * * @public */ export interface IRelativeDateFilterBody extends IIdentifiableFilter { dataSet: ObjRef; granularity: DateAttributeGranularity; from: number; to: number; /** * How to treat empty date values. */ emptyValueHandling?: EmptyValues; } /** * Object defining the {@link IRelativeDateFilter} object body. * * @public */ export interface IRelativeDateFilterAllTimeBody extends IIdentifiableFilter { dataSet: ObjRef; granularity: AllTimeGranularity; from: 0; to: 0; /** * How to treat empty date values. */ emptyValueHandling?: EmptyValues; } /** * Attribute filter with element selection - either positive (IN) or negative (NOT IN). * * @remarks * This type represents attribute filters that work with attribute elements selection, * as opposed to arbitrary and match filters which do not contain elements. * * @public */ export type IAttributeFilterWithSelection = IPositiveAttributeFilter | INegativeAttributeFilter; /** * Attribute filters limit results of execution to data pertaining to attributes that are or are not specified * by the filters. * * @public */ export type IAttributeFilter = IAttributeFilterWithSelection | IArbitraryAttributeFilter | IMatchAttributeFilter; /** * Union of text mode attribute filter types (arbitrary and match). * * @remarks * These filters use free-text values rather than element selection. * * @alpha */ export type TextAttributeFilter = IArbitraryAttributeFilter | IMatchAttributeFilter; /** * Date filters limit the range of results to data within relative or absolute date range. * * @public */ export type IDateFilter = IRelativeDateFilter | IAbsoluteDateFilter; /** * @public */ export type ComparisonConditionOperator = "GREATER_THAN" | "GREATER_THAN_OR_EQUAL_TO" | "LESS_THAN" | "LESS_THAN_OR_EQUAL_TO" | "EQUAL_TO" | "NOT_EQUAL_TO"; /** * @public */ export interface IComparisonConditionBody { operator: ComparisonConditionOperator; value: number; treatNullValuesAs?: number; } /** * @public */ export interface IComparisonCondition { comparison: IComparisonConditionBody; } /** * @public */ export type RangeConditionOperator = "BETWEEN" | "NOT_BETWEEN"; /** * Object defining the {@link IRangeCondition} object body. * * @public */ export interface IRangeConditionBody { operator: RangeConditionOperator; from: number; to: number; treatNullValuesAs?: number; } /** * @public */ export interface IRangeCondition { range: IRangeConditionBody; } /** * @public */ export type MeasureValueFilterCondition = IComparisonCondition | IRangeCondition; /** * Object defining the {@link IMeasureValueFilter} object body. * * @public */ export interface IMeasureValueFilterBody extends IIdentifiableFilter { measure: ObjRefInScope; dimensionality?: ObjRefInScope[]; /** * Indicates whether this filter should be applied on result. * * @remarks * When undefined, backend defaults are used. * * @public */ applyOnResult?: boolean; condition?: MeasureValueFilterCondition; /** * Optional list of conditions for measure value filtering. When provided, it represents multiple conditions * that can be interpreted by backend-specific implementations (e.g. Tiger supports compound measure value * filter with OR-ed conditions). * * @public */ conditions?: MeasureValueFilterCondition[]; } /** * @public */ export interface IMeasureValueFilter { measureValueFilter: IMeasureValueFilterBody; } /** * @public */ export type RankingFilterOperator = "TOP" | "BOTTOM"; /** * Object defining the {@link IRankingFilter} object body. * * @public */ export interface IRankingFilterBody extends IIdentifiableFilter { measure: ObjRefInScope; attributes?: ObjRefInScope[]; operator: RankingFilterOperator; value: number; applyOnResult?: boolean; } /** * @public */ export interface IRankingFilter { rankingFilter: IRankingFilterBody; } /** * All possible filters. * * @public */ export type IFilter = IAbsoluteDateFilter | IRelativeDateFilter | IPositiveAttributeFilter | INegativeAttributeFilter | IMeasureValueFilter | IRankingFilter | IArbitraryAttributeFilter | IMatchAttributeFilter; /** * Filter able to identify itself via local identifier * * @public */ export interface IIdentifiableFilter { localIdentifier?: Identifier; } /** * Represents a filter specification variant where either the actual filter or a 'null' filter is * provided. Null filters will be ignored during processing. * * @public */ export type INullableFilter = IFilter | undefined | null; /** * All possible filters that can be specified for a simple measure. * * @public */ export type IMeasureFilter = IAbsoluteDateFilter | IRelativeDateFilter | IPositiveAttributeFilter | INegativeAttributeFilter | IArbitraryAttributeFilter | IMatchAttributeFilter; /** * Type guard checking whether the provided object is a positive attribute filter. * * @public */ export declare function isSimpleMeasureFilter(obj: unknown): obj is IMeasureFilter; /** * Type guard checking whether the provided object is a positive attribute filter. * * @public */ export declare function isPositiveAttributeFilter(obj: unknown): obj is IPositiveAttributeFilter; /** * Type guard checking whether the provided object is a negative attribute filter. * * @public */ export declare function isNegativeAttributeFilter(obj: unknown): obj is INegativeAttributeFilter; /** * Helper function checking whether the provided filter has negative meaning. * * @public */ export declare function isNegativeFilter(filter: IAttributeFilter): boolean; /** * Type guard checking whether the provided object is an arbitrary attribute filter. * * @alpha */ export declare function isArbitraryAttributeFilter(obj: unknown): obj is IArbitraryAttributeFilter; /** * Type guard checking whether the provided object is a match attribute filter. * * @alpha */ export declare function isMatchAttributeFilter(obj: unknown): obj is IMatchAttributeFilter; /** * Type guard checking whether the provided object is a text attribute filter * ({@link IArbitraryAttributeFilter} or {@link IMatchAttributeFilter}). * @alpha */ export declare function isTextAttributeFilter(obj: unknown): obj is TextAttributeFilter; /** * Type guard checking whether the provided object is an absolute date filter. * * @public */ export declare function isAbsoluteDateFilter(obj: unknown): obj is IAbsoluteDateFilter; /** * Type guard checking whether the provided object is a relative date filter. * * @public */ export declare function isRelativeDateFilter(obj: unknown): obj is IRelativeDateFilter; /** * Type guard checking whether the provided object is a relative date filter body with bounded. * * @public */ export declare function isRelativeBoundedDateFilterBody(obj: unknown): obj is IRelativeBoundedDateFilterBody; /** * Type guard checking whether the provided filter body has a bounded filter with upper bounded. * * @public */ export declare function isRelativeUpperBoundedDateFilterBody(obj: unknown): obj is IRelativeBoundedDateFilterBody & { boundedFilter: IUpperBoundedFilter; }; /** * Type guard checking whether the provided object is an upper bounded filter. * * @public */ export declare function isUpperBound(obj: unknown): obj is IUpperBoundedFilter; /** * Type guard checking whether the provided object is a lower bounded filter. * * @public */ export declare function isLowerBound(obj: unknown): obj is ILowerBoundedFilter; /** * Type guard checking whether the provided filter body has a bounded filter with lower bounded. * * @public */ export declare function isRelativeLowerBoundedDateFilterBody(obj: unknown): obj is IRelativeBoundedDateFilterBody & { boundedFilter: ILowerBoundedFilter; }; /** * Type guard checking whether the provided object is a relative date filter with bounded. * * @public */ export declare function isRelativeBoundedDateFilter(obj: unknown): obj is IRelativeDateFilter & { relativeDateFilter: IRelativeBoundedDateFilterBody; }; /** * Type guard checking whether the provided filter is a relative date filter with upper bounded. * * @public */ export declare function isRelativeUpperBoundedDateFilter(obj: unknown): obj is IRelativeDateFilter & { relativeDateFilter: IRelativeBoundedDateFilterBody & { boundedFilter: IUpperBoundedFilter; }; }; /** * Type guard checking whether the provided filter is a relative date filter with lower bounded. * * @public */ export declare function isRelativeLowerBoundedDateFilter(obj: unknown): obj is IRelativeDateFilter & { relativeDateFilter: IRelativeBoundedDateFilterBody & { boundedFilter: ILowerBoundedFilter; }; }; /** * Type guard checking whether the provided object is an all time date filter. * * @public */ export declare function isAllTimeDateFilter(obj: unknown): obj is IRelativeDateFilter & { relativeDateFilter: { granularity: "ALL_TIME_GRANULARITY"; }; }; /** * Type guard checking whether the provided object is an all time date filter with `emptyValueHandling` defined. * * @remarks * This is useful to distinguish between: * - a noop "all time" filter (no additional configuration), and * - an "all time" filter that carries extra configuration (e.g. empty date values handling). * * @public */ export declare function isAllTimeDateFilterWithEmptyValueHandling(obj: unknown): obj is IRelativeDateFilter & { relativeDateFilter: IRelativeDateFilterAllTimeBody & { emptyValueHandling: EmptyValues; }; }; /** * Type guard checking whether the provided object is a noop "all time" date filter. * * @remarks * This is useful to distinguish between: * - a noop "all time" filter (no additional configuration), and * - an "all time" filter that carries extra configuration (e.g. empty date values handling). * * @public */ export declare function isNoopAllTimeDateFilter(obj: unknown): boolean; /** * Type guard checking whether the provided object is a date filter with `emptyValueHandling` defined. * * @public */ export declare function isDateFilterWithEmptyValueHandling(obj: unknown): obj is (IAbsoluteDateFilter & { absoluteDateFilter: IAbsoluteDateFilterBody & { emptyValueHandling: EmptyValues; }; }) | (IRelativeDateFilter & { relativeDateFilter: (IRelativeDateFilterBody | IRelativeDateFilterAllTimeBody) & { emptyValueHandling: EmptyValues; }; }); /** * Type guard checking whether the provided object is an attribute filter. * * @public */ export declare function isAttributeFilter(obj: unknown): obj is IAttributeFilter; /** * Type guard checking whether the provided object is an attribute filter with selection by elements. * * @public */ export declare function isAttributeFilterWithSelection(obj: unknown): obj is IAttributeFilterWithSelection; /** * Type guard checking whether the provided object is a date filter. * * @public */ export declare function isDateFilter(obj: unknown): obj is IDateFilter; /** * Type guard checking whether the provided object is a measure value filter. * * @public */ export declare function isMeasureValueFilter(obj: unknown): obj is IMeasureValueFilter; /** * Type guard checking whether the provided object is a ranking filter. * * @public */ export declare function isRankingFilter(obj: unknown): obj is IRankingFilter; /** * Type guard checking whether the provided object is a filter. * * @public */ export declare function isFilter(obj: unknown): obj is IFilter; /** * Type guard checking whether the provided object is a measure value filter's comparison condition. * * @public */ export declare function isComparisonCondition(obj: unknown): obj is IComparisonCondition; /** * Type guard checking whether the provided operator is a measure value filter's comparison operator. * * @public */ export declare function isComparisonConditionOperator(obj: unknown): obj is ComparisonConditionOperator; /** * Type guard checking whether the provided object is a measure value filter's range condition. * * @public */ export declare function isRangeCondition(obj: unknown): obj is IRangeCondition; /** * Type guard checking whether the provided object is a measure value filter's range condition operator. * * @public */ export declare function isRangeConditionOperator(obj: unknown): obj is RangeConditionOperator; /** * Type guard checking whether the provided object is list of attribute elements specified by URI reference. * * @public */ export declare function isAttributeElementsByRef(obj: unknown): obj is IAttributeElementsByRef; /** * Type guard checking whether the provided object is list of attribute elements specified by their text value. * * @public */ export declare function isAttributeElementsByValue(obj: unknown): obj is IAttributeElementsByValue; /** * Tests whether the provided attribute element does not specify any attribute elements. * * @param filter - attribute filter to test * @returns true if empty = no attribute elements * @public */ export declare function filterIsEmpty(filter: IAttributeFilter): boolean; /** * Tests whether the provided filter is an "All values" attribute filter * (a negative attribute filter with an empty exclusion list). * * @param filter - filter to test * @returns true if the filter is a negative attribute filter selecting all values * @internal */ export declare function isAllValuesAttributeFilter(filter: unknown): filter is INegativeAttributeFilter; /** * Tests whether the attribute elements object is empty. * * @param attributeElements - object to test * @returns true if empty = attribute elements not specified in any way (URI or value) * @internal */ export declare function attributeElementsIsEmpty(attributeElements: IAttributeElements): boolean; /** * Gets the number of items in the {@link IAttributeElements}. * * @param attributeElements - object to test * @returns the number of items * @internal */ export declare function attributeElementsCount(attributeElements: IAttributeElements): number; /** * Gets the items from the {@link IAttributeElements}. * * @param attributeElements - object to get items from * @returns the array of items * @internal */ export declare function getAttributeElementsItems(attributeElements: IAttributeElements): Array; /** * Updates the items in the {@link IAttributeElements}. * * @param attributeElements - object to update items in * @param newItems - new items to put into attributeElements * @returns updated attributeElements object with new item values * @internal */ export declare function updateAttributeElementsItems(attributeElements: IAttributeElements, newItems: Array): IAttributeElements; /** * Gets attribute elements specified on the attribute filter. * * @param filter - attribute filter to work with * @returns attribute elements, undefined if not available * @public */ export declare function filterAttributeElements(filter: IAttributeFilterWithSelection): IAttributeElements; /** * Gets attribute elements specified on a filter. If the provided filter is not an attribute filter, then * undefined is returned * * @param filter - filter to work with * @returns attribute elements, undefined if not available * @public */ export declare function filterAttributeElements(filter: IFilter): IAttributeElements | undefined; /** * Gets reference to object being used for filtering. * * @remarks * For attribute filters, this will be reference to the display form. For date filters this will be reference to the data set. * This overload applies to filter types that always have an ObjRef (date filters, arbitrary attribute filter, match attribute filter). * Positive and negative attribute filters use ObjRef | ObjRefInScope for displayForm and may return undefined when using local identifiers. * * @param filter - filter to work with * @returns reference to object used for filtering (display form for attr filters, data set for date filters) * @public */ export declare function filterObjRef(filter: IAbsoluteDateFilter | IRelativeDateFilter | IPositiveAttributeFilter | INegativeAttributeFilter | IArbitraryAttributeFilter | IMatchAttributeFilter): ObjRef; /** * Gets reference to object being used for filtering. * * @remarks * For attribute filters, this will be reference to the display form. * For date filters this will be reference to the data set. For measure value filter and ranking filter, this will be undefined. * * @param filter - filter to work with * @returns reference to object used for filtering (display form for attr filters, data set for date filters), undefined * for measure value filters and ranking filters * @public */ export declare function filterObjRef(filter: IFilter): ObjRef | undefined; /** * Gets local identifier of filter. * * @remarks * So far valid only for attribute and date filters. * * @param filter - filter to work with * @returns local identifier of filter object if defined, undefined otherwise * @public */ export declare function filterLocalIdentifier(filter: IFilter): string | undefined; /** * Gets reference to a measure being used for filtering if the provided filter is measure based. For other filters return undefined. * * @public */ export declare function filterMeasureRef(filter: IFilter): ObjRefInScope | undefined; /** * Represents values of an absolute filter. * * @public */ export interface IAbsoluteDateFilterValues { from: string; to: string; dataSet?: ObjRef; emptyValueHandling?: EmptyValues; } /** * Gets effective values of an absolute date filter. * * @param filter - date filter to work with * @param includeDataSet - whether to include data set in the returned values * @returns filter values * @public */ export declare function absoluteDateFilterValues(filter: IAbsoluteDateFilter, includeDataSet?: boolean): IAbsoluteDateFilterValues; /** * Represents values of a relative filter. * * @public */ export interface IRelativeDateFilterValues { from: number; to: number; granularity: string; dataSet?: ObjRef; boundedFilter?: IUpperBoundedFilter | ILowerBoundedFilter; emptyValueHandling?: EmptyValues; } /** * Gets effective values of a relative date filter. * * @param filter - date filter to work with * @param includeDataSet - whether to include data set in the returned values * @returns filter values * @public */ export declare function relativeDateFilterValues(filter: IRelativeDateFilter, includeDataSet?: boolean): IRelativeDateFilterValues; /** * Gets measure value filter measure. * @param filter - measure value filter to work with * @returns filter measure * @public */ export declare function measureValueFilterMeasure(filter: IMeasureValueFilter): ObjRefInScope; /** * Gets measure value filter condition. Provides only legacy condition property. * @param filter - measure value filter to work with * @deprecated use measureValueFilterConditions instead * @returns filter condition * @public */ export declare function measureValueFilterCondition(filter: IMeasureValueFilter): MeasureValueFilterCondition | undefined; /** * Gets measure value filter conditions. * @param filter - measure value filter to work with * @returns filter conditions eother legacy condition or array of conditions * @public */ export declare function measureValueFilterConditions(filter: IMeasureValueFilter): MeasureValueFilterCondition[] | undefined; /** * Checks if measure value filter has conditions. * @param filter - measure value filter to work with * @returns true if filter has conditions, false otherwise * @public */ export declare function hasMeasureValueFilterConditions(filter: IMeasureValueFilter): boolean; /** * Gets measure value filter dimensionality. * @param filter - measure value filter to work with * @returns filter dimensionality array or undefined if not specified, in this case visualization granularity is used for filtering * @public */ export declare function measureValueFilterDimensionality(filter: IMeasureValueFilter): ObjRefInScope[] | undefined; /** * Gets operator used in measure value filter condition. * * @param filter - filter to get operator from * @returns undefined if no condition in the filter * @public */ export declare function measureValueFilterOperator(filter: IMeasureValueFilter): ComparisonConditionOperator | RangeConditionOperator | undefined; /** * Gets operators used in measure value filter conditions. * Supports both legacy single condition and new multiple conditions format. * * @param filter - filter to get operators from * @returns array of operators or undefined if no conditions in the filter * @public */ export declare function measureValueFilterOperators(filter: IMeasureValueFilter): Array | undefined; //# sourceMappingURL=index.d.ts.map