.. index::
   pair: MapScript; Querying

.. _querying:

*****************************************************************************
 Querying
*****************************************************************************

:Author: Sean Gillies
:Revision: $Revision$
:Date: $Date$

.. 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.

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)
            
            layer.getFeature(result)
            
            ...  # do something with this feature

        # Close when done
        layer.close()

Backwards Compatibility
-----------------------

The API changed substantially with version 6.0 and backward compatibility was broken.
Scripts will have to be updated to work
with the new API.


Attribute Queries
=================

By Attributes
-------------

queryByAttributes()

Spatial Queries
===============

By Rectangle
------------

queryByRect()

By Point
--------

queryByRect()

By Shape
--------

queryByShape()

By Selection
------------

queryByFeatures()