1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
.. $Id: querying-HOWTO.txt,v 1.5 2005/03/29 16:56:21 sean Exp $
===========================================================================
Copyright (c) 2004 Sean Gillies.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
===========================================================================
..
*****************************************************************************
Mapscript Query HOWTO
*****************************************************************************
:Author: Sean Gillies
:Contact: sgillies@frii.com
:Revision: $Revision: 1.5 $
:Date: $Date: 2005/03/29 16:56:21 $
.. The next heading encountered becomes our H2
..
.. sectnum::
.. contents::
:depth: 2
:backlinks: top
Introduction
============
All examples in this document refer to the mapfile and testing layers
distributed with MapServer 4.2+ and found under mapserver/tests.
Pseudocode
----------
All examples will use a pseudocode that is consistent with the language
independent API reference. Each line is a statement. For object attributes
and methods we use the dot, '.', operator. Creation and deletion of objects
will be indicated by 'new' and 'del' keywords. Other than that, the
pseudocode looks a lot like Python.
Querying Overview
=================
The Query Result Set
--------------------
Map layers can be queried to select features using spatial query methods
or the attribute query method. Ignoring for the moment whether we are
executing a spatial or attribute query, results are obtained like so::
layer.query() # not an actual method!
results = layer.getResults()
In the case of a failed query or query with zero results, 'getResults'
returns NULL.
Query Template
--------------
A query will not set results for a layer with a NULL 'template' attribute.
This is an artifact of the querying functionality of the mapserv CGI program
which, unfortunately, lingers in the scripting interface. I don't like it
either, and would have removed this requirement except for the fact that
some users have scripts that are dependent on this artifact.
Result Set Members
------------------
Individual members of the query results are obtained like::
... # continued
if results:
for i in range(results.numresults): # iterate over results
result = results.getResult(i)
This result object is a handle, of sorts, for a feature of the layer,
having 'shapeindex' and 'tileindex' attributes that can be used as
arguments to 'getFeature'.
Resulting Features
-------------------
The previous example code can now be extended to the case of obtaining all
queried features::
layer.query()
results = layer.getResults()
if results:
# open layer in preparation of reading shapes
layer.open()
for i in range(results.numresults):
result = results.getResult(i)
feature = layer.getFeature(result.shapeindex, result.tileindex)
... # do something with this feature
# Close when done
layer.close()
Backwards Compatibility
-----------------------
Scripts using the 4.2 API can continue to access query result members
through layer methods::
for i in range(layer.getNumResults()):
result = layer.getResult(i)
but should adopt the new API for use in new work.
Attribute Queries
=================
Please see the API Reference (mapscript.txt) for details of
layerObj::queryByAttributes().
Spatial Queries
===============
Please see the API Reference (mapscript.txt) for details of layerObj's
queryByPoint(), queryByRect(), queryByShape(), and queryByFeatures()
methods.
|
