Opened 19 years ago

Closed 19 years ago

#1095 closed enhancement (wontfix)

Add documentation to mapserver API docs

Reported by: cord@… Owned by: sgillies@…
Priority: low Milestone:
Component: MapScript-SWIG Version: 4.4
Severity: minor Keywords:
Cc:

Description

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.

Change History (3)

comment:1 by cord@…, 19 years ago

op_sys: Windows XPLinux
rep_platform: PCOther

comment:2 by sgillies@…, 19 years ago

Status: newassigned
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?

comment:3 by sgillies@…, 19 years ago

Resolution: wontfix
Status: assignedclosed
no response.  am closing this bug.

Note: See TracTickets for help on using tickets.