Scope overview

A Scope specifies a location or range of locations of an Atoti Server Cube a limit will be applied on.

Scope Definition

A limit’s Scope represents one or many locations in the Cube where the limit should be applied. A Scope is defined by a list of Cube Level names and Level-Values. For example, for a limit to apply to “MyBook” of the “Book” dimension, the Value/Pair “Book=MyBook” can be defined as the limit’s Scope.

A Scope Key needs to be specific enough so that it only matches one Level Member in the Cube, to avoid Ambiguous Scopes. The Scope can consist of multiple Level definitions within the format: key1=value1|key2=value2|key3=value3.

Each individual Scope is separated by a pipe ‘|’ character, which represents an AND condition. If a key is used multiple times within a Scope definition, the multiple values will be treated with an OR condition.

For example, the following scope with multiple values for one key:

Desk=Desk1|Book=Book_A|Book=Book_B

Will create a matching condition on the cube:

Desk=Desk1 AND (Book=Book_A OR Book=Book_B)

This is the same as defining the limit twice where each scope defines the same Desk but different Books.

Scope Syntax

A Scope is broken up into two main components:

1. Scope Key: Specifies a Level in the Cube. Can be provided in one of the following ways:
   • LevelName - (Minimum required): Only specifies the Level Name.
   • LevelName@HierarchyName - (Optional): Specifies the Level in a specific Hierarchy.
   • LevelName@HierarchyName@DimensionName - (Optional): Specifies the Level in a specific Hierarchy in a specific Dimension.
2. Scope Value: Specifies a Member(s) within the provided Level to apply the limit on.
   • Specific Member - Can specify a specific Member of a Level in the Cube.
   • AllMember - Can specify the AllMember (total) of a Level in the Cube.
   • Wildcard “*” - To match all members of a Level in the Cube (not including the AllMember).

Scope Normalization

Loaded Scopes are normalized internally so that the Scope Keys are in the format of LevelName@Hierarchy@Dimension and any missing parent levels of a MultiLevelHierarchy will be added to the scope. This means that if you provide only the level “Level4” then levels 1-3 will be added to the scope with their value as a Wildcard.

When exporting limits, you may notice that the Scopes exported may not line up exactly with the input Scopes - but functionally the exported limits will behave the same as the Scope provided.

Scope Overlap

Two limits can overlap on a location in the cube. For instance, if we define a limit with a Wildcard and another with an Explicit member, both limits can apply to the same location. To prevent multiple limits from applying to the same location, the following logic is in place to pick the limit whose Scope best fits a location in the Cube:

For a given location, we take the Limit Definition that has:

1. A higher precedence
2. Matches a location with more explicit scope matches.
3. Matches a location with more wildcard scope matches.
4. Has a more conservative value.

Scope Examples

Below we can find examples of the different types of scopes that can be used in Atoti Limits.

Simple Scope Creation Example

Let’s say we want to add a limit on the following highlighted location:

We can define our limit with the Level Key “Book” and the LevelMember “Book 1”:

Which we can define as:

Book=Book 1

We can use this process to define limits on any location(s) in the cube.

Explicit Scopes

An explicit Scope value is one where the Cube Level and Level Member are explicitly defined.

For example:

ID=1

Multiple Explicit Scopes

A Scope can have multiple explicit values.

For example:

Vertex=1d|Vertex=1m|Vertex=1w

This is the same as defining the limit three times, each with a scope only defining one vertex.

Wildcard Scopes

A Scope’s Level value can also be applied to all Level Members of a given Cube Level. This is done by specifying a Scope where the Cube Level Member is a wildcard denoted by an asterisk “*”. This will match all Members of the given Cube Level. An example of a Wildcard scope is defined below:

ID=*

All Member Scopes

A Scope’s Level value can also be applied to the AllMember Level of a given Cube Level. This is done by specifying a Scope where the Cube Level Member is (“AllMember”). This will match the Total / AllMember of the given Cube Level. An example of an AllMember scope is defined below:

Book=AllMember

Ambiguous Scopes

A Scope can be ambiguous if the Level or Level Member specified exists in multiple Hierarchies.

Ambiguous Level Name

Assuming we have the following Cube structure:

If we specify a Scope Year=2022, Limits will throw an exception, as Year is ambiguous and relates to two Levels in the Cube Year of the Days Hierarchy and Year of the Leap Years Hierarchy. To fix this, we need to specify that we want the year of the Leap Years Hierarchy: Year@Leap Years=2022.

Ambiguous Level Path

A Level Member is ambiguous if it’s part of a Multi-Level Hierarchy and there are multiple paths through the Hierarchy Levels to get to this specific Level Member. Scopes defined in this manner are valid and do not cause issues. When defining a Scope on a Multi-Level-hierarchy, missing parent-levels will be defaulted to the Wildcard scope value.

Here is an example of an ambiguous Level Path.

Assuming we have the following Cube structure:

With the below data for the Levels of the Days Hierarchy:

If we specify a scope Month=February, after Scope Normalization the scope will be Month=February|Year=* (since Year was not provided, a default Wildcard is added). This is ambiguous, because there are two ways to get to the month February within the Days Hierarchy: [2021/February, 2022/February], so the Level Member does not have an absolute path back to the root.

If we wanted the scope to only apply to the year 2022, then we should modify our Scope to be: Month=February|Year=2022. If we want our limit to apply to any February, we can leave the Scope as is.