Selecting Elements Based on Key Values

Why you need to specify values for the keys of a Source

As mentioned in "What objects represent queries?", even though it helps to think of a Source object as a tabular or dimensional result set, a Source actually is not a result set. Instead, a Source object is a specification for a query that defines a result set. As part of this specification, a Source object keeps track of the keys for which values have been specified. Looking at keys from this point of view, you can say that a Source object has two different types of keys:

• Inputs which are keys for which values have not yet been specified. When a primary Source object has other Source objects that act as its keys, these Source objects are always inputs. Thus, the query specification represented by a dimensioned primary Source or any other Source that has an input is incomplete. You cannot create a Cursor for this type of Source and, consequently, you cannot retrieve the query specified by the Source.

• Outputs which are keys for which values have been specified. When a Source has only outputs, the primary key to its elements are fully specified. The query that this type of Source specifies is determinable. You can create a Cursor for this type of Source and use the Cursor to retrieve the data set specified by the Source.

If you want to create a Cursor on a Source object, all of the keys of the Source must be outputs. Consequently, to display a primary dimensional Source, you must first specify values for the keys of that Source. Specifying values for the keys of a Source is called changing inputs to outputs.

How to turn inputs into outputs?

The need to specify values for the keys of a dimensional Source with inputs is so universal, that the OLAP API has a join shortcut method to support it. To specify values for the keys of a dimensional Source, thereby changing an input to an output, use the following join method where the original Source is the Source object that has the input that you want to become an output and the joined Source is the input you want to change.

join (Source joined)

This is a shortcut for the following join method.

join (joined, emptySource, Source.COMPARISON_RULE_REMOVE, true);

Note that the comparison Source is the empty Source that has no elements. Consequently, even though the COMPARISON_RULE_REMOVE constant is specified, no elements are removed as a result of the comparison. Also, because the visible flag is set to true, the joined Source becomes an output of the new Source.

Additionally, since many of the methods of Source class and its subclasses are actually shortcut and convenience methods that implicitly call the join method, some of these methods also change inputs to outputs.

How does the structure of a dimensional Source determine its processing?

The way a dimensional Source is processed is determined by its structure. When a Source has both inputs and outputs, its elements (tuples) are identified by the set of its input and output values. In this case, each set of possible input values typically identifies a number of elements (tuples). Within this subset of data, the tuples are arranged by output. When a Source has inputs, many Source methods work on this subset of data.

For example, when a Cursor is opened on a Source, the OLAP service loops over its outputs in order to produce the data, but it (arbitrarily) qualifies away any of its inputs. Additionally, the OLAP service loops over the outputs of a Source when it processes any aggregation methods like average and total. In this sense, moving a Source from the list of inputs to the list of outputs is similar to moving a column out of the GROUP BY list in SQL.

For more information on the structure of a Source with inputs, see "Finding the position of elements"; for more information on fastest-varying and slowest-varying columns, see "What is the effect of input-output order on Source structure?".

What is the effect of input-output order on Source structure?

The structure of a dimensioned Source is determined by the order in which you turn the inputs of the Source into outputs. The fastest-varying column is always the column that contains the elements of the Source. For a Source that has outputs, the first output that was created is the fastest-varying key column; the last output that was created is the slowest-varying key column.

When you string two join methods together in a single statement, the first join (reading left to right) is processed first. Consequently, when creating a single statement containing several join methods, make sure that the input that you want to be the fastest-varying of the new Source is the joined Source in the first join in the statement.

You can retrieve the inputs of a Source using the getInputs method that the Source class inherits from the DataDescriptor class. You can retrieve the outputs of a Source using the getOutputs method that the Source class inherits from the DataDescriptor class.

Example: Effect of input-output order on Source structure

Assume that you have a primary Source named unitCost that you created from a MdmMeasure object named mdmUnitCost. The Source named unitCost has inputs of timesDim and productsDim, and no outputs.The timesDim and productsDim Source objects do not have any inputs or outputs. The order in which you turn the inputs of unitCost into outputs determines the structure of a Source on which you can create a Cursor.

Joining first to timesDim

Assume also that you issue the following code to turn the inputs of the primary Source named unitCost into outputs.

Source newSource = unitCost.join(timesDim).join(productsDim);

This code strings two join methods together. Because unitCost.join(timesDim) is processed first, the key values for timesDim are the first key values specified. You can also say that timesDim is the first output defined for the new Source. After the first join is processed, the query specification represented by the resulting unnamed Source consists of the name of its input (that is, productsDim) and both the name and the element values of its output (that is, timesDim). You can think of the new unnamed Source as having the structure depicted below.

Output2	Output1	Element
productsDim	timesDim	unit_Cost
Boys
...
49780
...

After the second join is processed, the query specification represented by newSource consists of the names and the element values of both of its output (that is, timesDim and productsDim). Since timesDim was the first key for which values were specified, it is the fastest-varying output and the new Source has the structure depicted below.

Output2	Output1	Element
productsDim	timesDim	unit_Cost
Boys	1998	4,000
Boys	...	...
Boys	31-DEC-01	10
...	...	...
49780	1998	500
49780	...	...
49780	31-DEC-01	9

Joining first to productsDim

Assume that you issue the following code to turn the inputs of unitCost into outputs.

Source newSource = unitCost.join(productsDim).join(timesDim);

This code strings two join methods together. Because unitCost.join(productsDim) is processed first, productsDim is the first output defined for the new Source. Consequently, productsDim is the fastest-varying output and the new Source has the structure depicted below.

Output2	Output1	Element
timesDim	productsDim	unitCost
1998	Boys	4,000
1998	...	...
1998	49780	500
...	...	...
31-DEC-01	Boys	10
31-DEC-01	...	...
31-DEC-01	48780	9