A quick look at the versatile spatial filters in the ArcGIS JavaScript APIs

Using the Query class geometry property as a spatial filter is one of the most important and versatile aspects of the ArcGIS JavaScript API and its extensions for the Google Maps API and Virtual Earth. This functionality lets you pass a point, line, multi-point line, bounding box, or a polygon to a QueryTask without having to worry about handling any particular aspects of the shape. A QueryTask uses the geometry to perform a query operation against a map service layer resource that has been exposed through an ArcGIS Server REST API URL. An example of a QueryTask is to return the attributes for all census blocks that exist inside the geometry with a population greater than 200.

To make this work, all your application needs to do is create a valid shape either by manually defining its attributes and vertices, or using one of the built-in drawing tools that comes with the API or extensions. Continuing with the example mentioned above, you can use a hand-drawn polygon to define a demographic study area. As soon as the drawing is complete, as detected a the mouse listener, you can have the code pass the polygon directly to the QueryTask which then returns the demographic population attributes for the area.

Below is an JavaScript code excerpt showing how you might use the geometry property with the extension for the Google Maps API.

function enableDrawing()
{
        //create a new polygon and add it to the map
        polygon = new GPolygon([], "#DC143C", 2, 1.0, "#00FFFF", 0.5);
        map.addOverlay(polygon);
        //activate the Google browser drawing functionality
        polygon.enableDrawing(options);
        //register a listener for "endline" event
        GEvent.addListener(polygon, "endline", runQueryTask);              
}
function runQueryTask()
{                   
        //Assign the polygon geometry to the queryGeometry property.
        //And, define what attribute fields to return in the FeatureSet
        query.queryGeometry = polygon;
        query.returnGeometry = true;
        query.where = “POP2000>200”;
        query.outFields = ['POP2000','HOUSEHOLDS','BLOCK'];     
        
        //execute the Query Task and then display the results
        qtask.execute(query,false,displayStats);
        
        esri.arcgis.gmaps.Config.proxyUrl = "proxy.ashx";   
}

The online help provides a more detailed discussion on how to use Query and QueryTask with the JavaScript APIs. Or, go here to see a short (4 min.) video demo.