Spatial and Attribute Queries with the ArcGIS Server JavaScript API
With the ArcGIS Server Query Task you can perform attribute and spatial queries against data layers in a map service that has been exposed. You can also combine these query types to perform a combination attribute and spatial query. Some examples would perhaps be illustrative at this point. An attribute query might search for all land parcels with a valuation of greater than $100,000. A spatial query could be used to find all land parcels that intersect a 100 year floodplain, and a combination query might search for all land parcels with a valuation of greater than $100,000 and whose geometry intersects the 100 year floodplain. In this post we’ll take a look at the mechanics of querying data from a map service using the ArcGIS Server JavaScript API.
As you’ll see with most tasks in the ArcGIS Server JavaScript API, queries are performed using a sequence of objects that typically include input to the tasks, execution of the tasks, and a result set returned from the operation as seen in the figure below.
The input to your query is stored in a Query object which contains various parameters that can be set for the query. The QueryTask object executes the task using the input provided in the Query object, and the result set is stored in a FeatureSet object which contains an array of Graphic features.
Query Object
As I have already mentioned, queries in the JavaScript API are essentially composed of three objects: Query, QueryTask, and FeatureSet. A Query object provides input to the QueryTask object and can include things like the query geometry, and spatial relationship for spatial queries or a ‘where clause’ for an attribute query. The Query object can also include optional properties such as the fields (outFields) that will be returned with the records, the output spatial reference, and whether to return geometry with the results.
The ‘queryGeometry’ property is used to input a geometry that will be used in a spatial query and will be a point, line, or polygon geometry. The complementary ‘spatialRelationship’ property can be set to one of the constants you see in the figure below.
The ‘where’ and ‘text’ properties are used to define an attribute query. The only difference being that the ‘text’ property is shorthand for a where clause using ‘like’.
In the code example below you can see how a Query object is created. Here, we are defining a spatial query which is evident from the use of the ‘geometry’ and ‘spatialRelationship’ properties. In addition, we have also specified that the features returned as a result of the query should include the geometry and also the fields that will be returned. This is a spatial query only; no attribute query has been defined with either the ‘where’ or ‘text’ properties.
However, we could easily include an attribute query as seen below through the use of the ‘where’ property. Here we are simply performing an attribute query to find records where the value of the ‘POP2007’ field is greater than the variable ‘population’.
QueryTask Object
A QueryTask object is used to execute a query against a layer in a map service. This QueryTask object needs the input parameters which are defined within a Query object as we saw in the section above. Once these input parameters have been defined they are passed into the QueryTask.execute() method which submits the query task to ArcGIS Server. The creation of an instance of QueryTask needs to point to a specific data layer within a map service as you can see in the code example below.
In this case we are defining that our query will execute against layer ‘1’ which is the Census Block Group layer from the ESRI_Census_USA map service as you can see from examining the ArcGIS Services Directory.
Now that an instance of QueryTask has been created we can call the QueryTask.execute() method, passing in the Query object we have already created.
FeatureSet Object
The query is then executed on the server. A FeatureSet object containing the results of the query is then passed back into a callback function. In this case ‘dojo.connect’ has been used to define an event handler for the ‘onComplete’ event for our QueryTask. The FeatureSet object is passed into this function as the variable ‘fset’.
This FeatureSet can then be processed for display on a map or as a tabular display on your web page. The FeatureSet is nothing more than an array of Graphic which you can plot on your map.
Example:
ESRI provides a great example of a spatial query here.
More Information
For more information on the ArcGIS Server JavaScript API you may wish to consider our “Mastering the ArcGIS Server JavaScript API” course which covers this topic among many others. Our next session begins October 5th and ends November 13th. It’s not too late to register! Contact eric at geospatialtraining.com for more information.
