You use an OLAP query to extract data from an OLAP cube for display by the OLAPDataGrid control. An OLAP query defines a result set in a two-dimensional table of rows and columns so that the data can be viewed in the OLAPDataGrid control.

The following table describes the classes and interfaces that you use the define a query:

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

Preparing a cube for a query

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:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    creationComplete="creationCompleteHandler();">

<mx: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 {
            ...
        }
    ]]>
</mx:Script>

<mx:OLAPCube name="FlatSchemaCube" 
    dataProvider="{flatData}" 
    id="myMXMLCube"
    complete="runQuery(event);">
    ...
</mx:OLAPCube>

Creating a query axis

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);         
    ...

Populating a query axis

You use the OLAPSet class to specify the members of the dimensions of the OLAP cube that populate a query axis. To add a member to an OLAPSet instance, you call the OLAPSet.addElement() or OLAPSet.addElements() method. The following table describes these methods:

For more information, see Writing a query for a simple OLAP cube and Writing a query for a complex OLAP cube.

Executing a query and returning the results to an OLAPDataGrid control

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:

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
        creationComplete="creationCompleteHandler();">

<mx: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;
        }
    ]]>
</mx:Script>

<mx:OLAPCube name="FlatSchemaCube" 
    dataProvider="{flatData}" 
    id="myMXMLCube"
    complete="runQuery(event);">
    ...
</mx:OLAPCube>
<mx:OLAPDataGrid id="myOLAPDG" width="100%" height="100%" />

Using the default member in a query

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.

Specifying a default cell string for the OLAPDataGrid control

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 Illustrator. 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%"/>