Dimension Queries

A dimension query is a metadata query that returns members from a dimension.

Query Object Structure

// swagger/v1/swagger.json#/components/schemas/DimensionQuery
interface DimensionQuery {
  dimension?: string;                // Name of the dimension to query
  model?: string;                    // Name of the model the dimension is associated with
  useDimensionRoles?: boolean;       // Use dimension roles (API-specific)
  dimensionRole?: string;            // Used to identify the dimension by role
  hierarchy?: string;                // Alternate hierarchy to query (null = primary)
  postOrder?: boolean;               // If true, use post-order (children before parents)
  securityProfile?: string;          // Name of the security profile to apply
  properties?: string[];             // List of properties to return
  members?: QueryMemberSet[];        // Query specification
  queryOptimizationFlags?: QueryOptimizationFlags; // Optimization flags (API-specific)
  variables?: string[][];            // Array of variable arrays for substitution
  rootMemberKey?: string;            // Root member key for tree queries
  rootMemberName?: string;           // Root member name for tree queries
  rootMemberTag?: string;            // Root member tag for tree queries
  includeRoot?: boolean;             // Whether to include the virtual root member
  isCustomRootMember?: boolean;      // API-specific: custom root member
}

Member	Description
Dimension	Name of the dimension to query; optional
Model	Name of the model the queried dimension is associated with; optional; used to identify the dimension by role and to apply security profiles
DimensionRole	Used to identify the dimension by role; requires Model; ignored if Dimension is not null
Hierarchy	Alternate hierarchy to query; null means the default/primary hierarchy
Ordering	Can be Natural (parents before children) or PostNatural (children before parents); default is Natural
SecurityProfile	Name of the security profile to apply; defaults to the ReadProfile for the model if a model is specified
Properties	List of dimension member properties to return; Key, Name, Caption, and Level are always returned
Members	Query specification—which dimension members to return; multiple set specifications will be appended together
RootMemberKey	Used for tree queries with a common root; specifies the root member key
RootMemberName	Used for tree queries with a common root; specifies the root member name; ignored if RootMemberKey is present
RootMemberTag	Used for tree queries with a common root; specifies the root member tag; ignored if RootMemberKey or RootMemberName are present
IncludeRoot	If true, then the virtual member root will be returned as a query result member

Member Set Specification

// swagger/v1/swagger.json#/components/schemas/QueryMemberSet
interface QueryMemberSet {
  id: string;                      // Unique identifier for the member set (required)
  type?: string;                   // Member, Union, Intersect, Exclude, Range, Filter
  subsets?: QueryMemberSet[];      // For set operations
  filterProperty?: string;         // Property for filtering
  filterOp?: string;               // Filter operation
  filterValue?: string;            // Value to filter by
  key?: string;                    // Member key (string, not number)
  name?: string;                   // Member name
  tag?: string;                    // Member tag
  relationship?: string;           // Relationship to member
}

Type Values

Member

The set consists of a single member or a list of members related to a single member. This is the default set type. One of Key, Name, or Tag must be supplied, and optionally Relationship.

Relationship options:

Relationship	Description
Self	Returns just the specified member (default)
Children	Returns the children of the specified member (excluding the member itself)
SelfAndChildren	Returns the member and its children
Descendants	Returns all descendants of the specified member (excluding the member itself)
SelfAndDescendants	Returns the member and all its descendants
LeafDescendants	Returns all leaf member descendants of the specified member (including the member itself)
FirstSibling	Returns the first sibling of the member
LastSibling	Returns the last sibling of the member
PrevSibling	Returns the previous sibling of the member (might not exist)
NextSibling	Returns the next sibling of the member (might not exist)
FirstLeafDescendant	Returns the first leaf descendant of the member (including member itself)
LastLeafDescendant	Returns the last leaf descendant of the member (including member itself)

Set Operations

• Union - Returns all members from all subsets; eliminates duplicates
• Intersect - Returns only members present in all subsets
• Exclude - Returns members from the first set that are not present in any other sets
• Range - Returns all members between a start and end member; both must be on the same level

Filter

Filters a subset by a property. Requires FilterProperty, FilterOp, and FilterValue.

• FilterOp can be one of: =, <>, <, >, <=, >=

Virtual Root

Each hierarchy contains a virtual root member that is the ultimate ancestor of all members. By convention, the virtual root has a Key equal to 0 and its Name is "*".

The virtual adjective means that, while it can be referred to in queries, it does not really exist and will normally not be returned as part of a query result.

Query	Result
Children of the root	All members at level 1 in the hierarchy
SelfAndChildren	Same as Children (member itself is not included)
Descendants or SelfAndDescendants	All members in the hierarchy
LeafDescendants	All leaf members in the hierarchy
Self	Nothing
Sibling relationships	Nothing

If IncludeRoot is true, then the query result will include the virtual root when applicable. The virtual root member has Key 0, Name "*", Caption same as the name of the dimension/hierarchy, Level 0, and all other properties set to null.

Variable Substitution

Most query parameters support strings that contain a variable name surrounded by braces (e.g., {name}). If the name included in the braces matches an existing variable (global tenant variable, user variable, dashboard/report parameter), the entire construct, including the braces, will be replaced with the content of the variable.

caution

Variable substitution is done blindly, without any awareness of context. It is the responsibility of the query builder to properly incorporate the substitution.

Query Result

The query result returns:

// swagger/v1/swagger.json#/components/schemas/DimensionResult
interface DimensionResult {
  dimension: string;                // Dimension name
  hierarchy?: string;               // Hierarchy name (if applicable)
  members?: MemberResult[];         // Array of member results
}

// swagger/v1/swagger.json#/components/schemas/MemberResult
interface MemberResult {
  key: number;                      // Member key
  name?: string;                    // Member name
  caption?: string;                 // Display caption
  level: number;                    // Hierarchical level
  parentKey?: number;               // Parent member key
  isLeaf?: boolean;                 // Is leaf member
  properties?: Record<string, unknown>; // Additional properties
  displayOnly?: boolean;            // API-specific: display only
}