> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced scopes

> Reference for advanced scope types in Atoti Limits, covering IN, NOT IN, TOTAL IN, and TOTAL NOT IN operators, their notation formats, use cases, and multi-level member scope definitions

Advanced scopes allow you to define scopes across a set of scope location members, which is often required when managing limits.

Atoti Limits currently supports four types of advanced scopes at a defined level. These are:

* [IN scope / “(For each) selected” in the UI](#in--for-each-selected-in-the-ui)
* [NOT IN scope / “(For each) excluding selected” in the UI](#not-in--for-each-excluding-selected-in-the-ui)
* [TOTAL IN scope / “(Total) of selected” in the UI](#total-in--total-of-selected-in-the-ui)
* [TOTAL NOT IN scope / “(Total) excluding selected” in the UI](#total-not-in--total-excluding-selected-in-the-ui)

See the [operators](#scope-operators) section for more details on each type of scope.

## Advanced scope definitions

Advanced scopes are defined similarly to regular scopes, with some added notation. Each location is pipe-separated, the level names are
[normalized](./scope-overview#scope-normalization) and missing parents of multi-level hierarchies are derived depending on user-defined
[scope properties](./scope-properties).

<Note>
  In the following examples we denote scopes using the standard verbose format as it is more
  intuitive to new users. More experienced users may prefer to use
  the [Simplified scopes](#using-simplified-scope-notation) notation.
</Note>

<Note>
  Whitespaces between symbols will be trimmed.
</Note>

Here are some examples:

### `IN` / “(For each) selected” in the UI

Here the limit is evaluated where the level member is IN a set of supplied members. The notation is:

```
<Level Name> = [ <Level Member 1> + <Level Member 2> + ... ]
```

For example, to evaluate the limit only where the currency is USD or EUR, define the location as:

```
Currency = [ USD + EUR ]
```

<Note>
  The `+` symbol here is merely for notational purposes and does not indicate addition of the members. We require distinct
  symbols to be used in order to correctly parse the scope on file import. For very complex scopes, we recommend using the UI rather than
  editing the file.
</Note>

### `NOT IN` / “(For each) excluding selected” in the UI

Here the limit is evaluated where the level member is NOT IN a set of supplied members. The notation is:

```
<Level Name> <> [ <Level Member 1> + <Level Member 2> + ... ]
```

For example, to evaluate the limit only where currency is not equal to USD or EUR, define the location as:

```
Currency <> [ USD + EUR ]
```

<Note>
  `<>` is the MDX representation of “[not equal to](https://learn.microsoft.com/en-us/sql/mdx/not-equal-to-mdx?view=sql-server-ver16)”.
</Note>

### `TOTAL IN` / “(Total) of selected” in the UI

<Warning>
  A limit of this scope should not be used in conjunction with other limits or scope locations.
  Otherwise, the Business cube will not be able to determine the location for evaluating the limit.
</Warning>

Here the limit is evaluated as the total of where the level member is IN a set of supplied members. The notation is:

```
<Level Name> &= [ <Level Member 1> + <Level Member 2> + ... ]
```

For example, to evaluate the sum of values where Book is Book 1 and Book 2, define the location as:

```
Book &= [ Book 1 + Book 2 ]
```

<Note>
  The wildcard (`*`) and `AllMember` values are not allowed for this type of scope.
</Note>

### `TOTAL NOT IN` / “(Total) excluding selected” in the UI

<Warning>
  A limit of this scope should not be used in conjunction with other limits or scope locations.
  Otherwise, the Business cube will not be able to determine the location for evaluating the limit.
</Warning>

Here the limit is evaluated as the total of locations where the level member is NOT IN a set of supplied members.

```
<Level Name> &<> [ <Level Member 1> + <Level Member 2> + ... ]
```

For example, to evaluate the sum of values of the Book level, excluding Book 3 and Book 4, define the location as:

```
Book &<> [ Book 3 + Book 4 ]
```

<Note>
  The wildcard (`*`) and `AllMember` values are not allowed for this type of scope.
</Note>

### Special case: defining multiple multi-Level members

We may want to define a location on a multi-level hierarchy for multiple members. For example, we may want to evaluate at:

```
City = North America / United States / New York City
City = Europe / Ireland / Dublin
```

To do so, for this special case we use the following notation:

```
<Selected Level> <Operator> [ <Level Parent_0>=<Level Parent Value_0>&<Level Parent_1>=<Level Parent Value_1>&...&<Selected Level>=<Selected Value 1> +
                              <Level Parent_0>=<Level Parent Value_2>&<Level Parent_1>=<Level Parent Value_3>&...&<Selected Level>=<Selected Value 2> +
                              ...
                              <Level Parent_0>=<Level Parent Value_2>&<Level Parent_1>=<Level Parent Value_3>&...&<Selected Level>=<Selected Value n> +
                              ]
```

where:

* `Operator` is the symbol of the [operator](#scope-operators) to be used.
* `Level Parent_n` is the level at ordinal `n` in the level path. This order is important and the topmost parent should be the first in the path.

In our city example above, this would look like:

```
City = [
        Continent@Geography=North America & Country=United States & City=New York City +
        Continent@Geography=Europe & Country=Ireland & City=Dublin
        ]
```

## Scope operators

A scope operator determines the type of operation an advanced scope uses. The options are:

* EQUALS
* NOT\_EQUALS
* TOTAL\_EQUALS
* TOTAL\_EXCEPT

Each operator can be inclusive or exclusive, and aggregated or non-aggregated. On evaluation:

* an inclusive operator includes the level members specified in its definition, while an exclusive operator will exclude the members specified in its definition.
* an aggregated operator will evaluate only at the `AllMember` level for the levels specified in its definition, while a non-aggregated operator will only apply at the level members for the members specified in its definition.

<table><thead><tr><th>Advanced scope type</th><th>Operator</th><th>Symbol</th><th>Inclusive</th><th>Aggregated</th><th>Example</th><th>Example value Description</th></tr></thead><tbody><tr><td>IN</td><td>EQUALS</td><td>=</td><td>Yes</td><td>No</td><td>Book=\[ Book 1 + Book 2 ]</td><td>Evaluation occurs where the <code>Book</code> level member equals <code>Book 1</code> or <code>Book 2</code>.</td></tr><tr><td>NOT IN</td><td>NOT\_EQUALS</td><td>\<></td><td>No</td><td>No</td><td>Book\<>\[ Book 1 + Book 2 ]</td><td>Evaluation occurs anywhere where the <code>Book</code> level member is not equal to <code>Book 1</code> or <code>Book 2</code>.</td></tr><tr><td>TOTAL IN</td><td>TOTAL\_EQUALS</td><td>&=</td><td>Yes</td><td>Yes</td><td>Book&=\[ Book 1 + Book 2 ]</td><td>The value is the sum of <code>Book 1</code> and <code>Book 2</code>, and will be displayed at the <code>AllMember</code> level.</td></tr><tr><td>TOTAL NOT IN</td><td>TOTAL\_EXCEPT</td><td>&\<></td><td>No</td><td>Yes</td><td>Book&\<>\[ Book 1 + Book 2 ]</td><td>The value is the sum of all members of the <code>Book</code> level, excluding <code>Book 1</code> and <code>Book 2</code>, and will be displayed at the <code>AllMember</code> level.</td></tr></tbody></table>

### Use simplified scope notation

Simplified scope notation offers a shortened version of the traditional scope notation Level = Member. Instead of specifying the Level and Member, separated by an Operator, you can simply specify the Member.
See [Simplified scopes](./scope-overview#example-notation-for-defining-simplified-scopes) for example notation.