Add documentation to mapserver API docs

[tbonfort]

Reporter: cord@lupinex.com Date: 2004/11/28 - 21:06

I have found it somewhat unclear whether to use Filter or Query for mapserver
application.  I suggest the following information be added to the setFilter and
queryByAttribute methods - or in a more general place that can be referred to
from each of these methods - say in the header of the layerObj:

Filter:
A filter can be used to reduce the graphic information presented in a map layer.
Filter expressions can include single or multiple fields, such as:
  state_abbr = 'CA'
  ((state_abbr in ('CA','WA')) or (state_name like 'New%'))
Using filters does not provide access to feature or shape information - use
query methods for this access.

Query methods:
Queries can be used to get extents of features, gather feature attribute
information, or reduce the graphic information presented in a layer.
Query expressions can include single or multiple fields (??? is this true).
queryByAttributes method is a succint way to get a set of features matching
attribute criteria in such a way:
  queryByAttributes (mapref, "state_abbr", "state_abbr='CA'", MS_SINGLE) - for
postgis 
   queryByAttributes (mapref, "state_abbr,state_name", "((state_abbr in
('CA','WA')) or (state_name like 'New%'))", MS_MULTI) - for postgis - i am not
sure this works - one of the issues i am working with now
Once you have issued a query against a map layer, you can then use the
combination of open(), getResult(index), getFeature(index) to gather information
on the resulting features

** - aside from providing example code snippets, the API documentation should
explain what results should be expected.
** - also, performance is a question - do filter and query methods generate the
same SQL code to the server - or does one get all data from the server and then
place the data reduction burden on mapserver.

[tbonfort]

Author: sgillies@frii.com Date: 2005/01/30 - 17:55

Agreed, Cord, the issues surrounding filters and queries are some of the most
poorly explained of MapServer.  The problem's root is no documentation of the
original implementation and I am going to defer documentation to the original
author.  I have decided not to include this information into the mapscript API
docs, which will remain a very brief documentation of class attributes and
method signatures.

I am, however, willing to commit patches or improvements to the query howto doc
at mapscript/doc/querying-HOWTO.txt.  Would you be interested in editing your
text above into that document?

[tbonfort]

Author: sgillies@frii.com Date: 2005/03/29 - 17:06

no response.  am closing this bug.