Hide Table of Contents
esri/plugins
esri/process
esri/toolbars
esri/workers
Class: QueryTask
[ AMD Module Require | Legacy Module Require ]

require(["esri/tasks/QueryTask"], function(QueryTask) { /* code goes here */ });

Description

(Added at v1.0)
Executes a query operation on a layer resource of a map service exposed by the ArcGIS Server REST API.

Samples

Search for samples that use this class.

Constructors

NameSummary
new QueryTask(url, options?)Creates a new QueryTask object used to execute a query on the layer resource identified by the url.

Properties

NameTypeSummary
urlStringURL to the ArcGIS Server REST resource that represents a map service layer.

Methods

NameReturn typeSummary
execute(parameters, callback?, errback?)DeferredExecutes a Query against an ArcGIS Server map layer.
executeForCount(query, callback?, errback?)DeferredGet a count of the number of features that satisfy the input query.
executeForExtent(query, callback?, errback?)DeferredGet the extent of the features that satisfy the input query.
executeForIds(parameters, callback?, errback?)DeferredExecutes a Query against an ArcGIS Server map layer.
executeRelationshipQuery(parameters, callback?, errback?)DeferredExecutes a RelationshipQuery against an ArcGIS Server map layer (or table).

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
complete
{
  featureSet: <FeatureSet>
}
Fires when the query operation is complete.
error
{
  error: <Error>
}
Fires when an error occurs when executing the task.
execute-for-count-complete
{
  count: <Number>
}
Fires when the query for the count is complete.
execute-for-extent-complete
{
  count: <Number>,
  extent: <Object>
}
Fires when the query for the extent is complete.
execute-for-ids-complete
{
  objectIds: <Number[]>
}
Fires when the query on IDs is complete.
execute-relationship-query-complete
{
  featureSets: <FeatureSet[]>
}
Fires when the executeRelationshipQuery is complete.
Constructor Details

new QueryTask(url, options?)

Creates a new QueryTask object used to execute a query on the layer resource identified by the url.
Parameters:
<String> url Required URL to the ArcGIS Server REST resource that represents a layer in a service. An example is http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Portland/Portland_ESRI_LandBase_AGO/MapServer/1. For more information on constructing a URL, see The Services Directory and the REST API.
<Object> options Optional Optional parameters. See options list.
options properties:
<String> gdbVersion Optional Specify the geodatabase version to display. (As of v2.7). Requires ArcGIS Server service 10.1 or greater
Sample:
var queryTask = new esri.tasks.QueryTask("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StatesCitiesRivers_USA/MapServer/0");
Property Details

<String> url

URL to the ArcGIS Server REST resource that represents a map service layer. To obtain the URL, use Services Directory.
Method Details

execute(parameters, callback?, errback?)

Executes a Query against an ArcGIS Server map layer. The result is returned as a FeatureSet. If the query is successful, the user-specified callback function is invoked with the result. A FeatureSet contains an array of Graphic features, which can be added to the map using Map.graphics.add(). This array will not be populated if no results are found.
Return type: Deferred
Parameters:
<Query> parameters Required Specifies the attributes and spatial filter of the query.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution. (As of v1.3)
Sample:
var query = new esri.tasks.Query();
query.where = "STATE_NAME = 'Washington'";
query.outSpatialReference = {wkid:102100}; 
query.returnGeometry = true;
query.outFields = ["CITY_NAME"];
queryTask.execute(query, addPointsToMap);

executeForCount(query, callback?, errback?)

Get a count of the number of features that satisfy the input query. Valid only for layers published using ArcGIS Server 10 SP1 or greater. Layers published with earlier versions of ArcGIS Server return an error to the error callback. (Added at v2.1)
Return type: Deferred
Parameters:
<Query> query Required Specify the input query object.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the "execute-for-count-complete" event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution.
Sample:
var query = new esri.tasks.Query();
query.where = "POP90_SQMI < 100";
queryTask.executeForCount(query,function(count){
  dojo.byId("info").innerHTML = count + " features matched the input query";
},function(error){
  console.log(error);
});

executeForExtent(query, callback?, errback?)

Get the extent of the features that satisfy the input query. The count of features that satisfy the input query is returned as well. Valid only for hosted features services on arcgis.com. (Added at v3.9)
Return type: Deferred
Parameters:
<Query> query Required Specify the input query object.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the "execute-for-extent-complete" event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution.

executeForIds(parameters, callback?, errback?)

Executes a Query against an ArcGIS Server map layer. The result is an array of object IDs for features that satisfy the input query. (Added at v2.0)
Return type: Deferred
Parameters:
<Query> parameters Required Specifies the attributes and spatial filter of the query.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onExecuteForIdsComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution.
Sample:
  var query = new esri.tasks.Query();
  query.where = "region = 'Southern California'"; 
  queryTask.executeForIds(query,function(results){
    console.log(results);
  });

executeRelationshipQuery(parameters, callback?, errback?)

Executes a RelationshipQuery against an ArcGIS Server map layer (or table). The result is returned as a FeatureSet. If the query is successful, the user-specified callback function is invoked with the result. The result of this operation are featuresets grouped by source layer (or table) object IDs. Each featureset contains an array of Graphic features including the values for the fields requested by the user. This array will not be populated if no results are found. (Added at v2.0)
Return type: Deferred
Parameters:
<RelationshipQuery> parameters Required Specifies the attributes and spatial filter of the query.
<Function> callback Optional The function to call when the method has completed. The arguments in the function are the same as the onExecuteRelationshipQueryComplete event.
<Function> errback Optional An error object is returned if an error occurs on the Server during task execution.
Event Details
[ On Style Events | Connect Style Event ]

complete

Fires when the query operation is complete. Should be used in favor of onComplete. (Added at v3.5)
Event Object Properties:
<FeatureSet> featureSet Fires when the query operation is complete.
See also: execute()

error

Fires when an error occurs when executing the task. (Added at v3.6)
Event Object Properties:
<Error> error ArcGIS Server error message returned in a JavaScript error object.

execute-for-count-complete

Fires when the query for the count is complete. This event is only available for layers published using ArcGIS Server 10 SP1 or later. Should be used in favor of onExecuteForCountComplete. (Added at v3.5)
Event Object Properties:
<Number> count Fires when the query for the count is complete. This event is only available for layers published using ArcGIS Server 10 SP1 or later.

execute-for-extent-complete

Fires when the query for the extent is complete. Valid only for hosted features services on arcgis.com. (Added at v3.9)
Event Object Properties:
<Number> count Number of the features that satisfy the input query.
<Object> extent Extent of the features that satisfy the input query. At v3.10, the type will be Extent.

execute-for-ids-complete

Fires when the query on IDs is complete. Should be used in favor of onExecuteForIdsComplete. (Added at v3.5)
Event Object Properties:
<Number[]> objectIds Fires when the query on IDs is complete.
See also: executeForIds()

execute-relationship-query-complete

Fires when the executeRelationshipQuery is complete. Should be used in favor of onExecuteRelationshipQueryComplete. (Added at v3.5)
Event Object Properties:
<FeatureSet[]> featureSets Fires when the executeRelationshipQuery is complete.