MapGuide RFC 84 - Fetch Size

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	Sept. 07, 2009
Last Modified	(Leaf Li) Timestamp
Author	(Leaf Li)
RFC Status	adopted
Implementation Status	implemented
Proposed Milestone	(2.2)
Assigned PSC guide(s)	(Tom Fukushima)
Voting History	September 21, 2009
+1	Tom, Bruce, Trevor, Andy, Paul, Kenneth
+0
-0
-1
no vote	Jason, Bob, Harris

Overview

This proposal is to extend MapGuide Feature Service so that the client can set the size of the fetch array when executing a query.

Motivation

For queries that return a large number of objects many feature sources support improving performance by configuring the row fetch size in order to reduce the number database server round trips required to satisfy the selection criteria. For example, Oracle and Microsoft SQL Server support fetching many rows at once. While many FDO providers take advantage of this internally, the fetch size they use is fixed and does not allow the caller to tune it based on their circumstances. In FDO RFC 41 (​http://trac.osgeo.org/fdo/wiki/FDORfc41), it enhances FDO API to allow callers to tune the fetch size for providers that will support this. Providers that do not use a fetch size or have a fixed internal implementation simply will ignore the set fetch size. In either case, this does not affect the actual results of queries as it is a performance tuning parameter. This RFC will do the similar enhancement for MapGuide Feature Service.

Proposed Solution

The following method will be added to class MgFeatureQueryOptions to allow users to set fetch size and fetch size is 0 by default. When calling method MgFeatureService::SelectFeatures(...) and MgFeatureService::SelectAggregate(...), fetch size will be used.

    //////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// For queries that return a large number of objects 
    /// some feature sources support improving performance by setting
    /// fetch size in order to reduce the number of database server
    /// round trips required to satisfy the selection criteria. 
    /// Providers that do not use a fetch size will ignore the fetch
    /// size parameter.  This does not affect the actual results of 
    /// queries as it is a performance tuning parameter.
    ///
    /// \param fetchSize (int)
    /// The fetch size of query. The query returns all of query
    /// results if setting the fetch size to 0.
    ///
    /// \return
    /// Returns nothing.
    ///
    void SetFetchSize(INT32 fetchSize);

The following method will be added in MgFeatureService by adding one argument fetchSize to method ExecuteSqlQuery so that callers can set fetch size for an SQL query. For the old method ExecuteSqlQuery, it always returns all of query results.

    //////////////////////////////////////////////////////////////
    /// \brief
    /// Executes the SQL SELECT statement with the specified parameters
    /// on the specified feature source.
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier referring to a feature source.
    /// \param sqlStatement (String/string)
    /// The SQL SELECT statement.
    /// \param params (MgParameterCollection)
    /// Parameters binded to the SQL statement.
    /// \param transaction (MgTransaction)
    /// The transaction on which the sql statement will be executed.
    /// \param fetchSize (int)
    /// The fetch size of query. This method returns all data
    /// of query if setting the fetch size to 0.
    ///
    /// \return
    /// Returns an MgSqlDataReader instance (or NULL).
    ///
    virtual MgSqlDataReader* ExecuteSqlQuery( 
                                 MgResourceIdentifier* resource,
                                 CREFSTRING sqlStatement,
                                 MgParameterCollection* params,
                                 MgTransaction* transaction,
                                 INT32 fetchSize ) = 0;

Implications

This is new API only. There will be no effect on existing applications. However, API documentation needs to be updated.

Test Plan

Add unit tests for those new methods into the existing Feature Service unit tests.

Funding/Resources

Supplied by Autodesk.