QueryTask

AMD: require(["esri/tasks/QueryTask"], (QueryTask) => { /* code goes here */ });
ESM: import QueryTask from "@arcgis/core/tasks/QueryTask";
Class: esri/tasks/QueryTask
Inheritance: QueryTask Task Accessor
Since: ArcGIS API for JavaScript 4.0
Deprecated since version 4.20. Use query instead.

Executes different types of query operations on a layer. The most common method used in this class is execute(), which executes the query as defined in the Query object that is passed as a parameter to the function. QueryTask.execute() returns a Promise that resolves to a FeatureSet, which contains the features in the layer that satisfy the Query.

With QueryTask, you can also obtain the number of features that satisfy the query, the extent of features, related features or records associated with a feature, attachments for features or the featureIds of features.

For example, when working with a feature layer of world cities, to obtain a FeatureSet of cities with a population greater than one million people, use the following code:

require(["esri/tasks/QueryTask", "esri/tasks/support/Query"], function(QueryTask, Query){
  let citiesLayerUrl = " ... "; // Represents the REST endpoint for a layer of cities.
  let queryTask = new QueryTask({
    url: citiesLayerUrl
  });
  let query = new Query();
  query.returnGeometry = true;
  query.outFields = ["*"];
  query.where = "POP > 1000000";  // Return all cities with a population greater than 1 million

  // When resolved, returns features and graphics that satisfy the query.
  queryTask.execute(query).then(function(results){
    console.log(results.features);
  });

  // When resolved, returns a count of the features that satisfy the query.
  queryTask.executeForCount(query).then(function(results){
    console.log(results);
  });

});
See also:

Constructors

new QueryTask(properties)
Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
Stringmore details

The name of the class.

more detailsAccessor
Stringmore details

Specify the geodatabase version to query.

more detailsQueryTask
Objectmore details

The options to be used for data requests.

more detailsTask
Stringmore details

The ArcGIS Server REST service URL (usually of a Feature Service Layer or Map Service Layer) for use in a task.

more detailsTask

Property Details

declaredClass Stringreadonly inherited
Since: ArcGIS API for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

gdbVersion String

Specify the geodatabase version to query.

requestOptions Object inherited

The options to be used for data requests. These options can also be controlled through the requestOptions method parameter.

The ArcGIS Server REST service URL (usually of a Feature Service Layer or Map Service Layer) for use in a task.

Method Overview

Name Return Type Summary Class
Promise<FeatureSet>more details

Executes a Query against the layer specified in the url.

more detailsQueryTask
Promise<Object>more details

Query information about attachments associated with features from a feature layer specified in the url.

more detailsQueryTask
Promise<Number>more details

Gets a count of the number of features that satisfy the input query.

more detailsQueryTask
Promise<Object>more details

Gets the extent of the features that satisfy the input query.

more detailsQueryTask
Promise<Number[]>more details

Executes a Query against the layer specified in the url.

more detailsQueryTask
Promise<Object>more details

Executes a RelationshipQuery against the layer or table specified in the url.

more detailsQueryTask

Method Details

execute(query, requestOptions){Promise<FeatureSet>}

Executes a Query against the layer specified in the url. The result is returned as a FeatureSet, which can be accessed using the .then() method. A FeatureSet contains an array of Graphic features, which can be added to the map. This array will not be populated if no results are found.

Parameters:
query Query autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<FeatureSet> When resolved, a FeatureSet containing an array of graphic features is returned.
Example:
require([
  "esri/tasks/support/Query", "esri/tasks/QueryTask", ...
], function(Query, QueryTask, ... ) {
  let query = new Query();
  let queryTask = new QueryTask( ... );
  query.where = "STATE_NAME = 'Washington'";
  query.outSpatialReference = { wkid:102100 };
  query.returnGeometry = true;
  query.outFields = [ "CITY_NAME" ];
  queryTask.execute(query).then(function(results){
    // Results.graphics contains the graphics returned from query
  });
  ...
});
executeAttachmentQuery(attachmentQuery, requestOptions){Promise<Object>}
Since: ArcGIS API for JavaScript 4.9

Query information about attachments associated with features from a feature layer specified in the url. It will return an error if the layer's capabilities.data.supportsAttachment is set to false.

Parameters:
attachmentQuery AttachmentQuery autocast
Autocasts from Object

Specifies the attachment parameters for query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<Object> When resolved, returns an object containing AttachmentInfos grouped by the source feature objectIds.
See also:
executeForCount(query, requestOptions){Promise<Number>}

Gets a count of the number of features that satisfy the input query.

Parameters:
query Query autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<Number> When resolved, the result is the number of features that satisfy the input query.
Example:
require([
  "esri/tasks/QueryTask", ...
], function(QueryTask, ... ) {
  let queryTask = new QueryTask( ... );
  queryTask.executeForCount({  // autocasts as new Query()
     where: "POP90_SQMI &lt; 100"
  }).then(function(count){
    console.log(count, " features matched the input query");
  }, function(error){
       console.log(error); // Will print error in console if unsupported layers are used
     });
});
executeForExtent(params, requestOptions){Promise<Object>}

Gets the extent of the features that satisfy the input query. The count of features that satisfy the input query is returned upon resolution as well.

Parameters:
params Query

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<Object> When resolved, returns the extent and count of the features that satisfy the input query. See the object specification table below for details.
Property Type Description
count number The number of features that satisfy the input query.
extent Extent The extent of the features that satisfy the query.
executeForIds(query, requestOptions){Promise<Number[]>}

Executes a Query against the layer specified in the url. The result is an array of the object IDs of features that satisfy the input query.

Parameters:
query Query autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<Number[]> When resolved, the result is an array of object IDs for features that satisfy the input query.
Example:
require([
  "esri/tasks/QueryTask", ...
], function(QueryTask, ... ) {
  let queryTask = new QueryTask( ... );
  queryTask.executeForIds({  // autocasts as new Query()
     where: "region = 'Southern California'"
  }).then(function(results){
    console.log(results);  // an array of object IDs
  });
  ...
});
executeRelationshipQuery(relationshipQuery, requestOptions){Promise<Object>}

Executes a RelationshipQuery against the layer or table specified in the url. If the query is successful, the returned results are FeatureSets grouped by source layer or table objectIds.

Parameters:
relationshipQuery RelationshipQuery autocast
Autocasts from Object

Specifies relationship parameters for querying related features or records from a layer or a table.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns:
Type Description
Promise<Object> When resolved, the results are FeatureSets grouped by source layer or table objectIds. Each FeatureSet contains an array of Graphic features including the values of the fields requested by the user.
Example:
// specify relationship query parameter
const query = new RelationshipQuery({
  outFields: ["*"],
  relationshipId: relationshipId,
  objectIds: [385, 416]
});

// query related features that meet the query parameters
queryTask.executeRelationshipQuery(query).then(function (results) {
  console.log("queryTask results", results);
})
.catch(function (error) {
  console.log("query task error", error);
});

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.