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

# Dimensions

> The shared dimensions provided by the common layer and how to extend them through configuration properties or the IModelConfigurer Java API.

The common layer ships with a set of dimensions shared across all solutions. These dimensions cover the core analytical axes needed for financial risk reporting: dates, trade metadata, currencies, statistical parameters, and reference data.

Understanding the available dimensions helps when configuring a solution or extending it with custom analytical axes.

**Prerequisites**: Familiarity with the Atoti Configuration API cube model and APIs.

## What are the common dimensions?

The following table lists every dimension provided by the common layer.

| Dimension | Description | Optional? |
| - | - | - |
| **AsOfDate** | Business date of the risk calculation. Displayed in descending order by default. | No |
| **Trade Attributes** | Trade-level descriptors including Trade ID, Trader, Sales, Trade Date, and Trade Maturity. | No |
| **Display Currency** | Output currency for monetary measures. Currency conversion is applied at query time using FX rates. The available currencies and default are set via configuration properties. | No |
| **Confidence Levels** | Confidence percentages used for VaR and ES calculations (e.g. 95%, 99%). The available levels and default are set via configuration properties. | No |
| **Scenarios** | Individual scenario names derived from the PnL vector. The scenario count is set via configuration properties. | No |
| **Instrument Attributes** | Instrument reference data including identifiers (ISIN, CUSIP, Bloomberg code, SEDOL, Ticker), classification fields (asset class, instrument type, sector, issuer country), and derivative fields (strike, underlying, expiry, call/put). | No |
| **Organization** | Hierarchical organization units, supporting parent-child tree navigation. | Yes |
| **Counterparty** | Counterparty groupings with classification levels (ID, name, rating, sector, country of address, country of risk) and a configurable hierarchy. | Yes |
| **Book** | Book hierarchy with a flat identifier level and a configurable multi-level structure hierarchy. | Yes |

### What are optional dimensions?

The common layer provides the Organization, Counterparties, and Books dimensions as reusable building blocks. Each solution decides independently whether to include them and, if so, whether to expose a configuration property that lets users enable or disable them. Some solutions include a feature as a permanent part of their cube with no toggle.

The documentation for each solution lists which optional dimensions are available and how they are controlled.

## How to extend dimensions

### Via configuration properties

Configuration properties control which dimensions are enabled and how existing dimensions behave. Examples include enabling or disabling optional dimensions via feature flags, and setting parameters such as display currencies, confidence levels, and scenario count. Adding entirely new custom dimensions requires the Java API.

See [Configuration properties](/solutions/enterprise-risk-suite/1.0/common/reference/configuration-properties.md) for supported options.

### Via the Java API

To add entirely new dimensions, use an `IModelConfigurer` implementation. First add the field to the database, then create the dimension on the cube.

The following example adds a `Region` field to the facts table and exposes it as a new dimension. On the cube, obtain the dimensions configurator with `cube(...).dimensions()`, create the dimension with `addDimension(name, dimensionTable)`, then attach a single-field hierarchy built with `ITableHierarchyDefinition.builder(...).withFieldLevel(level, FieldPath.of(...))`:

```java theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
private static final FieldDescription REGION_FIELD =
    FieldDescription.builder().name("Region").dataType(STRING).build();
// In IModelConfigurer.configureDatabase(): add the field to the facts table.
void configureDatabase(final IDatabaseConfigurator databaseConfigurator) {
  databaseConfigurator.table(FACTS_TABLE).addField(REGION_FIELD);
}
// In IModelConfigurer.configureCubes(): expose the field as a new dimension and hierarchy.
void configureCubes(final ICubeManagerConfigurator cubeManagerConfigurator) {
  cubeManagerConfigurator
      .cube(CUBE_NAME)
      .dimensions()
      .addDimension("Region", FACTS_TABLE)
      .addHierarchy(
          ITableHierarchyDefinition.builder("Region")
              .withFieldLevel("Region", FieldPath.of("Region"))
              .build());
}
```

### What are the dimension relationship types?

When adding a dimension from a table, the relationship between that table and the fact table must be specified. Three relationship types are available:

| Relationship | Description | Use case |
| - | - | - |
| Many-to-one | Multiple fact rows map to a single dimension row. | Standard dimensions such as products or counterparties. |
| Many-to-many | A single fact row maps to multiple dimension rows. | Dimensions such as a trade with multiple counterparties. |
| No relationship | The dimension table is not related to the fact table. | Reference data not joined to trades or positions. |

If the relationship is not specified, the configurator infers a unique many-to-one relationship automatically. The code example above uses this inferred behavior.

Many-to-many dimensions are computed at query time and cannot be used in pre-aggregators.

## How to rename dimensions

Dimensions, hierarchies, and levels defined by a solution can be renamed without modifying Java code. Add name overrides to `application.yml`:

```yaml theme={"languages":{"custom":["/engine/python-sdk/6.2/languages/pycon.tmLanguage.json"]}}
semantic-model:
  name-overrides:
    cubes:
      MyCube:
        dimensions:
          Dimension1:
            newName: DimensionA
            hierarchies:
              Hierarchy1:
                levels:
                  Level1:
                    newName: LevelA
              Hierarchy2:
                newName: HierarchyB
                levels:
                  Level2:
                    newName: LevelB
          Dimension2:
            hierarchies:
              Hierarchy1:
                newName: HierarchyC
                levels:
                  Level1:
                    newName: LevelC
```

## Related pages

* [Dimensions and hierarchies reference](/solutions/enterprise-risk-suite/1.0/common/reference/dimensions-and-hierarchies.md)
* [Atoti Configuration API: Hierarchies and dimensions reference](/solutions/enterprise-risk-suite/1.0/foundry/cube/structure.md)
* [Configuration properties](/solutions/enterprise-risk-suite/1.0/common/reference/configuration-properties.md)