RFC 29: OGR Set Desired Fields

Author: Martin Dobias
Contact: wonder.sk@…
Status: Development

Summary

To improve performance when fetching features, this RFC proposes a way how to tell OGR which fields are going to be required in subsequent GetFeature() / GetNextFeature() calls. Knowing the necessary fields, the OGR driver can decide to leave the rest of the fields null.

Details

A new (non-virtual) function should be added to OGRLayer class to allow the client to set which fields will be fetched:

void SetDesiredFields(int nNumFields, int* pabFields);

and an equivalent call for C API:

void CPL_DLL OGR_L_SetDesiredFields( OGRLayerH, int, int* );

The parameter "pabFields" is an array of booleans, each item specifies whether the field with the same index should be fetched. The length of the array is specified in "nNumFields" parameter and typically it should be the same as the actual number of fields. The SetDesiredFields() function makes a copy of both nNumFields and pabFields (these have to be stored as class member variables of OGRLayer: nDesiredNumFields, pabDesiredFields).

The parameter "nNumFields" is a bit redundant, but it keeps things safe in case some fields are later added so that there is not access beyond the allocated memory of the array.

The semantics is as follows: if nNumFields < 0, all fields will be fetched. Otherwise the pabFields array will be copied to an internal one within OGRLayer and only the fields having non-zero value in that array will be fetched.

The implementation of fetching in drivers will usually require only small adjustment, e.g.:

for( int iField = 0; iField < poDefn->GetFieldCount(); iField++ )
{
  if (nDesiredNumFields >= 0 && iField < nDesiredNumFields && !pabDesiredFields[iField])
    continue;

  // fetch field
}

Compatibility

This change is fully backwards compatible: OGR will continue to fetch all fields by default. Only applications using the proposed new API will experience new behavior.

There is no need to modify all existing drivers. Drivers that do not consider the desired fields will still fetch all attributes as before.