2 Understanding OLAP API Metadata

2.1.1 Data Preparation

A database administrator starts with a data warehouse that is organized according to certain specifications. For example, it might conform to a star schema. The requirements are described in the Oracle OLAP Application Developer's Guide.

2.1.2 Metadata Preparation

The administrator adds OLAP metadata to the OLAP Catalog. The OLAP metadata objects, which are created in this step, supply the metadata required for Oracle OLAP to access the data. These OLAP metadata objects map to MDM metadata objects in the OLAP API.

An application developer can discover the mapping of the MDM metadata objects to the relational tables and views, or create some custom MDM metadata objects, by using MTM (metadata mapping) objects. See Chapter 5, " Working with Metadata Mapping Objects", for more information on MTM objects.

The topic "OLAP Metadata Objects" briefly describes the OLAP metadata objects that a database administrator prepares for use with Oracle OLAP.

2.2.1 Dimensions in the OLAP Metadata

The following are some of the characteristics that a database administrator can specify for dimensions:

• General characteristics, such as the name of the dimension and the database schema from which its data is drawn.

• Hierarchies, which organize the elements of the dimension into parent-child relationships. A hierarchy can be level-based or value-based. In a level-based hierarchy, the parent and child elements are in different levels. In a value-based hierarchy, the database administrator has defined the parent and child relationships by values rather than levels. A simple, nonhierarchical list of elements is represented by a hierarchy that has only one level and that has no parent-child relationships defined for the elements.

• Levels, which organize the elements of a hierarchy into the levels defined for the dimension.

• Attributes, which record characteristics of the elements for the dimension. For example, attributes record the level of each element of a level-based hierarchy and the depth of that level in the hierarchy.

Typically, a database administrator specifies one or more columns in a database table to serve as the basis for each OLAP level, hierarchy, and attribute.

A database administrator creates cubes after creating dimensions. A cube is a set of dimensions that provide organizational structure for measures.

2.2.2 Measures in the OLAP Metadata

In the OLAP Catalog, a database administrator specifies that a given measure belongs to a given cube. Because a cube is a set of dimensions that provide organizational structure for measures, specifying that a given measure belongs to a given cube specifies the dimensions of that measure. This is essential information for the OLAP API, where the dimensionality of a measure is one of its most important features.

To identify the data for a measure, the database administrator typically specifies a column in a fact table where the data for the measure resides. As an alternative, the database administrator can specify a calculation or transformation that produces the data.

2.2.3 Measure Folders in the OLAP Metadata

Once a database administrator has created measures (after first creating dimensions and cubes), the next step is to create one or more groups of measures called measure folders. Typically, the measures in a given folder are related by subject matter. That is, they all pertain to the same business area. For example, there might be separate folders for financials, sales, and human resources data.

The measures in a given measure folder can belong to different cubes and they can be from more than one schema.

The database administrator must create at least one measure folder because the scope of the data that an OLAP API application can access is defined in terms of measure folders. That is, an OLAP API MdmMetadataProvider gives access only to the measures that are contained in measure folders. Of course, the dimensions of each measure are included, along with their hierarchies, levels, and attributes.

In this context, it is important to understand that measure folders can be nested. This means that a given measure folder can have subfolders that have their own measures, and even their own subfolders. Thus, a database administrator can arrange measures in a hierarchy of folders, and an OLAP API MdmMetadataProvider can give access to all of the measure folders and their subfolders.

2.3.1 Mapping of OLAP Metadata Objects to MDM objects

An application gains access to metadata objects by creating an OLAP API MdmMetadataProvider and using it to discover the available metadata objects in the data store.

The metadata objects that a database administrator specifies in the OLAP Catalog map directly to MDM metadata objects that are accessible through the MdmMetadataProvider. The following table presents a typical mapping.

This chapter describes the MDM metadata objects. For information about how an application discovers the available MDM metadata objects in the data store, see Chapter 4, " Discovering the Available Metadata". MTM objects record the mapping of MDM objects to relational tables. For information on MTM objects, see Chapter 5, " Working with Metadata Mapping Objects".

MdmSchema and MdmSource are the two subclasses of MdmObject.

2.3.2 MdmSchema Class

An MdmSchema represents a set of data that is used for navigational purposes. An MdmSchema is a container for MdmMeasure, MdmPrimaryDimension, and other MdmSchema objects. An MdmSchema is equivalent to a folder or directory that contains associated items. It does not correspond to a relational schema in the Oracle database. Instead, it corresponds to a measure folder, which can include data from several relational schemas and which was created in the OLAP Catalog by a database administrator or by the createSchema method of an MdmCustomObjectFactory.

Data that is accessible through the OLAP API is arranged under a top-level MdmSchema, which is referred to as the root MdmSchema. Under the root, there are one or more subschemas. To begin navigating the metadata, an application calls the getRootSchema method of the MdmMetadataProvider, as explained in Chapter 4, " Discovering the Available Metadata".

The root MdmSchema contains all of the MdmDimension objects that are in the data store. Most MdmPrimaryDimension objects are contained in subschemas under the root MdmSchema. However, a data store can contain a dimension that is not included in a subschema. The root MdmSchema contains dimension objects that are in subschemas as well as dimension objects that are not.

The root MdmSchema contains MdmMeasure objects only if they are not contained in a subschema. Because most MdmMeasure objects belong to a subschema, the root MdmSchema typically has no MdmMeasure objects. Therefore, the getMeasures method of the root MdmSchema typically returns an empty List object.

An MdmSchema has methods for getting all of the MdmMeasure, MdmPrimaryDimension, and MdmSchema objects that it contains. The root MdmSchema also has a method for getting the MdmMeasureDimension, whose elements are all of the MdmMeasure objects in the data store regardless of whether they belong to a subschema.

2.3.3 MdmSource Class

An MdmSource represents a measure, dimension, or other set of data (such as an attribute) that is used for analysis. MdmSource objects represent data, but they do not provide the ability to create queries on that data. Their function is informational, recording the existence, structure, and characteristics of the data. They do not give access to the data values.

To gain access to the data values for a given MdmSource, an application calls the getSource method of the MdmSource. This method returns a Source through which an application can create queries on the data represented by the MdmSource. The following line of code creates a Source from an MdmStandardDimension called mdmProductDim.

Source productDim = mdmProductDim.getSource();

A Source that is the result of the getSource method of an MdmSource is called a primary Source. An application derives new Source objects from this primary Source as it selects, calculates, and otherwise manipulates the data. Each new Source specifies a new query.

For more information about working with Source objects, see Chapter 6, " Understanding Source Objects". The rest of this chapter describes the subclasses of MdmSource.

2.6.1 MdmLevelHierarchy

MdmLevelHierarchy is a concrete subclass of MdmHierarchy. An MdmLevelHierarchy has its parent-child relationships defined between the values of the elements at different levels. The different levels of an MdmLevelHierarchy are represented by MdmLevel objects. An MdmLevelHierarchy has a tree-like structure. The elements at the lowest level of the hierarchy are the leaves, and the elements at higher levels are nodes. Nodes have children; leaves do not.

The MdmLevelHierarchy has all of the elements of the hierarchy, and each of its component MdmLevel objects has only the elements at the level it represents. Each element, except those at the highest level, can have a parent, and each element, except those at the lowest level, can have one or more children. The parent and children of an element of an MdmLevel are in other MdmLevel objects. An MdmLevelHierarchy can also represent a nonhierarchical list of elements, in which case the MdmLevelHierarchy has one MdmLevel, and both objects have the same elements. You get the levels of an MdmLevelHierarchy by calling its getLevels method.

2.6.2 MdmValueHierarchy

MdmValueHierarchy is the other concrete subclass of MdmHierarchy. An MdmValueHierarchy has parent-child relationships defined between the values of the dimension elements, and does not have the parent and child elements at different levels. An example of a value hierarchy is the employee reporting structure of a company, which can be represented with parent-child relationships but without levels. A database administrator defines a dimension as a value hierarchy in the OLAP Catalog. An application developer can define a value hierarchy with the createValueHierarchy method of an MdmCustomObjectFactory.

2.8.1 Description of an MdmMeasure

An MdmMeasure represents a set of data that is organized by one or more MdmDimension objects. The structure of the data is similar to that of a multidimensional array. Like the dimensions of an array, which provide the indexes for identifying a specific cell in the array, the MdmDimension objects that organize an MdmMeasure provide the indexes for identifying a specific value of an element of the MdmMeasure.

For example, suppose you have an MdmMeasure for product units sold data, and the data is organized by dimensions for products, times, customers, and channels (with channel representing the sales avenue, such as catalog or internet.). You can think of the data as occupying a four-dimensional array with the products, times, customers, and channels dimensions providing the organizational structure. The values of these four dimensions are indexes for identifying each particular cell in the array, which contains a single units sold data value. You must specify a value for each dimension in order to identify a value in the array. In relational terms, the MdmDimension objects constitute a compound (that is, composite) primary key for the MdmMeasure.

The values of an MdmMeasure are usually numeric, but this is not necessary.

2.8.2 Elements of an MdmMeasure

An MdmMeasure is based on an OLAP measure that was created by a database administrator in the OLAP Catalog or is created by an application developer using a method of an MdmCustomObjectFactory. In most cases, the MdmMeasure maps to a column in a fact table or to an expression that specifies a mathematical calculation or a data transformation. In many but not all cases, the MdmMeasure also maps to at least one hierarchy for each OLAP dimension of the measure, as well as an aggregation method. Oracle OLAP uses all of this information to identify the number of elements in the MdmMeasure and the value of each element.

2.9.1 Description of an MdmAttribute

An MdmAttribute represents a particular characteristic of the elements of an MdmDimension. An MdmAttribute maps one element of the MdmDimension to a particular value.

For example, mdmCustDim is an MdmPrimaryDimension for the CUSTOMER dimension, which represents a dimension of customers and is based on the columns of the GLOBAL.CUSTOMER_DIM table of a relational database. The MdmPrimaryDimension has a hierarchy that has levels that are based on shipment origination and destination values. One column in the customer table records a short value description for the customer identification value. The MdmAttribute returned by the getShortValueDescriptionAttribute method of mdmCustDim relates a short description to each the element of the dimension. The elements of the MdmAttribute have String values such as Computer Services Tokyo, Italy, and North America.

The values of an MdmAttribute might be String values (such as Italy), numeric values (such as 45), or objects (such as MdmLevel objects).

Like an MdmMeasure, an MdmAttribute has elements that are organized by its MdmDimension. Sometimes an MdmAttribute does not have a value for every element of its MdmDimension. For example, an MdmAttribute that records the name of a contact person might have values only for the SHIP_TO and WAREHOUSE levels of the SHIPMENTS_ROLLUP hierarchy of the CUSTOMER dimension, because contact information does not apply to the higher REGION and ALL_CUSTOMERS levels. If an MdmAttribute does not apply to an element of an MdmDimension, then the MdmAttribute element value for that element is null.

Some MdmAttribute objects provide a mapping that is one-to-many, rather than one-to-one. Therefore, a given element in an MdmDimension might map to a whole set of MdmAttribute elements. For example, the MdmAttribute that serves as the ancestors attribute for an MdmHierarchy maps each MdmHierarchy element to its set of ancestor MdmHierarchy elements.

Some attributes apply generally to the all of elements of an MdmPrimaryDimension. You can get the MdmAttribute objects for those attributes with the getAttributes method of the MdmPrimaryDimension. Other attributes relate only to an MdmHierarchy, such as the parent attribute, or an MdmLevelHierarchy, such as the level depth attribute. You get the MdmAttribute objects for those attributes with the getParentAttribute method of the MdmHierarchy or the getLevelDepthAttribute method of the MdmLevelHierarchy.

2.9.2 Elements of an MdmAttribute

An MdmAttribute is based on an attribute that was specified for a dimension, hierarchy, or level by a database administrator in the OLAP Catalog or that was specified by an MtmValueExpression for a custom MdmAttribute created by an application.

The following table lists the values of elements of a Source object that represents the elements of a hierarchy of an MdmPrimaryDimension of products. The table also lists the values of the Source objects for two MdmAttribute objects that are dimensioned by the MdmPrimaryDimension. One attribute is the short description attribute for the dimension. Each element of the dimension has a related short description. The other is a custom attribute that relates a color to the values of elements at the ITEM level, which is the lowest level of the hierarchy. The values of the color MdmAttribute are null for the aggregate TOTAL_PRODUCT, CLASS, and FAMILY levels. In the table, null values appear as NA.

2.10.1 Data Type of MDM Metadata Objects

The concept of data type is a familiar one in computer languages and database technology. It is common to categorize data into types such as integer, Boolean, and String.

The OLAP API implements the concept of data type through the FundamentalMetadataObject and FundamentalMetadataProvider classes. Every data type recognized by the OLAP API is represented by a FundamentalMetadataObject, and you obtain this object by calling a method of a FundamentalMetadataProvider.

The following table lists the most familiar OLAP API data types. For each data type, the table presents a description of the FundamentalMetadataObject that represents the data type and the name of the method of FundamentalMetadataProvider that returns the object. The OLAP API data types appear in regular typeface, instead of monospace typeface, to distinguish them from java.lang data type classes.

In addition to these familiar data types, the OLAP API includes two generalized data types (which represent groups of the familiar data types) and two data types that represent the absence of values. The following table lists these additional data types.

When an MDM metadata object, such as an MdmMeasure, has a given data type, this means that each of its elements conforms to that data type. If the data type is numeric, then the elements also conform to the generalized Number data type, as well as to the specific data type (Double, Float, Integer, or Short). The elements of any MDM metadata object conform to the Value data type, as well as to their more specific data type, such as Integer or String.

If the elements of an object represent a mixture of several numeric and non-numeric data types, then the data type is only Value. The object has no data type that is more specific than that.

The MDM metadata objects for which data type is relevant are MdmSource objects, such as MdmMeasure, MdmLevelHierarchy, and MdmLevel. The typical data type of an MdmMeasure is one of the numeric data types; the typical data type of an MdmLevelHierarchy or MdmLevel is String.

2.10.2 Getting the Data Type of an MdmSource

If you have obtained an MdmSource from the data store, and you want to find the data type of its elements, then you call its getDataType method. This method returns a FundamentalMetadataObject.

To find the OLAP API data type that is represented by the returned FundamentalMetadataObject, you compare it to the FundamentalMetadataObject for each OLAP API data type. That is, you compare it to the return value of each of the data type methods in FundamentalMetadataProvider.

The following sample method returns a String that indicates the data type of the MdmSource that is passed in as a parameter. Note that this code creates a FundamentalMetadataProvider by calling a method of a DataProvider. Getting a DataProvider is described in Chapter 4, " Discovering the Available Metadata". The dp object is the DataProvider.

public String getDataType(DataProvider dp, MdmSource metaSource) 
{
   String theDataType = null;
   FundamentalMetadataProvider fmp =
                              dp.getFundamentalMetadataProvider();

   if (fmp.getBooleanDataType() == metaSource.getDataType())
       theDataType = "Boolean";
    else if (fmp.getDateDataType() == metaSource.getDataType())
       theDataType = "Date";
    else if (fmp.getDoubleDataType() == metaSource.getDataType())
       theDataType = "Double";
    else if (fmp.getFloatDataType() == metaSource.getDataType())
       theDataType = "Float";
    else if (fmp.getIntegerDataType() == metaSource.getDataType())
       theDataType = "Integer";
    else if (fmp.getShortDataType() == metaSource.getDataType())
       theDataType = "Short";
    else if (fmp.getStringDataType() == metaSource.getDataType())
       theDataType = "String";
    else if (fmp.getNumberDataType() == metaSource.getDataType())
       theDataType = "Number";
    else if (fmp.getValueDataType() == metaSource.getDataType())
       theDataType = "Value";

    return theDataType;
    }

2.10.3 Type of MDM Metadata Objects

An MDM metadata object, such as an MdmSource, is a collection of elements. Its type (as opposed to its data type) is another metadata object from which the metadata object draws its elements. In other words, the elements of a metadata object correspond to a subset of the elements in its type. There can be no element in the metadata object that does not match an element of its type.

Consider the following example of a MdmPrimaryDimension called mdmCustDim, which has the OLAP API data type of String. The mdmCustDim dimension has a hierarchy, which is an MdmLevelHierarchy object called mdmShipmentsRollup), which in turn has levels, which are MdmLevel objects. The MdmLevelHierarchy and the MdmLevel objects represent subsets of the elements of the MdmPrimaryDimension. In the following list, the hierarchy and the levels are indented under the MdmPrimaryDimension to which they belong.

mdmCustDim
      mdmShipmentsRollup
            mdmTotalCust
            mdmRegion
            mdmWarehouse
            mdmShipTo

Because of the hierarchical structure, mdmWarehouse (for example) draws its elements from the elements of mdmShipmentsRollup. That is, the set of elements for mdmWarehouse corresponds to a subset of elements from mdmShipmentsRollup, and mdmShipmentsRollup is the type of mdmWarehouse.

Similarly, mdmShipmentsRollup is a component hierarchy of mdmCustDim. Therefore, mdmShipmentsRollup draws its elements from mdmCustDim, which is its type.

However, mdmCustDim is not a component of any other object. It represents the entire dimension. The pool of elements from which mdmCustDim draws its elements is the entire set of possible String values. Therefore, the type of mdmCustDim is the FundamentalMetadataObject that represents the OLAP API String data type. In the case of mdmCustDim, the type and the data type are the same.

The following list presents the types that are typical for the most common MdmSource objects:

• The type of an MdmLevel is the MdmLevelHierarchy to which it belongs.

• The type of a MdmHierarchy is the MdmPrimaryDimension to which it belongs.

• The type of an MdmPrimaryDimension is the FundamentalMetadataObject that represents its OLAP API data type. Typically, this is the String data type.

• The type of an MdmMeasure is the FundamentalMetadataObject that represents its OLAP API data type. Typically, this is one of the OLAP API numeric data types.

2.10.4 Getting the Type of an MdmSource

If you have obtained an MdmSource from the data store, and you want to find out its type, you call its getType method. This method returns the object that is the type of the MdmSource object.

For example, the following Java statement obtains the type of the MdmLevel named mdmWarehouse.

MetadataObject mdmWarehouseType = mdmWarehouse.getType();