You use the Flex OLAPDataGrid control to display an OLAP data grid. The following image shows the OLAPDataGrid control displaying the aggregated sales information for product and quarter:

Like all Flex data grid controls, the OLAPDataGrid control is designed to display data in a two-dimensional representation of rows and columns.

You can modify this example to compare quarterly sales from two different years, as the following example shows:

In the previous figure, the columns of the OLAPDataGrid control show a hierarchy of information for year and quarter. You can add multiple-level hierarchies for both the columns and the rows of the control.

The following figure shows the data flow that you use to aggregate your data for display in the OLAPDataGrid control:

The following steps describe this process in more detail:

1. Start with flat data, which is typically data arranged as a set of records where each record contains the same data fields. For example, you might start with flat data from a spreadsheet, or with data from a table of a relational database.

   The following code shows an example format of flat data:

     data:Object = { 
    	customer:"AAA",  
    	product:"FlexJS", 
    	quarter:"Q1" 
    	revenue: "100.00"  
    }

2. Define an OLAP schema that describes how your data gets transformed from a flat representation into an OLAP cube. An OLAP schema defines the representation of your flat data in an OLAP cube, and defines how to aggregate your data for an OLAP query.

   An OLAP cube is analogous to a table in a relational database. But whereas a table typically has two dimensions (row and column), an OLAP cube can have any number of dimensions. In this example, the cube has three dimensions: customer, product, and quarter. Every possible set of values for customer, product, and quarter defines a unique point in the cube. The value at each point in the cube is the sales revenue for that set of values of customer, product, and quarter.

3. Create queries to extract aggregated data from the OLAP cube for display in the OLAPDataGrid control.

   After your data is in an OLAP cube, you write queries to extract aggregated data for display in the OLAPDataGrid control. You can write multiple queries to create different types of data aggregations.

4. Use the query results as input to the OLAPDataGrid control to display the results.

An OLAP cube can have any number of dimensions. In its simplest form, the dimensions of an OLAP cube correspond to a field of the flat data set. For example, you have flat data that contains three fields:

  data:Object = { 
 	product:"FlexJS" 
 	quarter :"Q1" 
 	revenue: "100.00",  
 }

The data fields of each record can contain the following values:

• The product field can have the values: FlexJS, Flex, Installer, and TourDeFlex.

• The quarter field can have the values: Q1, Q2, Q3, and Q4.

• The revenue field contains the sales, in dollars, of the product for the quarter.

To aggregate your data, you create an OLAP cube with two dimensions: quarter and product. The value along each dimension of the cube is called a member. For example, the product dimension of the cube has the following members: FlexJS, Flex, Installer, and TourDeFlex. For the quarter dimension, the members are Q1, Q2, Q3, and Q4.

The value at any point in the cube defined by the two dimensions is called a measure of the cube. For example, the measure at the point in the cube defined by (Q1, FlexJS) is 100.00. A schema can define one or more measures for a single point in the OLAP cube.

Flex supports only numeric values for the measure of a cube. The advantage of numeric values is that they can be easily aggregated for display in the OLAPDataGrid control. Some typical aggregation types include sum, average, minimum, and maximum. For example, you specify the aggregation method of the revenue measure as SUM. You then extract sales information from the cube for FlexJS. The aggregated sales data contains the sum of all FlexJS sales for each quarter.

To convert flat data into an OLAP cube, you create an OLAP schema that defines the dimensions of the cube, the fields of the flat data that supply the members along each dimension, and the fields of the flat data that supply the measure for any point in the cube.

For example, you have the following flat data that contains sales records:

  data:Object = { 
 	customer:"AAA",  
 	product:"FlexJS", 
 	quarter:"Q1" 
 	revenue: "100.00"  
 }

The following example shows the definition for an OLAPCube that includes the definition of the OLAP schema used to represent this data in the cube. This schema defines a three-dimensional OLAP cube based on the customer, product, and quarter fields of the data.

<mx:OLAPCube name="FlatSchemaCube" 
    dataProvider="{flatData}" 
    id="myMXMLCube" 
    complete="runQuery(event);"> 
     
    <mx:OLAPDimension name="CustomerDim"> 
        <mx:OLAPAttribute name="Customer" dataField="customer"/> 
        <mx:OLAPHierarchy name="CustomerHier" hasAll="true"> 
            <mx:OLAPLevel attributeName="Customer"/> 
        </mx:OLAPHierarchy> 
    </mx:OLAPDimension> 
    
    <mx:OLAPDimension name="ProductDim"> 
        <mx:OLAPAttribute name="Product" dataField="product"/> 
        <mx:OLAPHierarchy name="ProductHier" hasAll="true"> 
            <mx:OLAPLevel attributeName="Product"/> 
        </mx:OLAPHierarchy> 
    </mx:OLAPDimension> 
 
    <mx:OLAPDimension name="QuarterDim"> 
        <mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
        <mx:OLAPHierarchy name="QuarterHier" hasAll="true"> 
            <mx:OLAPLevel attributeName="Quarter"/> 
        </mx:OLAPHierarchy> 
    </mx:OLAPDimension> 
    
    <mx:OLAPMeasure name="Revenue" 
        dataField="revenue" 
        aggregator="SUM"/> 
</mx:OLAPCube>

Notice that in this schema:

• All dimensions are defined first, and then all measures.

• The first line of each dimension associates a data field of the flat data with an OLAPAttribute instance. You then use the OLAPLevel.attributeName property to associate the attribute with a level of the dimension to populate the members of the dimension. For example, in this schema you populate the Customer level of the CustomerDim dimension with the data from the customer field of the data.

• A dimension of an OLAP schema always contains a hierarchy of one or more levels. In this schema, the hierarchy of each dimension contains only a single level corresponding to a field of the flat data. This is the simplest form of a dimension. Other schemas could define multiple levels in a hierarchy to create a complex dimension. For more information, see Creating an OLAP schema.

• A measure definition specifies the data field of the flat data that contains the value for each point in the OLAP cube, and how the measure is aggregated by an OLAP query. In this example, you aggregate revenue by summing it. That means all queries of this OLAP cube will return revenue summations. Other types of aggregation methods include maximum, minimum, and average.

• This definition of the OLAPCube specifies an event handler for the complete event. You cannot invoke a query on the cube until it completes initialization, which is signalled by the cube when it dispatches the complete event.

Based on the requirements of your application, you might create multiple OLAP cubes from the same flat data set, where each cube uses a different schema to create its own arrangement of dimensions and measures. For more information and examples of OLAP schemas, see Creating an OLAP schema.

OLAP queries extract aggregated data from an OLAP cube for display in an OLAPDataGrid control. The query specifies the dimensions that define the characteristics of the query, and the measure or measures aggregated to create the query results.

In the previous section, you defined an OLAP schema for sales information where the schema defines CustomerDim, ProductDim, and QuarterDim dimensions, and a single measure for revenue aggregated by the SUM aggregation method. Therefore, you can create a query to sum revenue by the following criteria:

• Product for each quarter

• Customer for each product

• Customer for each quarter

• Any other combination of members from each dimension

You construct a query in ActionScript as an instance of the OLAPQuery class, and then execute the query by calling the OLAPCube.execute() method, which returns an instance of the AsyncToken class.

A query is required to have two axes, a row axis and a column axis, of type IOLAPQueryAxis. The row axis defines the data aggregation information for each row of the OLAPDataGrid control, and the column axis defines the data aggregation information for each column of the control.

You use the OLAPSet class to specify the data aggregation information for each axis, as the following example shows:

  // Create an instance of OLAPQuery to represent the query.  
 var query:OLAPQuery = new OLAPQuery; 
 	 
 // Get the row axis from the query instance. 
 var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 // Create an OLAPSet instance to configure the axis. 
 var productSet:OLAPSet = new OLAPSet; 
 // Add the Product to the row to aggregate data  
 // by the Product dimension. 
 productSet.addElements( 
 	cube.findDimension("ProductDim").findAttribute("Product").children); 
 // Add the OLAPSet instance to the axis. 
 rowQueryAxis.addSet(productSet); 
 	 
 // Get the column axis from the query instance, and configure it 
 // to aggregate the columns by the Quarter dimension.  
 var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 var quarterSet:OLAPSet= new OLAPSet; 
 quarterSet.addElements( 
 	cube.findDimension("QuarterDim").findAttribute("Quarter").children); 
 colQueryAxis.addSet(quarterSet); 
  
 // Execute the query. 
 var token:AsyncToken = cube.execute(query); 
 // Set up handlers for the query results. 
 token.addResponder(new AsyncResponder(showResult, showFault));

Notice that in this query:

• You initialize each axis by calling the OLAPQuery.getAxis() method.

• You configure each OLAPSet instance by calling the OLAPSet.addElements() method to specify the information used to populate the axis.

• You set up two functions to handle the query result defined by the AsyncToken class. In this example, the function showResult() handles the query results when the query succeeds, and the function showFault() handles any errors detected during query execution. For more information on using the AsyncToken class, see Executing a query and returning the results to an OLAPDataGrid control.

For more information and examples of OLAP queries, see Creating OLAP queries.

You use the OLAPDataGrid control to display the results of an OLAP query. The OLAPDataGrid control is a subclass of the AdvancedDataGrid control and inherits much of its functionality. However, because of the way you pass data to the OLAPDataGrid control, it has several differences from the AdvancedDataGrid control:

• Column dragging is not allowed in the OLAPDataGrid control.

• You cannot edit cells in the OLAPDataGrid control because cell data is a result of a query and does not correspond to a single data value in the OLAP cube.

• You cannot sort columns by clicking on headers in the OLAPDataGrid control. Sorting is supported at the dimension level so that you can change the order of members of that dimension. Note that you can only use sorting while preparing the query, and then use it to get the member names displayed along the rows and column headers.

You populate an OLAPDataGrid control with data by setting its data provider to an instance of the OLAPResult class, which contains the results of an OLAP query. For a complete example that uses this control, see Example using the OLAPDataGrid control.

The following example shows the complete code for creating the OLAPDataGrid control that appears in the section About OLAP data grids. This example aggregates product sales by quarter. The example uses flat data from the dataIntro.as file, which contains sales records in the following format:

  data:Object = { 
 	customer:"AAA",  
 	product:"FlexJS", 
 	quarter:"Q1" 
 	revenue: "100.00"  
 }

The following code implements this example:

<?xml version="1.0"?> 
<!-- olapdatagrid/OLAPDG_Intro.mxml --> 
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
        creationComplete="creationCompleteHandler();"> 
 
    <fx:Script> 
      <![CDATA[ 
        import mx.rpc.AsyncResponder; 
        import mx.rpc.AsyncToken; 
        import mx.rpc.events.FaultEvent; 
        import mx.olap.OLAPQuery; 
        import mx.olap.OLAPSet; 
        import mx.olap.IOLAPQuery; 
        import mx.olap.IOLAPQueryAxis; 
        import mx.olap.IOLAPCube; 
        import mx.olap.OLAPResult; 
        import mx.events.CubeEvent; 
        import mx.controls.Alert; 
        import mx.collections.ArrayCollection; 
        
        include "dataIntro.as" 
 
        private function creationCompleteHandler():void { 
            // You must initialize the cube before you 
            // can execute a query on it. 
            myMXMLCube.refresh(); 
        } 
 
        // Create the OLAP query. 
        private function getQuery(cube:IOLAPCube):IOLAPQuery { 
            // Create an instance of OLAPQuery to represent the query. 
            var query:OLAPQuery = new OLAPQuery; 
            
            // Get the row axis from the query instance. 
            var rowQueryAxis:IOLAPQueryAxis = 
                query.getAxis(OLAPQuery.ROW_AXIS); 
            // Create an OLAPSet instance to configure the axis. 
            var productSet:OLAPSet = new OLAPSet; 
            // Add the Product to the row to aggregate data 
            // by the Product dimension. 
            productSet.addElements( 
                cube.findDimension("ProductDim").findAttribute("Product").children); 
            // Add the OLAPSet instance to the axis. 
            rowQueryAxis.addSet(productSet); 
            
            // Get the column axis from the query instance, and configure it 
            // to aggregate the columns by the Quarter dimension. 
            var colQueryAxis:IOLAPQueryAxis = 
                query.getAxis(OLAPQuery.COLUMN_AXIS);         
            var quarterSet:OLAPSet= new OLAPSet; 
            quarterSet.addElements( 
                cube.findDimension("QuarterDim").findAttribute("Quarter").children); 
            colQueryAxis.addSet(quarterSet); 
            
            return query;       
        } 
 
        // Event handler to execute the OLAP query 
        // after the cube completes initialization. 
        private function runQuery(event:CubeEvent):void { 
            // Get cube. 
            var cube:IOLAPCube = IOLAPCube(event.currentTarget); 
            // Create a query instance. 
            var query:IOLAPQuery = getQuery(cube); 
            // Execute the query. 
            var token:AsyncToken = cube.execute(query); 
            // Set up handlers for the query results. 
            token.addResponder(new AsyncResponder(showResult, showFault)); 
        } 
 
        // Handle a query fault. 
        private function showFault(error:FaultEvent, token:Object):void { 
            Alert.show(error.fault.faultString); 
        } 
 
        // Handle a successful query by passing the query results to 
        // the OLAPDataGrid control.. 
        private function showResult(result:Object, token:Object):void { 
            if (!result) { 
                Alert.show("No results from query."); 
                return; 
            } 
            myOLAPDG.dataProvider= result as OLAPResult;            
        }        
      ]]> 
    </fx:Script> 
 
    <fx:Declarations> 
        <mx:OLAPCube name="FlatSchemaCube" 
            dataProvider="{flatData}" 
            id="myMXMLCube" 
            complete="runQuery(event);"> 
         
            <mx:OLAPDimension name="CustomerDim"> 
                <mx:OLAPAttribute name="Customer" dataField="customer"/> 
                <mx:OLAPHierarchy name="CustomerHier" hasAll="true"> 
                    <mx:OLAPLevel attributeName="Customer"/> 
                </mx:OLAPHierarchy> 
            </mx:OLAPDimension> 
    
            <mx:OLAPDimension name="ProductDim"> 
                <mx:OLAPAttribute name="Product" dataField="product"/> 
                <mx:OLAPHierarchy name="ProductHier" hasAll="true"> 
                    <mx:OLAPLevel attributeName="Product"/> 
                </mx:OLAPHierarchy> 
            </mx:OLAPDimension> 
 
            <mx:OLAPDimension name="QuarterDim"> 
                <mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
                <mx:OLAPHierarchy name="QuarterHier" hasAll="true"> 
                    <mx:OLAPLevel attributeName="Quarter"/> 
                </mx:OLAPHierarchy> 
            </mx:OLAPDimension> 
    
            <mx:OLAPMeasure name="Revenue" 
                dataField="revenue" 
                aggregator="SUM"/> 
        </mx:OLAPCube> 
    </fx:Declarations> 
 
    <mx:OLAPDataGrid id="myOLAPDG" width="100%" height="100%"/> 
</s:Application>

In MXML, you can define an OLAP schema as part of the definition of an OLAPCube instance. In MXML, you declare an OLAPCube in an <fx:Declarations> tag because it is not a visual component.

Typically, you set any properties of the OLAPCube instance as tag attributes, and set the OLAPCube.dimensions and OLAPCube.measures properties as child tags, as the following example shows:

<fx:Declarations> 
	  <mx:OLAPCube name="FlatSchemaCube"  
 		dataProvider="{flatData}"  
 		id="myMXMLCube" 
 		complete="runQuery(event);"> 
  
 		<!-- Define dimensions. --> 
 		<mx:OLAPDimension ... /> 
  
	 	<mx:OLAPDimension ... />		 
	 	... 
  
	 	<!-- Define measures. --> 
	 	<mx:OLAPMeasure ... /> 
	 	... 
	 </mx:OLAPCube> 
</fx:Declarations>

The order of the OLAPDimension and OLAPMeasure definitions is not important, but you should not place OLAPMeasure definitions between OLAPDimension definitions.

As part of creating an OLAP schema, you specify the data field that provides the value of the measure for each point in the cube. The measure corresponds to the data value at that point in the OLAP cube. For example, if you define a schema for sales information, you might specify as a measure of the cube the revenue for a product, and the aggregation type as SUM.

A schema can define one or more measures for a single point in the OLAP cube. The first measure in the schema is called the default measure, and is the measure returned by an OLAP query when you do not explicitly specify the measure to return. For more information on selecting a specific measure, see Creating a query using a nondefault measure.

The following example shows a section of an MXML schema definition that specifies two measures for the schema:

  <mx:OLAPMeasure name="Revenue" dataField="revenue" aggregator="SUM"/> 
 <mx:OLAPMeasure name="Cost" dataField="cost" aggregator="SUM"/>

When creating a schema, you specify the name of the measure, the data field in the input flat data that contains the data for the measure, and an aggregation method of the measure. In this example, the aggregation method is SUM. That means when you create an OLAP query for a measure, the query sums all revenue fields to generate the values displayed by the OLAPDataGrid control. You could use this schema to define a cube so that you can total sales and cost information for products, regions, and other characteristics of your data.

To aggregate the revenue data using a different aggregation method, such as average or maximum, create another schema to define a second OLAP cube. The following example shows a section of another MXML schema definition that specifies the aggregation method as MAX for the sales data and MIN for the cost data:

  <mx:OLAPMeasure name="Revenue" dataField="revenue" aggregator="MAX"/> 
 <mx:OLAPMeasure name="Cost" dataField="cost" aggregator="MIN"/>

You should take care in how you define your schema because it can limit the types of queries that you can run on it, or the level of detail at which you can create aggregations.

An OLAPSchema instance can define any number of dimensions, limited only by your input data. A dimension can be a simple dimension with a single level, or it can be a complex dimension with multiple levels. The dimension of a schema always has the same basic form:

  <mx:OLAPDimension name="QuarterDim"> 
 	<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 	... 
 	<mx:OLAPHierarchy name="QuarterHier" hasAll="true"> 
 		<mx:OLAPLevel attributeName="Quarter"/> 
 		... 
 	</mx:OLAPHierarchy>  
 </mx:OLAPDimension>

Notice that in this schema:

• The dimension first uses OLAPAttribute class to specify the data fields of the input data set used to populate the members of the dimension.

  The dimension defines an instance of the OLAPHierarchy class. Therefore, a dimension is always assumed to contain a hierarchy of levels, even if that hierarchy contains only a single level.

• The dimension specifies one or more instances of the OLAPLevel class to associate a field of the input with the dimension.

  <mx:OLAPDimension name="CustomerDim"> 
 	<mx:OLAPAttribute name="Customer" dataField="customer"/> 
 	<mx:OLAPHierarchy name="CustomerHier" hasAll="true"> 
 		<mx:OLAPLevel attributeName="Customer"/> 
 	</mx:OLAPHierarchy> 
 </mx:OLAPDimension>

  <mx:OLAPCube name="FlatSchemaCube"  
 	dataProvider="{flatData}"  
 	id="myMXMLCube"> 
 	 
 	<mx:OLAPDimension name="TimeDim"> 
 		<mx:OLAPAttribute name="Year" dataField="year"/> 
 		<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 		<mx:OLAPHierarchy name="Time-PeriodHier" hasAll="true"> 
 			<mx:OLAPLevel attributeName="Year"/> 
 			<mx:OLAPLevel attributeName="Quarter"/> 
 		</mx:OLAPHierarchy>  
 	</mx:OLAPDimension> 
  
 	<mx:OLAPMeasure name="Revenue"dataField="revenue" aggregator="SUM"/> 
 </mx:OLAPCube>

  <mx:OLAPDimension name="TimeDim"> 
 	<mx:OLAPAttribute name="Year" dataField="year"/> 
 	<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 	<mx:OLAPAttribute name="Month" dataField="month"/> 
 	<mx:OLAPHierarchy name="Time-PeriodHier" hasAll="true"> 
 		<mx:OLAPLevel attributeName="Year"/> 
 		<mx:OLAPLevel attributeName="Quarter"/> 
 		<mx:OLAPLevel attributeName="Month"/> 
 	</mx:OLAPHierarchy>  
 </mx:OLAPDimension>

Most of the OLAP schemas shown so far have been defined in the following form:

  <mx:OLAPDimension name="TimeDim"> 
 	<mx:OLAPAttribute name="Year" dataField="year"/> 
 	<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 	<mx:OLAPHierarchy name="Time-PeriodHier" hasAll="true"> 
 		<mx:OLAPLevel attributeName="Year"/> 
 		<mx:OLAPLevel attributeName="Quarter"/> 
 	</mx:OLAPHierarchy>  
 </mx:OLAPDimension>

In this schema, the hierarchy sets the OLAPHierarchy.hasAll property to true to create a default member for the hierarchy. The default member is created automatically for the hierarchy and contains an aggregation of all levels in the hierarchy. In the previous schema, the default member contains an aggregation of the measure of the schema for all years and all quarters.

The default member is used by OLAP queries when you do not specify any criteria to aggregate the dimension. For example, your OLAP schema contains a ProductDim, TimeDim, and CustomerDim dimension. You then write a query to extract data by product and customer, but omit any specification in the query for time. The OLAP query automatically uses the default member of the dimension to aggregate the information for the TimeDim dimension.

The default value of the OLAPHierarchy.hasAll property is true. If you set it to false, the OLAP query uses the first level in the hierarchy to aggregate the dimension. The following schema sets the hasAll property to false:

  <mx:OLAPDimension name="TimeDim"> 
 	<mx:OLAPAttribute name="Year" dataField="year"/> 
 	<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 	<mx:OLAPHierarchy name="Time-PeriodHier" hasAll="false"> 
 		<mx:OLAPLevel attributeName="Year"/> 
 		<mx:OLAPLevel attributeName="Quarter"/> 
 	</mx:OLAPHierarchy>  
 </mx:OLAPDimension>

Because the hasAll property is false, an OLAP query automatically aggregates the data in the dimension by the Year level when you omit the TimeDim dimension from the query.

By default, the OLAP cube adds a member to the dimension named (All) to represent the default member. You can use the OLAPHierarchy.allLevelName property to specify a different name, as the following example shows:

  <mx:OLAPDimension name="TimeDim"> 
 	<mx:OLAPAttribute name="Year" dataField="year" allLevelname="AllTime"/> 
 	<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 	<mx:OLAPHierarchy name="Time-PeriodHier" hasAll="true"> 
 		<mx:OLAPLevel attributeName="Year"/> 
 		<mx:OLAPLevel attributeName="Quarter"/> 
 	</mx:OLAPHierarchy>  
 </mx:OLAPDimension>

When you execute an OLAP query, you choose whether or not to include the default member in the query results. For more information, see Using the default member in a query.

The process of creating a query has the following steps:

1. Prepare the cube for a query. For more information, see Preparing a cube for a query.

2. Define an instance of the OLAPQuery class to represent the query. For more information, see Creating a query axis.

3. Define an instance of the OLAPQueryAxis class to represent the rows of the query.

4. Define an instance of the OLAPSet class to define the members that provide the row axis information. For more information, see Writing a query for a simple OLAP cube and Writing a query for a complex OLAP cube.

5. Define an instance of the OLAPQueryAxis class to represent the columns of the query.

6. Define an instance of the OLAPSet class to define the members that provide the axis column information.

7. Optionally define an instance of the OLAPQueryAxis class to specify a slicer axis. For more information, see Creating a slicer axis

8. Define an instance of the OLAPSet class to define the members that provide the slicer axis information.

9. Execute the query on the cube by calling OLAPCube.execute(). For more information, see Executing a query and returning the results to an OLAPDataGrid control.

10. Pass the query results to the OLAPDataGrid control.

Before you can run the first query on an OLAP cube, you must call the OLAPCube.refresh() method to initialize the cube from the input data. Upon completion of cube initialization, the OLAP cube dispatches the complete event to signal that the cube is ready for you to query.

You can use event handlers to initialize the cube and to invoke the query. The following example uses the application's creationComplete event to initialize the cube, and then uses the cube's complete event to execute the query:

  <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
	xmlns:mx="library://ns.adobe.com/flex/mx" 
	xmlns:s="library://ns.adobe.com/flex/spark" 
 	creationComplete="creationCompleteHandler();"> 
  
 <fx:Script> 
 	<![CDATA[ 
  
 		private function creationCompleteHandler():void { 
 			// You must initialize the cube before you  
 			// can execute a query on it. 
 			myMXMLCube.refresh(); 
 		} 
  
 		// Event handler to execute the OLAP query  
 		// after the cube completes initialization. 
 		private function runQuery(event:CubeEvent):void { 
 			... 
 		} 
 	]]> 
 </fx:Script> 
<fx:Dclarations> 	 
	 <mx:OLAPCube name="FlatSchemaCube"  
	 	dataProvider="{flatData}"  
	 	id="myMXMLCube" 
	 	complete="runQuery(event);"> 
	 	... 
	 </mx:OLAPCube> 
</fx:Declarations> 
 
... 
  </s:Application>

The following example shows an OLAPDataGrid control containing the results of a query for the sales of different products for different quarters:

To create a query, you must define a row axis, a column axis, and optionally a slicer axis, where each axis is an instance of the IOLAPQueryAxis interface. The following table describes the different types of axes:

When you construct the OLAPQueryAxis instance, you use the OLAPQuery.getAxis() method to initialize the axis to configure it as either a row, column, or slicer axis, as the following example shows:

  	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
 	 
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = 	query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	...  
  
 	var colQueryAxis:IOLAPQueryAxis = 	query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	...

addElement(e:IOLAPElement):void

addElements(members:IList):void

OLAP cubes can be complex, so you do not want your application to pause while Flex calculates the results of an OLAP query. Therefore, when you execute a query, you also set up two callback functions that handle the results of the query. Flex then calls these functions when the query completes. This architecture lets the query run asynchronously so that your application can continue to execute during query processing.

You execute a query by calling the OLAPCube.execute() method, where the OLAPCube.execute() method returns an instance of the AsyncToken class. You use the AsyncToken class, along with the AsyncResponder class, to specify the two callback functions to handle the query results when execution completes.

In this example, the function showResult() handles the query results when the query succeeds, and the function showFault() handles any errors detected during query execution:

  <s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
	xmlns:mx="library://ns.adobe.com/flex/mx" 
	xmlns:s="library://ns.adobe.com/flex/spark" 
	creationComplete="creationCompleteHandler();"> 
  
 <fx:Script> 
 	<![CDATA[ 
 		 
 		private function creationCompleteHandler():void { 
 			// You must initialize the cube before you  
 			// can execute a query on it. 
 			myMXMLCube.refresh(); 
 		} 
  
 		// Create the OLAP query. 
 		private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 			... 
 		} 
  
 		// Event handler to execute the OLAP query  
 		// after the cube completes initialization. 
 		private function runQuery(event:CubeEvent):void { 
 			// Get cube. 
 			var cube:IOLAPCube = IOLAPCube(event.currentTarget); 
 			// Create a query instance. 
 			var query:IOLAPQuery = getQuery(cube); 
 			// Execute the query. 
 			var token:AsyncToken = cube.execute(query); 
 			// Set up handlers for the query results. 
 			token.addResponder(new AsyncResponder(showResult, showFault)); 
 		} 
  
 		// Handle a query fault. 
 		private function showFault(error:ErrorMessage, token:Object):void { 
 			Alert.show(error.faultString); 
 		} 
  
 		// Handle a query success. 
 		private function showResult(result:Object, token:Object):void { 
 			if (!result) { 
 				Alert.show("No results from query."); 
 				return; 
 			} 
  
 			myOLAPDG.dataProvider= result as OLAPResult; 
 		} 
 	]]> 
 </fx:Script> 
  
<fx:Declarations> 
	 <mx:OLAPCube name="FlatSchemaCube"  
	 	dataProvider="{flatData}"  
	 	id="myMXMLCube" 
	 	complete="runQuery(event);"> 
	 	... 
	 </mx:OLAPCube> 
<fx:Declarations> 
 
 <mx:OLAPDataGrid id="myOLAPDG" width="100%" height="100%" /> 
   
</s:Application>

Many of the queries shown so far have referenced only two dimensions of the OLAP cube, such as ProductDim and TimeDim. But what happens to the other dimensions when you omit them from the query?

All dimensions have a default member, either explicit or implicit. When you execute a query that does not reference a dimension, the query aggregates the data for that dimension using the default member. For information on defining the default member of a schema, see Creating a default member in a schema.

When you define your query, you might create a situation where a cell of the OLAPDataGrid does not contain a value. For example, when aggregating data by customer and product, you might have a customer that has never purchased TourDeFlex. For that customer and product combination, the corresponding cell of the OLAPDataGrid displays the String "NaN".

You can customize this String by setting the OLAPDataGrid.defaultCellString. For example, if you want to set the String to "No value", you would create an OLAPDataGrid control as shown here:

  <mx:OLAPDataGrid id="myOLAPDG" 
 	defaultCellString="No value" 
 	width="100%" height="100%"/>

An OLAP query has the following basic form:

  // Create an instance of OLAPQuery to represent the query.  
 var query:OLAPQuery = new OLAPQuery; 
 	 
 // Get the row axis from the query instance. 
 var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 // Create an OLAPSet instance to configure the axis. 
 var productSet:OLAPSet = new OLAPSet; 
 // Use OLAPSet.addElements() or OLAPSet.addElement() to add members to the row axis. 
 productSet.addElements(...); 
 // Add the OLAPSet instance to the axis. 
 rowQueryAxis.addSet(productSet); 
  
 // Get the column axis from the query instance, and configure it 
 // to aggregate the columns by the Quarter dimension.  
 var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 var quarterSet:OLAPSet= new OLAPSet; 
 // Use OLAPSet.addElements() or OLAPSet.addElement() to add members to the column axis. 
 productSet.addElements(...); 
 colQueryAxis.addSet(quarterSet);

You use the following methods and properties to extract information from an OLAP cube based on the attributes of the dimension, and pass it to the OLAPSet.addElements() or OLAPSet.addElement() method:

OLAPCube.findDimension(name:String):IOLAPDimension

OLAPDimension.findAttribute(name:String):IOLAPAttributeHierarchy

OLAPDimension.findMember(name:String):IOLAPMember

IOLAPAttributeHierarchy.children

IOLAPAttributeHierarchy.members

The following table shows the information returned for combinations of these methods and properties:

findDimension("ProductDim").findAttribute("Product").children

findDimension("ProductDim").findAttribute("Product").members

findDimension("ProductDim").findMember("Flex")

findDimension("QuarterDim").findAttribute("Quarter").children

findDimension("QuarterDim").findAttribute("Quarter").members

findDimension("QuarterDim").findMember("Q2")

Rather than use the findAttribute() method, you can drill down through the hierarchy of the cube by calling the following methods:

OLAPDimension.findHierarchy(name:String):IOLAPHierarchy

OLAPHierarchy.findLevel(name:String):IOLAPLevel

OLAPLevel.findMember(name:String):IList

The following table shows the information returned for different combinations of these methods:

findDimension("ProductDim").findhHierarchy("ProductHier").	findLevel("Product").children

findDimension("ProductDim").findHierarchy("ProductHier").	findLevel("Product").members

IOLAPElement(cube.findDimension("ProductDim").	findHierarchy("ProductHier").findLevel("Product").	findMember("Flex").getItemAt(0))

findDimension("QuarterDim").findHierarchy("QuarterHier").	findLevel("Quarter").children

findDimension("QuarterDim").findHierarchy("QuarterHier").	findLevel("Quarter").members

IOLAPElement(cube.findDimension("QuarterDim").	findHierarchy("QuarterHier").findLevel("Quarter").	findMember("Q2").getItemAt(0))

In the case of a simple cube, the OLAPDimension.findHierarchy(), OLAPHierarchy.findLevel(), and OLAPLevel.findMember() methods do not provide you with additional functionality from the OLAPDimension.findAttribute() and OLAPDimension.findMember() methods. They are more commonly used with complex cubes that contain dimensions with multiple levels. For more information, see Writing a query for a complex OLAP cube.

The most common type of query returns a data aggregation for all members of an attribute of a schema. For example, you define an OLAP cube using a schema that contains a ProductDim and a QuarterDim dimension, as shown in the section Writing a query for a simple OLAP cube. You then want to generate a query for all products for all quarters. The following query extracts this information:

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
  
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	productSet.addElements( 
 		cube.findDimension("ProductDim").findAttribute("Product").children); 
 	rowQueryAxis.addSet(productSet); 
  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);  
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("QuarterDim").findAttribute("Quarter").children); 
 	colQueryAxis.addSet(quarterSet); 
  
 	return query;  
 }

In this example, the column axis uses the findDimension() and findAttribute() methods to drill down into the ProductDim and QuarterDim dimensions to extract sales data. For each axis, you use the IOLAPAttributeHierarchy.children property to populate it with the all members of the attribute, but do not include the (All) member.

This query uses the default measure to populate the query result, where the default measure is the first measure defined in the cube's schema. Therefore, you do have to specify the measure as part of the query. For information on explicitly specifying the measure in the query, see Creating a query using a nondefault measure.

Notice that in this example, you did not have to specify the hierarchy name, ProductHier and QuarterDim, to extract the member from the schema. It is unnecessary to specify the hierarchy name when you only want to extract data for a single level of a dimension.

However, you could rewrite this example to explicitly drill down through the cube by calling the methods OLAPDimension.findHierarchy() and OLAPHierarchy.findLevel(), as the following example shows:

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
 	 
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	productSet.addElements(cube.findDimension( 
 		"ProductDim").findHierarchy("ProductHier").findLevel("Product").members); 
 	rowQueryAxis.addSet(productSet); 
  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("QuarterDim").findHierarchy("QuarterHier"). 
 		findLevel("Quarter").members); 
 	colQueryAxis.addSet(quarterSet); 
 	 
 	return query;        
 }

In this example, you drill down through the dimension to access the Product and Quarter levels. You typically use this technique with complex cubes where you are interested in an explicit member of a dimension.

In the query shown in the previous section, you obtain sales data for all members of the Product and Quarter levels of the schema. But, what if you only want sales data for a single product, or for a single quarter? When you drill down into a dimension, you can specify the individual member of the dimension that you want to query.

For example, you want to create a query to aggregate quarterly sales data only for Flex, but not for any other products. You therefore use the OLAPDimension.findMember() method to specify the name of the member. This method takes a String containing the name of the member, and returns an IOLAPMember instance that defines the member, as the following example shows:

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
 	 
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	productSet.addElement(cube.findDimension("ProductDim").findMember("Flex")); 
 	rowQueryAxis.addSet(productSet); 
 	 
 	var colQueryAxis:IOLAPQueryAxis =  
 	query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("QuarterDim").findAttribute("Quarter").children); 
 	colQueryAxis.addSet(quarterSet); 
 	 
 	return query;        
 }

Notice that in the previous example, you use the OLAPSet.addElement() method to add the Flex member to the OLAPSet instance, rather than the OLAPSet.addElements() method. This is because you are adding a single member to the axis, rather than multiple members.

The only issue with using the OLAPDimension.findMember() method is that it returns the first IOLAPMember instance in the cube that matches the String argument. If you think that you might have multiple instances of a member, you can rewrite this example to explicitly drill down through the cube by calling the OLAPDimension.findHierarchy(), OLAPHierarchy.findLevel(), and OLAPLevel.findMember() methods. This situation is more common with cubes that contain complex dimensions. For more information and examples, see Writing a query for a complex OLAP cube.

The OLAPLevel.findMember() method returns an IList instance that contains all IOLAPMember instances that match the String argument. You can then use the IList.getItemAt() method to access any element in the IList, as the following example shows:

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
  
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	// Get the first IOLAPElement instance in the IList instance. 
 	productSet.addElement( 
 		IOLAPElement(cube.findDimension("ProductDim").findHierarchy("ProductHier"). 
 		findLevel("Product").findMember("Flex").getItemAt(0))); 
 	rowQueryAxis.addSet(productSet); 
  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElement(IOLAPMember(cube.findDimension("TimeDim"). 
 		findHierarchy("Month").findMember("January"))); 
 	quarterSet.addElement(IOLAPMember(cube.findDimension("TimeDim"). 
 		findHierarchy("Month").findMember("February"))); 
 	colQueryAxis.addSet(quarterSet); 
  
 	return query;        
 }

An OLAP query can have three axes: row, column, and slicer. A slicer axis lets you reduce the size of the query results, often to reduce the dimensionality of the results from a dimension greater than two so that you can display the results. Another common use of a slicer axis is to aggregate data on a measure other than the default measure.

The following schema defines two measures for the points in the cube: Revenue and Cost. The first measure defined in the schema is the default measure, and it is the data that is aggregated by a query if you do not explicitly specify the measure.

  <mx:OLAPCube name="FlatSchemaCube"  
 	dataProvider="{flatData}"  
 	id="myMXMLCube" 
 	complete="runQuery(event);"> 
 	 
 	<mx:OLAPDimension name="ProductDim"> 
 		<mx:OLAPAttribute name="Product" dataField="product"/> 
 		<mx:OLAPHierarchy name="ProductHier" hasAll="true"> 
 			<mx:OLAPLevel attributeName="Product"/> 
 		</mx:OLAPHierarchy> 
 	</mx:OLAPDimension> 
  
 	<mx:OLAPDimension name="QuarterDim"> 
 		<mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
 		<mx:OLAPHierarchy name="QuarterHier" hasAll="true"> 
 			<mx:OLAPLevel attributeName="Quarter"/> 
 		</mx:OLAPHierarchy>  
 	</mx:OLAPDimension> 
 	 
 	<mx:OLAPMeasure name="Revenue"  
 		dataField="revenue" aggregator="MAX"/> 
 	<mx:OLAPMeasure name="Cost"  
 		dataField="cost" aggregator="MIN"/> 
 </mx:OLAPCube>

To aggregate by the Cost measure, you create a slicer axis to explicitly specify the measure for the query, as the following example shows:

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
 	 
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	productSet.addElements( 
 		cube.findDimension("ProductDim").findAttribute("Product").children); 
 	rowQueryAxis.addSet(productSet); 
  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("TimeDim").findAttribute("Month").children); 
 	colQueryAxis.addSet(quarterSet); 
 	 
 	// Create the slicer axis.  
 	var slicerQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.SLICER_AXIS);          
 	// Create an OLAPSet instance to configure the axis. 
 	var costSet:OLAPSet= new OLAPSet; 
 	// Use OLAPDimension.findMember() to add the Cost measure. 
 	costSet.addElement(cube.findDimension("Measures").findMember("Cost")); 
 	slicerQueryAxis.addSet(costSet); 
  
 	return query;        
 }

In this example, you use the keyword Measures to identify the measure dimension, and then use the OLAPDimension.findMember() method to access the Cost measure.

The OLAPDataGrid control displays information in two dimensions along its row and column axis. However, to display product sales by region and by month, you require a three-dimensional display: one dimension each for product, region, and month.

For example, your data has the following format:

  data:Object = { 
 	customer:"IBM",  
 	country:"US", 
 	state:"MA", 
 	region:"NewEngland", 
 	product:"FlexJS", 
 	year:2005, 
 	quarter:"Q1" 
 	month:"January", 
 	revenue: 12,575.00, 
 	cost: 500 
 }

The examples use the following OLAP schema to represent this data in an OLAP cube:

    <mx:OLAPCube name="FlatSchemaCube" 
        dataProvider="{flatData}" 
        id="myMXMLCube" 
        complete="runQuery(event);"> 
 
        <mx:OLAPDimension name="CustomerDim"> 
            <mx:OLAPAttribute name="Customer" dataField="customer"/> 
            <mx:OLAPHierarchy name="CustomerHier" 
                hasAll="true"> 
                <mx:OLAPLevel attributeName="Customer"/> 
            </mx:OLAPHierarchy> 
        </mx:OLAPDimension> 
    
        <mx:OLAPDimension name="ProductDim"> 
            <mx:OLAPAttribute name="Product" dataField="product"/> 
            <mx:OLAPHierarchy name="ProductHier" 
                hasAll="true"> 
                <mx:OLAPLevel attributeName="Product"/> 
            </mx:OLAPHierarchy> 
        </mx:OLAPDimension> 
 
        <mx:OLAPDimension name="TimeDim"> 
            <mx:OLAPAttribute name="Year" dataField="year"/> 
            <mx:OLAPAttribute name="Quarter" dataField="quarter"/> 
            <mx:OLAPAttribute name="Month" dataField="month"/> 
            <mx:OLAPHierarchy name="Time-Period" 
                hasAll="true"> 
                <mx:OLAPLevel attributeName="Year"/> 
                <mx:OLAPLevel attributeName="Quarter"/> 
                <mx:OLAPLevel attributeName="Month"/> 
            </mx:OLAPHierarchy> 
        </mx:OLAPDimension> 
 
        <mx:OLAPDimension name="GeographyDim">  
            <mx:OLAPAttribute name="Country" dataField="country"/> 
            <mx:OLAPAttribute name="Region" dataField="region"/> 
            <mx:OLAPAttribute name="State" dataField="state"/> 
            <mx:OLAPHierarchy name="Country-Region-State" 
                hasAll="true"> 
                <mx:OLAPLevel attributeName="Country"/> 
                <mx:OLAPLevel attributeName="Region"/> 
                <mx:OLAPLevel attributeName="State"/> 
            </mx:OLAPHierarchy> 
        </mx:OLAPDimension> 
 
        <mx:OLAPMeasure name="Revenue" 
            dataField="revenue" 
            aggregator="SUM"/> 
        <mx:OLAPMeasure name="Cost" 
         dataField="cost" 
         aggregator="SUM"/> 
    </mx:OLAPCube>

You can use a slicer axis to filter the results of a query for display in two dimensions. In this example, you set the row axis to the region and the column axis to the month. You then define a slicer axis to specify the product as Flex so that you end up with a two-dimensional table of sales by region and month for Flex.

  private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
  
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	productSet.addElements( 
 		cube.findDimension("GeographyDim").findAttribute("Region").children); 
 	rowQueryAxis.addSet(productSet); 
  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("TimeDim").findAttribute("Month").children); 
 	colQueryAxis.addSet(quarterSet); 
  
 	// Create the slicer axis.  
 	var slicerQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.SLICER_AXIS);          
 	// Create an OLAPSet instance to configure the axis. 
 	var flexSet:OLAPSet= new OLAPSet; 
 	flexSet.addElement( 
 		IOLAPElement(cube.findDimension("ProductDim").findHierarchy("ProductHier"). 
 		findLevel("Product").findMember("Flex").getItemAt(0))); 
 	slicerQueryAxis.addSet(flexSet); 
  
 	return query;        
 }

You can specify more than one member for the slicer access. For example, if your cube contains information on different product such as Flex and Adobe^® Flash^®, you could create the two slicer axes as the following example shows:

  // Create the slicer axis.  
 var slicerQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.SLICER_AXIS);  
  
 // Create an OLAPSet instance to configure the axis. 
 var sliceSet:OLAPSet= new OLAPSet; 
 sliceSet.addElement(IOLAPElement(cube.findDimension("ProductDim"). 
 	findHierarchy("ProductHier").findLevel("Product").findMember("Flex").getItemAt(0))); 
  
 sliceSet.addElement(IOLAPElement(cube.findDimension("ProductDim"). 
 	findHierarchy("ProductHier").findLevel("Product").findMember("Flash").getItemAt(0))); 
  
 slicerQueryAxis.addSet(sliceSet);

In this example, your query result would show sales of Flex and Flash for each region and month.

To control the styling of a cell by using a callback function, use the OLAPDataGrid.styleFunction property to specify the callback function. The callback function must have the following signature:

  function_name(row:IOLAPAxisPosition, column:IOLAPAxisPosition, value:Number):Object

where row is the IOLAPAxisPosition associated with this cell on the row axis, column is the IOLAPAxisPosition associated with this cell on the column axis, and value is the cell value.

The function returns an Object that contains one or more styleName:value pairs to specify a style setting, or null. The styleName field contains the name of a style property, such as color, and the value field contains the value for the style property, such as 0x00FF00. For example, you could return two styles using the following syntax:

  {color:0xFF0000, fontWeight:"bold"}

The OLAPDataGrid control invokes the callback function when it updates its display, such as when the control is first drawn on application start up, or when you call the invalidateList()method.

The following example modifies the example shown in the section Example using the OLAPDataGrid control to add a callback function to display all cells with a value greater than 1000 in green:

  <fx:Script> 
 	<![CDATA[ 
 		...         
  
 		// Callback function that hightlights in green 
 		// all cells with a value greater than or equal to 1000. 
 		public function myStyleFunc(row:IOLAPAxisPosition, column:IOLAPAxisPosition,  
 			value:Number):Object  
 		{ 
 			if (value >= 1000)  
 			return {color:0x00FF00};  
 	 
 			// Return null if value is less than 1000. 
 			return null;       
 		}         
 		]]> 
 </fx:Script> 
  
 ... 
  
 <mx:OLAPDataGrid id="myOLAPDG"  
 	width="100%" height="100%" 
 	styleFunction="myStyleFunc"/>

You customize the appearance and behavior of cells in an OLAPDataGrid control by creating custom item renderers.

For an introduction to item renderers and item editors, see MX item renderers and item editors.

To use an item renderer with the OLAPDataGrid control, you assign the item renderer to the OLAPDataGrid control itself, not to a specific column, by using the OLAPDataGrid.itemRendererProviders property. The itemRendererProviders property contains an Array of OLAPDataGridItemRendererProvider instances, where each OLAPDataGridItemRendererProvider instance defines the characteristics for a single item renderer.

You can use the OLAPDataGridRendererProvider.renderer property to assign an item renderer to the OLAPDataGrid control, much in the way that you can by using the AdvancedDataGrid.rendererProviders property, or can use the OLAPDataGridRendererProvider.formatter property to assign a formatter class. The following example modifies the example shown in the section Example using the OLAPDataGrid control to add an item renderer that applies the CurrencyFormatter formatter to each cell in the control:

  ... 
 <mx:CurrencyFormatter id="usdFormatter" precision="2"  
 	currencySymbol="$" decimalSeparatorFrom="." 
 	decimalSeparatorTo="." useNegativeSign="true"  
 	useThousandsSeparator="true" alignSymbol="left"/> 
  
 ... 
  
 <mx:OLAPDataGrid id="myOLAPDG"  
 	width="100%" height="100%"> 
  
 	<mx:itemRendererProviders> 
 		<mx:OLAPDataGridItemRendererProvider  
 			uniqueName="[QuarterDim].[Quarter]" 
 			type="{OLAPDataGrid.OLAP_HIERARCHY}" 
 			formatter="{usdFormatter}"/> 
 	</mx:itemRendererProviders> 
 </mx:OLAPDataGrid>

To assign the item renderer, use the uniqueName and type properties of the OLAPDataGridItemRendererProvider class. The uniqueName property specifies the elements of the query, and therefore the corresponding cells of the OLAPDataGrid control, that you modify by using the item renderer. The type properly specifies the element type, such as dimension, hierarchy, or level of the element specified by the uniqueName property.

When assigning a formatter to the OLAPDataGridItemRendererProvider, you must specify a subclass of the mx.formatters.Formatter class; for example, the MX formatters such as CurrencyFormatter or NumberFormatter. The formatter cannot be a Spark formatter.

The function that defines the query for this example is shown below:

  // Create the OLAP query. 
 private function getQuery(cube:IOLAPCube):IOLAPQuery { 
 	// Create an instance of OLAPQuery to represent the query.  
 	var query:OLAPQuery = new OLAPQuery; 
  
 	// Get the row axis from the query instance. 
 	var rowQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.ROW_AXIS); 
 	// Create an OLAPSet instance to configure the axis. 
 	var productSet:OLAPSet = new OLAPSet; 
 	// Add the Product to the row to aggregate data  
 	// by the Product dimension. 
 	productSet.addElements( 
 		cube.findDimension("ProductDim").findAttribute("Product").children); 
 	// Add the OLAPSet instance to the axis. 
 	rowQueryAxis.addSet(productSet); 
  
 	// Get the column axis from the query instance, and configure it 
 	// to aggregate the columns by the Quarter dimension.  
 	var colQueryAxis:IOLAPQueryAxis = query.getAxis(OLAPQuery.COLUMN_AXIS);          
 	var quarterSet:OLAPSet= new OLAPSet; 
 	quarterSet.addElements( 
 		cube.findDimension("QuarterDim").findAttribute("Quarter").children); 
 	colQueryAxis.addSet(quarterSet); 
  
 	return query;        
 }

Notice that the axis for the QuarterDim creates a query for the Quarter hierarchy of the QuarterDim dimension. Therefore, you set the uniqueName property to [QuarterDim].[Quarter], and set the type property to OLAPDataGrid.OLAP_HIERARCHY. For more information on the structure of the OLAP code for this example, see Writing a query for a simple OLAP cube.

You can modify this example to drill down through the cube by specifying the query as shown below for the QuarterDim:

  quarterSet.addElements( 
 	cube.findDimension("QuarterDim").findHierarchy("QuarterHier"). 
 	findLevel("Quarter").members);

You therefore modify the uniqueName and type properties as shown below:

  <mx:OLAPDataGrid id="myOLAPDG"  
 	width="100%" height="100%"> 
  
 	<mx:itemRendererProviders> 
 		<mx:OLAPDataGridItemRendererProvider  
 			uniqueName="[QuarterDim].[QuarterHier].[Quarter]" 
 			type="{OLAPDataGrid.OLAP_LEVEL}" 
 			formatter="{usdFormatter}"/> 
 	</mx:itemRendererProviders> 
 </mx:OLAPDataGrid>

Notice in this example that the query for the QuarterDim specifies the dimension, hierarchy, and level of the OLAP cube. Therefore, you modify the uniqueName property to match this structure, and set the type property to OLAPDataGrid.OLAP_LEVEL.

Each cell in an OLAPDataGrid control is a result of an intersection between the members along a row and the members along a column of the control. However, when you assign an item renderer to an OLAPDataGrid control, you only specify the uniqueName and type properties for one of the dimensions, either row or column. Therefore, you can create a situation where two different item renderers are assigned to the same cell of the control.

In case of a conflict between two or more item renderers, the OLAPDataGrid control applies the item renderer based on the following priorities:

1. type = OLAPDataGrid.OLAP_MEMBER

2. type = OLAPDataGrid.OLAP_LEVEL

3. type = OLAPDataGrid.OLAP_HIERARCHY

4. type = OLAPDataGrid.OLAP_DIMENSION

Therefore, if an item renderer with a type value of OLAPDataGrid.OLAP_LEVEL and an item renderer with a type value of OLAPDataGrid.OLAP_HIERARCHY are applied to the same cell, the OLAPDataGrid control applies the item renderer with a type value of OLAPDataGrid.OLAP_LEVEL.

If two item renderers have the same value for the type property, the OLAPDataGrid control determines which renderer more closely matches the item, and uses it.

You can use an item renderer to apply styles to specific cells in the OLAPDataGrid control, as the following example shows:

  <fx:Style> 
 	.cellStyle 
 	{ 
 		color:#ff0000; 
 		fontWeight:"bold" 
 	} 
 </fx:Style> 
  
 	... 
  
 <mx:OLAPDataGrid id="myOLAPDG"  
 	width="100%" height="100%"> 
  
 	<mx:itemRendererProviders> 
 		<mx:OLAPDataGridItemRendererProvider  
 			uniqueName="[QuarterDim].[Quarter]" 
 			type="{OLAPDataGrid.OLAP_HIERARCHY}" 
 			formatter="{usdFormatter}" 
 			styleName="cellStyle"/> 
 	</mx:itemRendererProviders> 
 </mx:OLAPDataGrid>

In this example, you create a style definition, then apply it to the cells of the OLAPDataGrid control so that it applies to the same cells as the CurrencyFormatter formatter.