Cube Locations

Location Definitions

A Location represents the path to one or several cells in a cube. For each Hierarchy, it specifies a path to one or more members.

A Coordinate is the value for a hierarchy/level pair. It is also called the Discriminator. For example, 'the Coordinate at (3,4)' represents the value at Hierarchy 3, Level 4. If Hierarchy 3 is a Date/Time hierarchy and its member in the location is 2014\October\23-Oct-2014\7am\07:25, then Discriminator designated by 'the Coordinate at (3,4)' is 7am.

Concrete locations

A concrete location, also called point location, or fully defined location, points at a single cell in the cube. It defines a specific member on each hierarchy.

As the main principle of an OLAP database is the aggregation of data, the exact definition required on each hierarchy is a path of a member from a root to the appropriate child member. For instance, suppose we have two root members (the years 2013 and 2014) on a time hierarchy. Each of these years has 12 children which are the months. Similarly, each month has a particular set of child days.

Hence on this hierarchy, one user can focus on:

  • A year, e.g.: 2014
  • A month defined by it's path, e.g.: 2014\October
  • A day defined by it's path, e.g.: 2014\October\23-Oct-2014

A location is fully defined when we are aware of all members' paths on each hierarchy.

An illustration of this would be to have a 3 hierarchy cube, with each hierarchy having a single level:

  • Time hierarchy with YEAR, MONTH and, DAY as levels. The hierarchy ordinal is 1.
  • Sales hierarchy with ALL and, SALESMAN as levels. The hierarchy ordinal is 2.
  • Products hierarchy with ALL and, PRODUCT as levels. The hierarchy ordinal is 3.

A fully defined location would give the path to each appropriate member for each hierarchy, such as [2014\October, ALL\John, ALL].

Range location

A range location points at one or more cells in the cube. It is used to efficiently represent a set of concrete locations. Range locations allow wild-cards in order to describe patterns. Wild-cards can be either discriminators, or an all wildcard that means any member is accepted. If a location contains either the all wildcard or a collection for one of its coordinates, it is a range location.

For example, with the 3 hierarchy cube defined above, the location [2014*, ALL{John, Sophie}, ALL\Product 1] has a all wildcard for the MONTH level on the Time hierarchy, which means that the location points to each month of year 2014, and the Sales hierarchy has a collection for the SALESMAN level, which means the location points to either John or Sophie. Resolving this range location would lead to a set of 24 point locations:

  • 2014\January, ALL\John, ALL\Product 1 ... 2014\December, ALL\John, ALL\Product 1
  • 2014\January, ALL\Sophie, ALL\Product 1 ... 2014\December, ALL\Sophie, ALL\Product 1

The ILocation interface

A location is defined in the Java code by the ILocation interface. The location can be represented as a two dimensional array:

/**
 * @return plain array representation of the location.
 */
Object[][] arrayCopy();

In the array notation, members are represented by actual Java Objects, not necessarily String. The all wildcard is represented by null and collections of coordinates are Java Collections. The first dimension of the array represents the hierarchy, while the second dimension represents that hierarchy's levels.

Note that locations do not contain the measures hierarchy, which has the ordinal 0. So hierarchy ordinals start at 1 while array indices are 0-based: the -1 shift should not be forgotten when translating the hierarchy ordinals to the array.

The array representation for "each month of 2014 for John or Sophie on Product 1" would be

new Object[][]{
        new Object[]{2014, null},
        new Object[]{ILevel.ALLMEMBER, Arrays.asList("John", "Sophie")},
        new Object[]{ILevel.ALLMEMBER, "Product 1"}}

Note Several implementations of ILocation exist, many of which do not materialize the location array for performance reasons. When manipulating an ILocation, if you only need to access some of the coordinates rather than the whole location array, it is better to use:

/**
 * @return the coordinate at the given hierarchy and given level depth. The coordinate can be a
 *         range coordinate: a <code>null</code> value means either 'ANY' or an explicit
 *         collection of values.
 */
Object getCoordinate(int hierarchyIndex, int levelIndex);

Note that in this case the parameters are named index rather than ordinal : this method uses the 0-based index in the location array (-1 shift from the hierarchy ordinal).

LocationUtil

com.quartetfs.biz.pivot.impl.LocationUtil provides a wide range of utilities to read, test, and transform locations. Be sure to check the utility class whenever you need to manipulate a location, as there may already be a utility already written for what you need.

A common usage in post-processors is the createModifiedLocation method to prefetch data from a location created by a little transformation on the location queried (for example if you want to retrieve data from the previous day).

← Continuous HandlersPost-Processors →