About Fetch Sizes and Fetch Blocks

What is the fetch size of a Cursor?

An OLAP API Cursor represents the entire result set for a Source. The Cursor is a virtual Cursor, however, because it retrieves only a portion of the result set at a time from the OLAP service. A CursorManager manages a virtual Cursor and retrieves results from the OLAP service as your application needs it. By managing the virtual Cursor, the CursorManager relieves your application of a substantial burden.

The amount of data that a Cursor retrieves in a single fetch operation is determined by the fetch size specified for the Cursor. For a CompoundCursor, the amount of data fetched in a single operation is the product of the fetch sizes of all of its descendent ValueCursor objects. The total set of values retrieved in a single fetch is the fetch block for the Cursor. You specify fetch sizes in order to limit the amount of data your application needs to cache on the local computer and to maximize the efficiency of the fetch by customizing it to meet the needs of your method of displaying of the data.

When you create a CursorManagerSpecification for a Source, as the first step in creating a Cursor, the OLAP service specifies a default fetch size on the root CursorSpecification of the CursorManagerSpecification. By calling methods on the CursorSpecification objects of the CursorManagerSpecification, you can specify a default fetch size or specify setting the fetch size at other levels of a CompoundCursor.

If the fetch size is specified on a CursorSpecification, then you can get or set the fetch size for the corresponding Cursor by calling the getFetchSize or setFetchSize method on that Cursor. For a CompoundCursor, you can set different fetch sizes for child Cursor objects at different levels in the outputs.

A Cursor has a local fetch size if the size of the fetch block is specified for that Cursor. Not all of the Cursor objects in a CompoundCursor can have local fetch sizes. The structure of a CompoundCursor is like a tree, with the hierarchy of Cursor objects starting at the topmost (root) Cursor and going down through all the child Cursor objects. Any path through the hierarchy, starting from the root and going down to a leaf ValueCursor, can contain one, and only one, Cursor with a local fetch size. Specifying the fetch size on a parent Cursor affects all of the child Cursor objects of that parent. This means that a fetch block can contain no more than the number of elements of each child Cursor specified by the fetch size. The following figure shows an example of a path through the hierarchy of a Cursor tree in which the Cursor objects with local fetch sizes are shaded.

About determining the shape of a fetch block

In a CompoundCursor, the levels at which you set the fetch sizes determine the shape of the fetch block of the CompoundCursor. The optimal fetch block for a CompoundCursor depends on the way you intend to navigate the Cursor and display the data. After determining how to display the data, you should do the following:

• Specify a fetch block that is large enough to contain all the data required for the portion of the result set that you are displaying in the user interface. For example, if you display the data in a table and the size of the window means that 25 rows are visible at a time, then the fetch block should contain at least 25 rows. If it is any smaller than this, the Cursor needs to make multiple trips to the OLAP service to fill the display.

• Specify fetch sizes on the Cursor objects that you use to loop through the result set. For example, for a table view, set fetch sizes on the root Cursor and for a crosstab view, set fetch sizes on the child Cursor objects.

• Keep the product of all of the fetch sizes relatively small because the product determines the total number of cells in the fetch block. If the product of all the fetch sizes is too large, then you lose the advantages of the virtual Cursor.

For examples of specifying fetch sizes and fetch blocks for different displays, see Chapter 9.

About sharing fetch blocks

You can create two or more Cursor objects from the same CursorManager and use both Cursor objects simultaneously. The Cursor objects can share the data managed by the CursorManager, rather than having separate data caches, because the shape of the fetch blocks is the same for both Cursor objects. The shape of the fetch blocks is determined by the levels of the CursorManagerSpecification on which the fetch size is specified.

An example is an application that displays the results of a query to the user as both a table and a graph. The application creates a CursorManagerSpecification for a Source and then creates a CursorManager for the CursorManagerSpecification. The application creates two separate Cursor objects from the same CursorManager, one for a table view and one for a graph view. The two views share the same query and display the same data, just in different formats. The following figure illustrates the relationship between the Source, the Cursor objects, and the views.