> ## 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.

# Dimension and hierarchy Configuration

## Introduction

Hierarchies and dimensions are central to how data is structured, filtered and analyzed using Atoti.

* A hierarchy contains a list of similar items or members. For example a currency hierarchy may contain the members EUR,
  GBP, USD, etc.
* A hierarchy can be single-level (i.e. the currency hierarchy above) or multi-level (i.e. a date hierarchy which is
  organized by year/quarter/month/date).
* A dimension is a group of related hierarchies. For example the hierarchies “Trader Name”, “Trader ID”, and “Trader
  Location” could be grouped into a dimension “Trader”.

For more info about hierarchies, see [here](../concepts/dimensions_and_hierarchies).

## Create a dimension with multi-level and single-level hierarchies

To create a dimension, use `ICanStartBuildingDimensions.DimensionsAdder` to create new dimensions

* `withDimension` creates and name the dimension
* `withHierarchy` creates and name the hierarchy
* `withLevel` creates and name the levels for this hierarchy, matching the fields in the datastore. For more info about
  level configuration see [here](./level_configuration)

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
public ICanStartBuildingDimensions.DimensionsAdder dimensions() {
  return dimensionsBuilder ->
      dimensionsBuilder
          .withDimension("Currency")
          .withSingleLevelHierarchy("Currency")
          .withDimension("Trader")
          .withHierarchy("Trader")
          .withLevel("Trader Region")
          .withLevel("Trader Country")
          .withLevel("Trader Entity");
}
```

:::tip\[Check that it works:]

* use `StartBuilding.cube().withName("Cube")` to start creating a cube
* use `withDimensions` to use the `DimensionAdder` you defined earlier
* use `build()` to build the cube

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
StartBuilding.cube().withName("Cube").withDimensions(dimensions());
```

:::

## Hierarchy members: AllMember vs slicing members

The data in a hierarchy can sometimes be sensibly summed or aggregated. For example, sales data in the geography
hierarchy can be summed to give a global sum. The aggregated value is in AllMember for a hierarchy.
Not all hierarchies can be aggregated in this way. Some data cannot be easily summed, for example the sales figures for
different currencies cannot be summed without taking into consideration fluctuating exchange rates. In this case, the
hierarchy can be set as a slicing hierarchy.

The AllMember is used as a default for the hierarchy. When the aggregated values for this hierarchy are selected,
AllMember is displayed.

For slicing hierarchies, a slicing member is displayed as the default in place of AllMember.

Common uses of slicing hierarchies include:

* currency: retrieve aggregated values for a single currency at a time
* date: retrieve the values for AsOfDate (or another date) by default

Define a hierarchy as a slicing hierarchy

* use `slicing()`
* `.withLevel()` gives the name of the level used as the slicer

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
builder.withDimension("Trader").withHierarchy("Trader").slicing().withLevel("Trader");
```

### Set a default hierarchy member with a slicing hierarchy

You can specify the default member of a slicing hierarchy by changing the first member of the first level.

* a date hierarchy is set to show As of Date as T-1
* a currency hierarchy is set to show EUR as a default. Other currencies are selected when required.

Define a hierarchy as a slicing hierarchy with a default member

* use `slicing()`
* `.withLevel()` gives the name of the level used as the slicer
* `.withFirstObjects()` to provide the first member that will be used as the default value.

```java theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
builder
    .withDimension("Currency")
    .withHierarchy("Currency")
    .slicing()
    .withLevel("Currency")
    .withFirstObjects("EUR");
```

## Uses and applications

Hierarchies can be used in different ways, depending on your needs and objectives.

You may want to learn more about these concepts:

* data filtering on Atoti UI
* measure definition using hierarchies
* limit end-user access and permissions with hierarchies