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