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	Draft
Implementation Status	(pending)
Proposed Milestone	(2.2)
Assigned PSC guide(s)	(Tom Fukushima)
Voting History	(vote date)
+1
+0
-0
-1

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 two methods will be added to class MgFeatureService to allow users to set fetch size for a FdoISelect and FdoISelectAggregate command.

    /// \brief
    /// Selects features from a feature source according to the
    /// criteria set in the MgFeatureQueryOptions argument The
    /// criteria are applied to all of the features in the feature
    /// source. Use the coordinateSystem argument to set the target
    /// coordinate system if you want to transform and use fetchSize
    /// argument to set the fetch size of query.
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier for the feature source.
    /// \param className (String/string)
    /// The name of the feature class from which
    /// the properties of interest are selected.
    /// \param options (MgFeatureQueryOptions)
    /// MgFeatureQueryOptions instance
    /// containing all required filters for this
    /// select operation.
    /// \param coordinateSystem (String/string)
    /// The name of the coordinate system to transform to.
    /// \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 MgFeatureReader containing the set of selected
    /// features.
    ///
    virtual MgFeatureReader* SelectFeatures(   
                                  MgResourceIdentifier* resource,
                                  CREFSTRING className,
                                  MgFeatureQueryOptions* options,
                                  CREFSTRING coordinateSystem,
                                  INT32 fetchSize ) = 0; 

    /// \brief
    /// Selects groups of features from a feature source and applies
    /// filters to each of the groups according to the criteria set
    /// in the MgFeatureAggregateOptions argument. Use fetchSize
    /// argument to set the fetch size of query.
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier for the feature
    /// source.
    /// \param className (String/string)
    /// The name of the feature class on which
    /// the select operation is performed.
    /// \param options (MgFeatureAggregateOptions)
    /// An MgFeatureAggregateOptions instance
    /// containing all the criteria and filters
    /// required for this select operation.
    /// \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 MgDataReader containing the group values.
    ///
    virtual MgDataReader* SelectAggregate( 
                                 MgResourceIdentifier* resource,
                                 CREFSTRING className,
                                 MgFeatureAggregateOptions* options,
                                 INT32 fetchSize) = 0;

The following two methods in MgFeatureService will be extended to add one argument fetchSize to allow callers to set fetch size for a SQL query.

    //////////////////////////////////////////////////////////////
    /// \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;

    ///////////////////////////////////////////////////////
    /// \brief
    /// Executes SQL statements NOT including SELECT statements
    /// with the specified parameters.
    ///
    /// \param resource (MgResourceIdentifier)
    /// A resource identifier for a feature source.
    /// \param sqlNonSelectStatement (String/string)
    /// The SQL statement that is NOT a 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 a positive integer value indicating how many
    /// instances (rows) have been affected.
    ///
    virtual INT32 ExecuteSqlNonQuery( 
                                 MgResourceIdentifier* resource,
                                 CREFSTRING sqlNonSelectStatement,
                                 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.