1.. _rfc-29: 2 3================================================================================ 4RFC 29: OGR Set Ignored Fields 5================================================================================ 6 7Author: Martin Dobias 8 9Contact: wonder.sk@gmail.com 10 11Status: Adopted 12 13Summary 14------- 15 16To improve performance when fetching features, this RFC proposes a way 17how to tell OGR which fields are not going to be required in subsequent 18GetFeature() / GetNextFeature() calls. Such fields will be ignored by 19the driver and their value will be kept null. The RFC counts also with 20the possibility to ignore feature geometry and style. 21 22Common use cases: 23 241. the client renders the layer: all (or most) fields can be ignored, 25 only the geometry is required 26 272. the client shows attribute table: all fields are required, the 28 geometry can be ignored 29 30Details 31------- 32 33A new function will be added to OGRLayer class to allow the client to 34set which fields will *not* be fetched: 35 36:: 37 38 virtual OGRErr OGRLayer::SetIgnoredFields( const char **papszFields ); 39 40and an equivalent call for C API: 41 42:: 43 44 OGRErr CPL_DLL OGR_L_SetIgnoredFields( OGRLayerH, const char **papszFields ); 45 46The argument is a list of fields to be ignored, by name, and the special 47field names "OGR_GEOMETRY" and "OGR_STYLE" will be interpreted to refer 48to the geometry and style values of a feature. 49 50Passing by field name has been chosen so that we could handle 51OGR_GEOMETRY, OGR_STYLE and possibly some other special fields in the 52future. Instead of specifying "desired" fields, it has been decided to 53specify "ignored" fields so that we wouldn't accidentally drop things 54like geometry and style just because they weren't explicitly listed in a 55desired list. 56 57Passing NULL for papszFields will clear the ignored list. 58 59The method will return OGRERR_NONE as long as all the field names are 60able to be resolved, even if the method does not support selection of 61fields. 62 63The drivers supporting this method will return TRUE to OLCIgnoreFields 64("IgnoreFields") capability. 65 66The method will be implemented at the level of OGRLayer class: it will 67resolve indexes of the fields and set the following new member variables 68which indicate what should be ignored. The flags will be stored within 69OGRFeatureDefn and OGRFieldDefn classes and available with these getter 70functions: 71 72:: 73 74 bool OGRFieldDefn::IsIgnored(); 75 bool OGRFeatureDefn::IsGeometryIgnored(); 76 bool OGRFeatureDefn::IsStyleIgnored(); 77 78The getter member functions will be complemented by setter functions for 79use by OGRLayer. Setting the "ignored" flags directly by clients will be 80forbidden. 81 82Optionally the method ``SetIgnoredFields()`` can be overridden in driver 83implementation if the driver has some special needs. 84 85Implementation in drivers 86------------------------- 87 88The implementation of drivers will require small adjustments in order to 89support this RFC. Drivers not making use of this addition will simply 90continue to fetch also fields/geometry/style that are not requested by 91the caller. 92 93The adjustments in driver implementation will look as follows: 94 95:: 96 97 if (!poDefn->IsGeometryIgnored()) 98 { 99 // fetch geometry 100 } 101 if (!poDefn->IsStyleIgnored()) 102 { 103 // fetch style 104 } 105 106 for( int iField = 0; iField < poDefn->GetFieldCount(); iField++ ) 107 { 108 if (poDefn->GetFieldDefn(iField)->IsIgnored()) 109 continue; 110 111 // fetch field 112 } 113 114Compatibility 115------------- 116 117This change is fully backwards compatible: OGR will continue to fetch 118geometry, style and all fields by default. Only applications using the 119proposed API will experience the new behavior. 120 121Initially, only some drivers (Shapefile and few others) will implement 122this RFC. There is no need to modify all existing drivers when adopting 123the RFC - drivers that do not consider the ignored fields will simply 124fetch all attributes as before. To check whether a driver supports this 125RFC, OLCIgnoreFields capability can be checked. 126 127ogr2ogr command line tool will make use of this RFC in cases it receives 128-select argument with a list of required fields. Other than the 129specified fields will be ignored. 130 131Voting History 132-------------- 133 134- Frank Warmerdam +1 135- Tamas Szekeres +1 136- Daniel Morissette +0 137- Howard Butler +0 138- Even Rouault +0 139